Grok API quickstart: your first grok-4.7 call with curl, Python and TypeScript

What do I need before my first Grok API call?

Short answer: An xAI API key stored in the XAI_API_KEY environment variable, and one way to send the request: curl, the OpenAI SDK, xAI's xai-sdk for Python, or the Vercel AI SDK.

export XAI_API_KEY="your_api_key"

Install lines from xAI's quickstart:

Versions on 8 Oct 2026: xai-sdk 1.20.0 and @ai-sdk/xai 5.0.20. xAI has no official JavaScript SDK repo on GitHub, so TypeScript users go through the AI SDK or the OpenAI SDK.

Which environment variable does the Grok API use? XAI_API_KEY. The xai-sdk and the AI SDK provider read it automatically. With the OpenAI SDK you pass it yourself, for example api_key=os.getenv("XAI_API_KEY").

How do I call the Grok API with curl?

Short answer: Send a POST to https://api.x.ai/v1/responses with your key in an Authorization: Bearer header and a JSON body containing model and input.

curl https://api.x.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -d '{
    "model": "grok-4.7",
    "input": "In two sentences, what is the difference between a list and a tuple in Python?"
  }'

grok-4.7 always reasons before it answers, so a request can take a while. xAI's reasoning examples set a 3600-second timeout; with curl that's -m 3600.

How do I call Grok from Python?

Short answer: Install openai, create a client with base_url="https://api.x.ai/v1" and your XAI_API_KEY, and call the Responses API with model="grok-4.7".

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1",
    timeout=3600,  # xAI's reasoning examples use a 3600-second timeout
)

response = client.responses.create(
    model="grok-4.7",
    input="In two sentences, what is the difference between a list and a tuple in Python?",
)

print(response.output_text)

Can I use xAI's own Python SDK instead? Yes. xai-sdk is xAI's gRPC-based Python library. It reads XAI_API_KEY automatically and raises an error if the variable is missing.

How do I call Grok from TypeScript?

Short answer: With the Vercel AI SDK, install ai and @ai-sdk/xai, then pass xai.responses('grok-4.7') as the model. The OpenAI SDK also works with baseURL set to https://api.x.ai/v1.

import { xai } from '@ai-sdk/xai';
import { generateText } from 'ai';

const { text } = await generateText({
  model: xai.responses('grok-4.7'),
  prompt: 'In two sentences, what is the difference between a list and a tuple in Python?',
});

console.log(text);

The AI SDK provider reads XAI_API_KEY by default, so there's no key in the code.

Should I use the Responses API or Chat Completions?

Short answer: Use the Responses API for new code. Chat Completions still works with grok-4.7, but xAI calls it a legacy endpoint, and its comparison table labels it "Deprecated".

What differs:

• Encrypted reasoning. On the Responses API, grok-4.7 returns its reasoning in encrypted form (next section). Chat Completions doesn't.
• Cache routing. xAI recommends prompt_cache_key on the Responses API and the x-grok-conv-id header on Chat Completions.
• Stored responses. The Responses API stores responses for 30 days by default (store defaults to true).
• Anthropic SDK compatibility is fully deprecated, according to xAI's API reference.

Is Chat Completions deprecated on the xAI API? xAI uses both words. Its Chat Completions page calls it a legacy endpoint, and its API comparison table labels it "Deprecated". It still serves grok-4.7.

What is reasoning.encrypted_content, and what do I do with it?

Short answer: It's grok-4.7's reasoning in encrypted form. On the Responses API it comes back on every response, even when include doesn't ask for it. Pass it back unchanged in your next request.

This matters when you manage conversation history yourself: send the reasoning items back as you received them, so the model keeps its reasoning across turns. Two details from xAI's reasoning page:

• Returning it by default doesn't stop xAI from storing the thinking trace server-side for rehydration.
• Whether the response itself is stored is controlled by store, not by this default.

Encrypted outputs of server-side tools come back the same way.

Should I set prompt_cache_key?

Short answer: Yes. xAI's Grok 4.7 page says it highly recommends a prompt_cache_key on the Responses API (or the x-grok-conv-id header on Chat Completions), because without it "you often pay full input price on a cache-cold server".

Cached input costs $0.50 per million tokens instead of $2 below 200K prompt tokens, so a missed cache is a real cost. Cached tokens still count toward your tokens-per-minute limit. Details are in Grok API rate limits.

How do I control reasoning effort on grok-4.7?

Short answer: On the Responses API, send reasoning: {"effort": ...} with low, medium, high or xhigh; that's the form xAI's own examples use. The default is high, and reasoning can't be turned off on grok-4.7.

The top-level reasoning_effort field is also accepted on the Responses API, but xAI's API reference says it's only read when reasoning is unset. In xai-sdk, the setting is reasoning_effort.

• xhigh exists on grok-4.6 and later. On models without it, such as grok-4.5, xAI treats xhigh as high.
• grok-4.3 accepts none; grok-4.7 doesn't.
• On reasoning models, presencePenalty, frequencyPenalty and stop return an error, and logprobs is silently ignored on grok-4.20 and newer. See Grok function calling and structured outputs for the full list of quirks.

Can I turn off reasoning on Grok 4.7? No. xAI's reasoning docs say reasoning can't be disabled, and reasoning_effort defaults to high. Use low for the lightest setting.

How do I send images to Grok 4.7?

Short answer: grok-4.7 accepts jpg and png images up to 20 MiB each, with no limit on the number of images and in any order with text. xAI advises not storing request and response history on the server when you send images, or the request may fail.

On the Responses API, storage is controlled by store, which defaults to true. Keep that in mind when you build an image request. grok-4.7 returns text only; image generation uses the separate Imagine models.

How do I keep Grok requests in the US?

Short answer: Use the US regional endpoint, https://us.api.x.ai/v1. It costs 10% more per token and currently serves only grok-4.7 and grok-4.6.

• Price: 1.1 times the standard rate on input, output and cached input, including long-context rates. For grok-4.7 below 200K that's $2.20 input, $0.55 cached input and $6.60 output per million tokens.
• Scope: only grok-4.7 and grok-4.6, and no image, video or voice. The US guarantee doesn't cover Files, Collections or server-side tools.
• Python SDK: xai-sdk takes the bare host us.api.x.ai, not the full URL.

What do Grok API error codes mean?

Short answer: xAI documents 400, 401, 403, 404, 405, 415, 422 and 429 errors, plus a 202 status for deferred completions that aren't ready yet. A 429 means you've hit a rate limit; a 401 usually means a missing or wrong key.

Table: xAI API status codes (last checked 8 Oct 2026)

A few more things to know:

• In xai-sdk, a rate-limit error surfaces as grpc.StatusCode.RESOURCE_EXHAUSTED, per xAI's example.
• Outages are posted at status.x.ai, which also has an RSS feed at status.x.ai/feed.xml.
• A retired model name won't necessarily error: many older slugs now redirect to a newer model. See what happened to retired Grok models.
• Old Live Search code that sends search_parameters: see moving from Live Search to the search tools.

What does a 429 error mean on the Grok API? You've exceeded a rate limit. xAI sets limits per model in requests per second and tokens per minute, by spend tier, and "Exceeding any limit returns a 429 Too Many Requests error."

Can I call grok-4.7 somewhere other than the xAI API?

Short answer: Yes. xAI lists OpenRouter, Vercel and Cloudflare as gateways for Grok 4.7, and it also runs in Cursor and Grok Build. Each uses its own model ID string.

See Grok 4.7 model IDs and prices by channel.

FAQ

Which environment variable does the Grok API use?

XAI_API_KEY. The xai-sdk and the AI SDK provider read it automatically. With the OpenAI SDK you pass it yourself, for example api_key=os.getenv("XAI_API_KEY").

How do I call the Grok API with curl?

Send a POST to https://api.x.ai/v1/responses with your key in an Authorization: Bearer header and a JSON body containing model and input.

Can I use xAI's own Python SDK instead of the OpenAI SDK?

Yes. xai-sdk is xAI's gRPC-based Python library. It reads XAI_API_KEY automatically and raises an error if the variable is missing.

Is Chat Completions deprecated on the xAI API?

xAI uses both words. Its Chat Completions page calls it a legacy endpoint, and its API comparison table labels it "Deprecated". It still serves grok-4.7.

Can I turn off reasoning on Grok 4.7?

No. xAI's reasoning docs say reasoning can't be disabled, and reasoning_effort defaults to high. Use low for the lightest setting.

What does a 429 error mean on the Grok API?

You've exceeded a rate limit. xAI sets limits per model in requests per second and tokens per minute, by spend tier, and "Exceeding any limit returns a 429 Too Many Requests error."