How to Configure API Keys, Select Endpoints, and Implement Function Calling with the xAI Grok API

Software developers integrating xAI's Grok into their applications can connect within minutes because the xAI platform provides full OpenAI SDK compatibility alongside its native SDKs and REST endpoints. Operating at https://api.x.ai/v1, the Grok API enables developers to configure authentication via standard bearer tokens, choose between high-performance reasoning models like grok-4.7 and high-speed coding engines like grok-build-0.1, and execute multi-turn function calling to connect Grok with databases, internal microservices, and live external tools.

This guide provides an end-to-end walkthrough for setting up API keys, choosing the optimal model endpoint for your workload, and implementing robust tool calling in production.

1. Setting Up Authentication and API Keys

Access to the Grok API is managed through the xAI Console (https://console.x.ai).

Step 1: Generate the API Key

1. Sign up or log in at the xAI Console.
2. Ensure your account is loaded with API credits under Billing.
3. Navigate to the API Keys section (https://console.x.ai/team/default/api-keys) and click Create API Key.
4. Copy the generated key immediately and store it securely; the console will not display it again.

Step 2: Configure Environment Variables

Store your API key in an environment variable named XAI_API_KEY:

export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

In Node.js or Python projects, store it in your .env file:

XAI_API_KEY=xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 3: Initialize the Client SDK

Because xAI adheres to standard REST protocols and OpenAI schema compatibility, developers can use the official xai-sdk, the standard openai library, or TypeScript frameworks like Vercel AI SDK.

Python (OpenAI SDK):

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

Python (Native xai-sdk):

import os
from xai_sdk import Client

client = Client(api_key=os.getenv("XAI_API_KEY"))

Node.js / TypeScript (openai SDK):

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XAI_API_KEY,
  baseURL: "https://api.x.ai/v1",
});

2. Selecting Model Endpoints and Architectures

xAI exposes two primary HTTP inference endpoints, alongside a family of specialized models designed for specific latency, context window, and reasoning requirements.

Endpoint Protocol: /v1/responses vs /v1/chat/completions

• https://api.x.ai/v1/responses (Recommended Modern Endpoint): Designed for agentic workflows, structured inputs, multi-turn tool calling with state tracking (previous_response_id), and server-side tool orchestration.
• https://api.x.ai/v1/chat/completions (OpenAI Drop-In Compatible): Matches standard OpenAI chat completion schemas, making it effortless to redirect existing pipelines by changing baseURL and apiKey.

Language and Reasoning Models

Note: For applications requiring real-time audio conversations, text-to-speech, or image generation, xAI offers dedicated endpoints including grok-voice-think-fast-2.0 (Realtime Voice) and grok-imagine-image-2.0 (Imagine API).

3. Implementing Function Calling (Tool Calling)

Function calling allows Grok to act as an autonomous agent: rather than guessing information, the model generates structured arguments to call external APIs, fetch database records, or trigger background tasks.

The Tool Calling Execution Flow

1. Tool Definition: The developer passes an array of tools with JSON Schema definitions (name, description, parameters).
2. Model Evaluation: Grok analyzes the user prompt and determines whether a tool invocation is required.
3. Tool Call Emission: Grok responds with a tool_calls object containing the generated function name and JSON arguments.
4. Local Execution: Your application executes the function locally using the provided arguments.
5. Context Continuation: The function result is passed back to Grok, which formulates the final user-facing response.

Implementation Example (Python with OpenAI Client)

The following example demonstrates defining a custom schema, sending the request to the responses API, parsing the tool invocation, and returning the output to grok-4.7.

import os
import json
from openai import OpenAI

# 1. Initialize client
client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
)

# 2. Define custom tools using JSON schema
tools = [
    {
        "type": "function",
        "name": "fetch_user_account",
        "description": "Retrieve user profile, subscription tier, and active status by account ID.",
        "parameters": {
            "type": "object",
            "properties": {
                "account_id": {
                    "type": "string",
                    "description": "Unique user account identifier, e.g., 'usr_10294'"
                },
                "include_usage_stats": {
                    "type": "boolean",
                    "description": "Whether to return current billing cycle usage data.",
                    "default": False
                }
            },
            "required": ["account_id"]
        }
    }
]

# Mock local function implementation
def execute_fetch_user_account(account_id: str, include_usage_stats: bool = False):
    return {
        "account_id": account_id,
        "name": "Alex Mercer",
        "tier": "Enterprise",
        "status": "Active",
        "usage_tokens": 1420500 if include_usage_stats else None
    }

# 3. Initial user query
user_query = "Can you look up account usr_10294 and check if they are on an active Enterprise tier?"

response = client.responses.create(
    model="grok-4.7",
    input=[{"role": "user", "content": user_query}],
    tools=tools,
)

# 4. Handle function call dispatch
for item in response.output:
    if item.type == "function_call":
        func_name = item.name
        func_args = json.loads(item.arguments)
        call_id = item.call_id
        
        print(f"Model requested tool: {func_name} with args: {func_args}")
        
        if func_name == "fetch_user_account":
            tool_result = execute_fetch_user_account(**func_args)
            
            # 5. Return tool execution output back to Grok
            followup = client.responses.create(
                model="grok-4.7",
                input=[{
                    "type": "function_call_output",
                    "call_id": call_id,
                    "output": json.dumps(tool_result)
                }],
                tools=tools,
                previous_response_id=response.id,
            )
            
            # Print the final synthesized message
            for followup_item in followup.output:
                if followup_item.type == "message":
                    print("\nFinal Answer:\n", followup_item.content[0].text)

4. Key Rules and Advanced Capabilities

When engineering tool calling pipelines with Grok, keep these architectural specifics in mind:

• Strict Object Schema Root: In the parameters field of any tool, the root type must be "type": "object". Schemas that specify primitives, arrays, or non-object unions at the root will be rejected with an HTTP 400 error.
• Parallel Function Calling: By default, Grok models can emit multiple tool calls simultaneously when a query requires querying multiple endpoints at once. You can disable this behavior by setting parallel_tool_calls: false in the request payload.
• Explicit Tool Choice: Control model behavior with tool_choice:
  • "auto" (default): Model autonomously chooses whether to reply with text or trigger a tool.
  • "required": Model is forced to call at least one tool before answering.
  • "none": Disables function calling for that completion turn.
  • {"type": "function", "function": {"name": "fetch_user_account"}}: Forces invocation of an exact function.
• Combining Custom and Built-In Tools: Grok supports hybrid orchestration. You can include custom client-side functions alongside xAI's managed server-side tools (such as {"type": "web_search"} or {"type": "x_search"}). Server-side tools run automatically on xAI's infrastructure, whereas client tools pause for your application's input, giving you unified agentic control.
• Single-Chunk Streaming: When streaming tool responses, Grok returns the function call metadata in a single complete chunk rather than splitting JSON fragments across streams, simplifying client-side deserialization.

References

• Grok API Quickstart: Get Your API Key | SpaceXAI Docs
• Grok Models & Pricing | SpaceXAI Docs
• API Pricing | SpaceXAI Docs
• Function Calling | SpaceXAI Docs
• API Reference - REST API Reference | SpaceXAI Docs