May 25, 2026 · 5 min read

xAI API Complete Setup Guide: Authentication, Models, and First Request (2026)

The xAI API powers Grok Build and gives you direct access to xAI’s model family. This guide covers everything from account creation to your first API call, available models, pricing, and integration patterns.

Account setup

Step 1: Create an xAI account

Go to console.x.ai
Sign up with email or X (Twitter) account
Verify your email
Add a payment method (required for API access)

Step 2: Generate an API key

Navigate to API Keys in the console
Click Create new key
Name it (e.g., “grok-build-dev” or “ci-pipeline”)
Copy the key immediately. It won’t be shown again.

The key format: xai- followed by a long alphanumeric string.

Step 3: Set the environment variable

# Add to your shell profile (~/.bashrc, ~/.zshrc, etc.)
export XAI_API_KEY="xai-your-key-here"

# Reload
source ~/.zshrc

First API request

Using curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-3",
    "messages": [
      {"role": "system", "content": "You are a helpful coding assistant."},
      {"role": "user", "content": "Write a Python function that reverses a linked list."}
    ],
    "temperature": 0.7
  }'

Using Python

import requests
import os

response = requests.post(
    "https://api.x.ai/v1/chat/completions",
    headers={
        "Authorization": f"Bearer {os.environ['XAI_API_KEY']}",
        "Content-Type": "application/json"
    },
    json={
        "model": "grok-3",
        "messages": [
            {"role": "system", "content": "You are a helpful coding assistant."},
            {"role": "user", "content": "Write a Python function that reverses a linked list."}
        ],
        "temperature": 0.7
    }
)

print(response.json()["choices"][0]["message"]["content"])

Using the OpenAI SDK (compatible)

The xAI API is OpenAI-compatible. You can use the OpenAI SDK with a custom base URL:

from openai import OpenAI

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

response = client.chat.completions.create(
    model="grok-3",
    messages=[
        {"role": "system", "content": "You are a helpful coding assistant."},
        {"role": "user", "content": "Write a Python function that reverses a linked list."}
    ]
)

print(response.choices[0].message.content)

Using Node.js

import OpenAI from 'openai';

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

const response = await client.chat.completions.create({
  model: 'grok-3',
  messages: [
    { role: 'system', content: 'You are a helpful coding assistant.' },
    { role: 'user', content: 'Write a function that reverses a linked list in TypeScript.' }
  ]
});

console.log(response.choices[0].message.content);

Available models

Model	Context	Best for	Input cost	Output cost
grok-3	256K	Complex coding, reasoning, multi-step tasks	$1.00/1M	$3.00/1M
grok-3-fast	128K	Quick responses, simple tasks	$0.50/1M	$1.50/1M
grok-3-mini	64K	Lightweight tasks, high throughput	$0.10/1M	$0.30/1M

All models support:

Tool use (function calling)
Structured output (JSON mode)
Reasoning/chain-of-thought
Streaming responses
System messages

Streaming responses

from openai import OpenAI

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

stream = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "Explain async/await in JavaScript"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Tool use (function calling)

response = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "What's the weather in San Francisco?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {"type": "string", "description": "City name"}
                },
                "required": ["location"]
            }
        }
    }]
)

# Check if model wants to call a tool
if response.choices[0].message.tool_calls:
    tool_call = response.choices[0].message.tool_calls[0]
    print(f"Function: {tool_call.function.name}")
    print(f"Args: {tool_call.function.arguments}")

Structured output (JSON mode)

response = client.chat.completions.create(
    model="grok-3",
    messages=[{"role": "user", "content": "List 3 JavaScript frameworks with pros and cons"}],
    response_format={"type": "json_object"}
)

import json
data = json.loads(response.choices[0].message.content)

Using with Grok Build

Once your API key is set, Grok Build uses it automatically:

export XAI_API_KEY="xai-your-key-here"

# Interactive mode
grok

# Headless mode
grok -p "add error handling to src/api.ts" --output-format json

No additional configuration needed. Grok Build routes to the appropriate model based on task complexity (or you can override with --model grok-3).

Using via OpenRouter

If you prefer unified billing across multiple AI providers:

Get an OpenRouter API key from openrouter.ai
Use the xAI models through OpenRouter’s endpoint:

client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1"
)

response = client.chat.completions.create(
    model="xai/grok-3",
    messages=[{"role": "user", "content": "Hello"}]
)

Same pricing ($1/1M input, $3/1M output for grok-3), but billed through OpenRouter alongside your other model usage.

Rate limits

Tier	Requests/min	Tokens/min
Starter	10	100K
Pay-as-you-go	60	1M
Scale	300	5M

Rate limit headers are included in every response:

x-ratelimit-remaining-requests: 58
x-ratelimit-remaining-tokens: 980000
x-ratelimit-reset-requests: 2s

Error handling

Common error codes:

Code	Meaning	Fix
401	Invalid API key	Check `XAI_API_KEY` is set correctly
429	Rate limited	Back off and retry, or upgrade tier
400	Bad request	Check model name and message format
500	Server error	Retry with exponential backoff

import time

def call_with_retry(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="grok-3",
                messages=messages
            )
        except Exception as e:
            if "429" in str(e):
                time.sleep(2 ** attempt)
            else:
                raise

API key security

Never commit API keys to version control
Use environment variables or secret managers
Create separate keys for different environments (dev, CI, production)
Rotate keys periodically from the console
Set spending limits in the xAI console to prevent unexpected bills

# .env (add to .gitignore)
XAI_API_KEY=xai-your-key-here

# .gitignore
.env

For Grok Build pricing details, see Grok Build Pricing Explained. For the full CLI guide, see the Grok Build complete guide.

FAQ

Is the xAI API OpenAI-compatible?

Yes. The endpoint follows the OpenAI chat completions format. You can use the OpenAI Python/Node.js SDK by changing the base_url to https://api.x.ai/v1. Most OpenAI-compatible tools work without modification.

Can I use the same API key for Grok Build and direct API calls?

Yes. One XAI_API_KEY works for both Grok Build CLI and direct HTTP requests. Usage from both is billed to the same account.

What’s the difference between grok-3 and grok-3-fast?

grok-3 is the full model with 256K context, best reasoning, and highest quality output. grok-3-fast has 128K context, faster responses, and lower cost. Use grok-3-fast for simple tasks where speed matters more than depth.

Is there a free tier?

There is no free tier. New accounts can use API credits purchased from the console. The minimum top-up is low enough for testing, so you can experiment without a large upfront commitment.

How do I check my API usage and spending?

The xAI console at console.x.ai shows real-time usage, spending by model, and daily/monthly breakdowns. You can also set spending alerts.

Can I use xAI models in LangChain or other frameworks?

Yes. Any framework that supports OpenAI-compatible endpoints works. Set the base URL to https://api.x.ai/v1 and provide your API key. LangChain, LlamaIndex, Vercel AI SDK, and similar tools all support custom base URLs.