The hard part of connecting to the Grok API is rarely writing the request itself. It usually comes down to three things: whether the key and the address belong together, which endpoint to use, and where to copy model names from. Get these right and the first call takes minutes. Get them wrong and the usual symptoms are 401, 404, or model not found.

This guide follows xAI's official documentation and walks through the account and key, the base URL, model names, curl, Python, streaming and function calling, error troubleshooting, and a migration checklist. Prices and available models change, so check xAI's official Models page and this site's model pricing before you connect.

Note: xAI and Grok are trademarks of their respective owners; OpenAI is a trademark of its owner. This article is for technical reference only.

1. Choose a path first: official console or compatible gateway

There are two common sources for a Grok API key: the official xAI console and a domestic gateway that exposes an OpenAI-compatible endpoint. The request formats are similar, but the account, payment, and base URL are different, and keys cannot be mixed between them.

Comparison Official xAI ZSQH AI Gateway
Console console.x.ai ai.zhongshangqihang.com
Base URL https://api.x.ai/v1 https://ai.zhongshangqihang.com/v1
Payment Methods supported by xAI RMB top-up; see the site for details
Best for Stable access and an overseas payment method Domestic access, unified billing, multi-model switching

Choose the path before you create a key. Putting an official key into a gateway address, or the reverse, usually produces a 401. The gateway sign-up page is here; whether you need a gateway depends on your network, payment, and invoicing requirements.

2. Six steps to create a key

  1. Register and sign in to the console. The official path is console.x.ai; the gateway path starts at the sign-up page.
  2. Complete billing setup or top up. Without available credit, a key may be created successfully but calls will fail.
  3. Open the API Keys page and create a key. Name it clearly with the project and runtime environment, for example prod-qa-2026-10.
  4. Copy the full key immediately and store it in a server-side environment variable or secrets manager. Most consoles show it only once at creation.
  5. Set quota, IP, or team permissions according to least privilege; there is no need to force options the console does not offer.
  6. Verify with a minimal request that the key, base URL, and model name all match.

Do not put keys in front-end code, Git repositories, or chat logs. Create separate keys for testing and production so that rotation does not affect every workload at once.

3. Base URL and endpoints: stop at /v1

The official base URL is https://api.x.ai/v1. Two points matter: the base URL ends at /v1, so do not append /chat/completions yourself; the specific endpoint is determined by the SDK or request path.

The official recommendation today is POST /v1/responses (the Responses API). The OpenAI-compatible POST /v1/chat/completions still works, but it is marked as legacy, and new features go to the Responses API first. New projects should use the Responses API directly. Existing OpenAI Chat Completions code can keep running, but accept that it is no longer the primary path.

A minimal curl request looks like this. Authentication uses Authorization: Bearer throughout:

export XAI_API_KEY="your-key"

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "Explain what an API gateway is in three sentences.",
    "store": false
  }'

store controls whether requests and responses are saved on the server. Official documentation states that Responses are stored for 30 days by default. When handling sensitive content, set store: false explicitly, and confirm that turning it off prevents conversation continuation via previous_response_id.

4. Filling in model names: copy the ID, do not guess

A model name is an API identifier, not the promotional name on a product page. The official Models page lists currently available IDs, context lengths, and billing tiers. The following examples come from the October 2026 documentation and are for format illustration only:

Model ID Context Common use
grok-4.7 500k General Q&A, coding, agents
grok-4.3 1M Long documents, long conversations
grok-4.20-0309-reasoning 1M Tasks that require explicit reasoning
grok-build-0.1 256k Coding and build workflows

Models are added and retired, and names often carry date suffixes. Before launch, copy the name from the official Models page or this site's model pricing; do not type it from memory. Models with a -reasoning suffix usually emit a reasoning trace, and their latency and cost structure differ from standard models, so validate them with a small traffic share first.

5. First Python call

xAI provides an official SDK and also supports the OpenAI SDK. Teams that already have OpenAI code can get running by changing base_url and api_key:

import os
from openai import OpenAI

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

response = client.responses.create(
    model="grok-4.7",
    input="Explain what an API gateway is in three sentences.",
    store=False,
)

print(response.output_text)

output_text is a convenience property provided by the SDK and works well for plain-text results. When you need to read reasoning, tool calls, or citations, iterate over response.output and check each item's type; do not assume text is always at a fixed index.

6. Streaming output and function calling

Streaming uses SSE: set "stream": true in the request and have the client read incremental chunks. Official documentation notes that reasoning models may generate for a long time, so raise the client timeout when streaming to avoid connections being closed early. Here is the OpenAI SDK calling the compatible endpoint:

stream = client.chat.completions.create(
    model="grok-4.7",
    messages=[{"role": "user", "content": "Explain SSE in three sentences."}],
    stream=True,
)

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

Function calling has five steps: define the tool's name, description, and JSON Schema; include the tool in the request; receive a function_call from the model; execute the function locally; return the result to the model for continued generation. In the Responses API, tool definitions are flat, with the core fields type: "function", name, description, and parameters.

Two details are easy to miss. In streaming mode, function-call arguments may arrive as one block rather than token by token. Server-side search tools may be billed separately by call volume, subject to the official pricing page. The more tools you define and the vaguer their descriptions, the more likely the model is to choose the wrong one, so tighten both the number of tools and their parameters first.

7. Common errors: read the status code first

Status Common cause What to do
401 Missing key, wrong key, or key and base URL do not match Check the Authorization header and whether the address pairs with the key
403 The account or key lacks permission, or regional and terms restrictions apply Check console permissions and account status
404 Wrong path or a model name that does not exist Verify /v1/responses and the model ID
400 / 422 Malformed fields in the request body Check fields against the API Reference
429 Request rate or concurrency exceeds a limit Retry with exponential backoff and lower concurrency
Timeout Long generation by a reasoning model, or a slow network path Raise the timeout, switch to streaming, and record timings

Insufficient balance does not always appear as a 429; the exact error code and message depend on the console and official documentation. A sensible troubleshooting order is: status code first, error message second, prompt last. No amount of prompt tuning will fix a wrong base URL.

8. Pre-launch migration checklist

  1. Put keys in server-side environment variables and confirm they never enter front-end bundles or logs.
  2. Fix the base URL and forbid hand-built endpoints in business code.
  3. Build a model-name mapping table recording old model, new model, context, and billing tier.
  4. Use /v1/responses for new projects; if an old project stays on Chat Completions, label it legacy and schedule migration.
  5. Unify timeout, retry, and cancellation logic across streaming and non-streaming paths.
  6. Set exponential backoff for 429 and 5xx, with no unlimited retries.
  7. Log request IDs, model, token usage, and latency for reconciliation and debugging.
  8. Roll out to one non-critical feature first and observe for a week before expanding.

Frequently asked questions

What exactly should the Grok API base URL be?

For the official service it is https://api.x.ai/v1. For a gateway, use the address shown in its console. Stop at /v1; do not include a specific endpoint.

Why can the OpenAI SDK call Grok?

xAI provides an OpenAI-compatible request structure, especially for Chat Completions. The Responses API can also be called through the OpenAI SDK's responses.create. Point base_url at xAI, but still follow xAI documentation for model names and some parameters.

Are Grok API and OpenAI API the same thing?

No. They are services from different companies with compatible interface shapes. Keys, billing, models, and data-handling policies all differ and cannot be mixed.

Do I have to use the Responses API?

New projects should. The official documentation has marked Chat Completions as legacy, and new capabilities arrive in the Responses API first. Existing systems can schedule migration according to cost; there is no need to switch overnight.

What is the most reliable way for a team in mainland China to connect?

First determine whether the problem is network access, payment, or compliance. If it is only access and settlement, evaluate an OpenAI-compatible gateway. If data cannot leave the internal network, consider private deployment or another architecture. Suitability depends on your actual constraints.

Summary

Grok API setup can be compressed into one sentence: choose the right key source, write the base URL only up to /v1, copy model names from the official page, and prefer the Responses API for new projects. Streaming, function calling, and error handling are details layered on that main path.

To manage multiple models and billing in one place, start at the sign-up page; for specific models and charges, refer to model pricing on this site.

Related reading: