| name | grok-api-sdk |
| description | Build applications using the xAI Grok API. Use when the user needs to call Grok models via API — text generation, reasoning, vision/image understanding, image generation, structured outputs, batch processing, streaming, function calling, or any xAI SDK integration. Covers both the Python xAI SDK (xai-sdk) and REST/TypeScript/JavaScript (OpenAI-compatible). Triggers on mentions of 'Grok API', 'xAI API', 'xai-sdk', 'grok-4', 'grok-3', or requests to integrate Grok into applications. |
xAI Grok API & SDK Skill
Quick Reference
Connection Setup
Base URL: https://api.x.ai
Auth header: Authorization: Bearer <XAI_API_KEY>
Python SDK: pip install xai-sdk — uses gRPC, covers all features
OpenAI SDK compatible: set base_url="https://api.x.ai/v1"
JS/TS AI SDK: @ai-sdk/xai via Vercel AI SDK
Model Selection
| Model | Type | Use when |
|---|
grok-4 | Reasoning (always-on) | Highest quality, complex tasks |
grok-4-1-fast-reasoning | Reasoning, fast | Agentic tool calling, fast + cheap |
grok-4-1-fast-non-reasoning | Non-reasoning, fast | Instant responses, lowest latency |
grok-3-mini | Reasoning (configurable) | Budget tasks, reasoning_effort control |
grok-imagine-image | Image generation | Text-to-image, image editing |
Knowledge cutoff: November 2024. Use web_search/x_search tools for current data.
Critical Rules
- Reasoning models reject these params (will error):
presencePenalty, frequencyPenalty, stop
reasoning_effort — ONLY grok-3-mini supports it ("low" / "high"). Grok 4 errors.- Encrypted reasoning — For grok-4: set
include: ["reasoning.encrypted_content"] in REST, or use_encrypted_content=True in SDK. Without this you get no reasoning traces.
- Image understanding + storage — Set
store_messages=False (SDK) or "store": false (REST) when sending images, otherwise requests may fail.
- Only one system message — must be first.
developer role is alias for system.
- Structured outputs —
allOf not supported. No minLength/maxLength on strings. No minItems/maxItems on arrays.
- Batch API — 50% off pricing. No server-side tools, no function calling, no image/video generation models. Text/language models only (vision input IS supported).
- Image input limits — 20 MiB max,
jpg/jpeg/png only, no limit on count.
- Responses API is preferred over Chat Completions. Supports stateful conversations (30-day retention).
- Timeout — Always set
timeout=3600 for reasoning models. They can take minutes.
Responses API (Preferred)
The Responses API supports stateful conversations — history stored server-side for 30 days.
Conversation chaining: Pass previous_response_id instead of resending full history. You're still billed for full context, but cached tokens reduce cost.
Disable storage: store_messages=False (SDK) or "store": false (REST).
See PYTHON.md or TYPESCRIPT.md for code.
Structured Outputs
Guarantees model output matches your JSON schema. Supported by all language models.
Two approaches in Python SDK:
chat.parse(PydanticModel) → returns (Response, parsed_model) — auto parsingresponse_format=PydanticModel + chat.sample() → manual Model.model_validate_json(response.content)
REST/OpenAI SDK: Use response_format: { type: "json_schema", json_schema: { name: "...", schema: {...} } }
Supported types: string, number, integer, boolean, object, array, enum, anyOf.
NOT supported: allOf, minLength/maxLength, minItems/maxItems.
With tools — works on Grok 4 family only (grok-4-1-fast, grok-4-fast, non-reasoning variants).
See VISION_STRUCTURED.md for vision + structured output patterns.
Image Understanding (Vision)
Send images as input to language models. Images go in user message content as input_image blocks.
SDK: Use image() helper — user("prompt text", image(image_url=url, detail="high"))
REST: Content array with {"type": "input_image", "image_url": "...", "detail": "high"}
Accepts both URLs and data:image/jpeg;base64,... data URIs.
Image Generation
Model: grok-imagine-image. Flat per-image pricing. Max 10 per request.
SDK: client.image.sample(prompt=..., model="grok-imagine-image")
Editing: Pass image_url= param with source image.
Batch gen: client.image.sample_batch(prompt=..., n=4)
URLs are temporary — download immediately. OpenAI SDK images.edit() NOT supported (use xAI SDK or direct HTTP).
Batch API
50% off all token types. No rate limit impact. Typically completes within 24 hours.
Workflow: Create batch → Add requests → Poll status → Retrieve results
Limits: 1 batch/sec creation rate, 100 add-requests calls per 30 seconds, 25MB per request payload, >1M requests may throttle.
NOT supported in batch: Server-side tools, function calling, image/video generation.
See BATCH.md for complete examples.
Tools Pricing
| Tool | Cost / 1k calls |
|---|
| web_search | $5 |
| x_search | $5 |
| code_execution | $5 |
| attachment_search | $10 |
| collections_search | $2.50 |
| view_image / view_x_video / MCP | Token-based |
Server-Side Tools (Agentic)
Grok can autonomously use server-side tools. The model decides when and how to call them — you just enable them.
| Tool | SDK Name | REST Name | Cost | Notes |
|---|
| Web Search | web_search() | web_search | $5/1k calls | Internet search + page browsing |
| X Search | x_search() | x_search | $5/1k calls | Posts, users, threads on X/Twitter |
| Code Execution | code_execution() | code_interpreter | $5/1k calls | Sandboxed Python execution |
| Collections Search | collections_search() | collections_search | $2.50/1k calls | RAG over uploaded docs |
| View Image | — | — | Token-based | Image analysis within search results |
| View X Video | — | — | Token-based | Video analysis within X posts |
| Remote MCP | — | mcp | Token-based | Custom MCP servers |
Key rules:
- Tools can be combined — pass multiple in the
tools list
- Not available in Batch API — server-side tools are excluded
- Agent may make multiple calls per request — costs scale with complexity
- Citations — automatically returned when using search tools. See CITATIONS.md.
Quick example (Python SDK):
from xai_sdk.tools import web_search, x_search, code_execution
chat = client.chat.create(
model="grok-4-1-fast-reasoning",
tools=[web_search(), x_search(), code_execution()],
)
See pattern files for full examples: X_SEARCH.md, CODE_EXECUTION.md, CITATIONS.md.
REST Endpoint Quick Reference
| Endpoint | Method | Description |
|---|
/v1/responses | POST | Create response (preferred) |
/v1/responses/{id} | GET/DELETE | Retrieve/delete stored response |
/v1/chat/completions | POST | Legacy chat completions |
/v1/images/generations | POST | Generate images |
/v1/images/edits | POST | Edit images |
/v1/batches | POST/GET | Create/list batches |
/v1/batches/{id} | GET | Get batch status |
/v1/batches/{id}/requests | GET/POST | List/add batch requests |
/v1/batches/{id}/results | GET | Get batch results |
/v1/batches/{id}:cancel | POST | Cancel batch |
/v1/models | GET | List models |
