Grok API

Summary

Official SpaceXAI API documentation. Build with Grok: chat, image and video generation, voice, tool calling, and structured outputs. Quickstarts, guides, and API reference.

Release history

1. docs update Aug 29, 2026 · issue 010

   Grok API adds Opus streaming for STT, SIP call transfer, batch image/video, multi-image generation, and audio-track control for video

   └──▷ TRY IT
   Stream compressed Opus audio from a bandwidth-constrained mobile client to the Grok STT WebSocket, saving ~90% bandwidth versus raw PCM.
   copy

   $ wss://api.x.ai/v1/stt?sample_rate=24000&encoding=opus&interim_results=true

   Transfer a live SIP caller to a destination number mid-conversation and inspect the synchronous outcome.
   copy

   $ curl -X POST https://api.x.ai/v1/realtime/calls/{call_id}/refer \
     -H 'Authorization: Bearer $XAI_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{"target_uri": "tel:+15551234567"}'

   Enable session resumption on the first SIP call so a later call can continue the same conversation.
   json copy

   {"type": "session.update", "session": {"resumption": {"enabled": true}}}

   • ›Adds encoding=opus parameter to the STT WebSocket endpoint (wss://api.x.ai/v1/stt) for compressed Opus audio streaming — roughly 4 KB/s at 24 kHz versus 48 KB/s for raw PCM; supports 8000, 16000, 24000, or 48000 Hz, mono only, one raw Opus packet per binary WebSocket frame.
   • ›Adds multichannel boolean parameter (default false) to the STT WebSocket for per-channel transcription of interleaved multichannel audio; requires channels ≥ 2 and is incompatible with encoding=opus.
   • ›Adds endpointing integer parameter (default 400 ms, range 0–5000) to the STT WebSocket to control silence duration before a speech_final=true event fires; set to 0 to fire on any VAD silence boundary.
   • ›Adds POST /v1/realtime/calls/{call_id}/refer endpoint to transfer a SIP caller to a tel: or sip: destination; returns 200 (transfer complete), 502 with SIP reason (rejected), 504 (timeout), 404 (no SIP participant), 400 (bad URI), or 500 (internal error).
   • ›Adds session resumption for Speech-to-Speech SIP calls via resumption.enabled: true in session.update; a later SIP call reconnects by opening wss://api.x.ai/v1/realtime?call_id={new_call_id}&conversation_id={saved_call_id} — history expires after 30 minutes of inactivity.
   +8 moreshow less

   • ›Adds n parameter (1–10) to the images API for multi-image generation in a single request; xAI Python SDK exposes sample() for one image and sample_batch(n=...) for batches.
   • ›Adds aspect_ratio parameter to image generation, including values 19.5:9, 9:19.5, 20:9, 9:20, 21:9, and 5:2; defaults to auto when omitted.
   • ›Adds resolution parameter to image generation supporting 1k (default) and 2k output sizes.
   • ›Adds quality parameter to image generation (e.g. 'low') to control output fidelity.
   • ›Adds response_format parameter to image generation (url default, or base64) to embed images directly without downloading.
   • ›Adds generate_audio boolean parameter to video generation; defaults to true (audio track included); pass False/false to produce a silent video.
   • ›Supports batch processing of image and video generation requests via /v1/images/generations, /v1/images/edits, and /v1/videos/generations endpoints in batch payloads using batch-enabled models such as grok-imagine-image-2.0 and grok-imagine-video-1.5.
   • ›Adds reference_audios array to video generation, accepting entries with voice_id values (e.g. 'eve', 'leo') to mix reference voices into generated video audio tracks.
2. 1.0.0 Aug 20, 2026 · issue 002

   Grok API now publishes an API — 43 endpoints across 1 area: V1

   • ›V1 (43 endpoints) — create, read, delete
3. snapshot-20260820 seen Aug 20, 2026 · issue 002

   Grok API snapshot-20260820 adds Grok 4.6, Grok Bot, video model upgrades, VAD tuning, Priority Processing, public file URLs, and more.

   └──▷ TRY IT
   Boost a latency-sensitive inference request to priority scheduling and confirm the tier that was applied.
   copy

   $ curl https://api.x.ai/v1/chat/completions \
     -H 'Authorization: Bearer $XAI_API_KEY' \
     -H 'Content-Type: application/json' \
     -d '{
       "model": "grok-4.6",
       "service_tier": "priority",
       "messages": [{"role": "user", "content": "Summarize this incident report."}]
     }'

   Tune Speech to Text to capture quiet telephony audio by lowering the VAD threshold.
   copy

   $ curl 'https://api.x.ai/v1/audio/transcriptions?vad_threshold=0.2' \
     -H 'Authorization: Bearer $XAI_API_KEY' \
     -F 'file=@call_recording.wav' \
     -F 'model=grok-speech-to-text'

   • ›Adds service_tier: "priority" parameter on Chat Completions and Responses endpoints to request higher scheduling priority per request; the response's service_tier field reports the tier actually applied, and priority rates are billed only when used.
   • ›Adds vad_threshold parameter (streaming query param and batch multipart field) to the Speech to Text API to tune the voice-activity gate — lower values capture quieter or noisier speech, and 0 disables the gate entirely.
   • ›Adds smart_turn query parameter to the streaming Speech to Text API for ML-based end-of-turn detection, with smart_turn_timeout to set a maximum silence fallback.
   • ›Adds image_file_id, video_file_id, and reference_image_file_ids fields across every Imagine endpoint to reference Files API stored assets directly as inputs without re-uploading.
   • ›Adds storage_options field on Imagine requests to persist generated assets to Files API storage; pair with storage_options.public_url to publish a shareable link in one round trip.
   +13 moreshow less

   • ›Adds enable_image_search to Web Search to let Grok search directly for images, with results returned as Markdown image embeds.
   • ›Adds cost_in_usd_ticks field to the usage object in every API response (chat completions, Responses API, image generation, video generation, and streaming) for per-request cost tracking.
   • ›Adds expires_after and expires_at fields to Files API uploads to set automatic expiration and deletion policies.
   • ›Adds Public URLs for Files API — any stored file can be turned into a permanent, unauthenticated URL, revocable at any time or with auto-expiry between 1 hour and 30 days.
   • ›Adds Context Compaction API to shrink long conversations into a reusable shorter context, reducing cost and time-to-first-token on long agent loops.
   • ›Adds WebSocket Responses API mode for driving the Responses API over a single long-lived WebSocket connection for lower end-to-end latency on tool-heavy agent workloads.
   • ›New grok-4.6 model with 500k context window, text and image inputs, no text output limit, and reasoning_effort supporting low, medium, high (default), and xhigh; priced at $2/$0.50/$6 per 1M tokens (input/cached/output) below 200k prompt tokens, $4/$1/$12 above.
   • ›Introduces Grok Bot — durable AI teammates running on a persistent cloud computer with messaging, approvals, connectors, and routines.
   • ›Adds grok-imagine-video-1.5 model supporting text-to-video, image-to-video, and reference-to-video (with optional preset voices) and native 1080p for T2V and I2V.
   • ›Adds grok-voice-think-fast-2.0 for Speech to Speech; grok-voice-latest will route to this model starting August 5, 2026.
   • ›New Custom Voices capability: clone a voice from a short audio clip and use it across Text-to-Speech and Speech to Speech APIs, managed from the xAI console.
   • ›Batch API now supports image generation, image editing, and video generation in addition to chat completions, including server-side and client-side function tools; image and video URLs in batch results expire after 1 hour.
   • ›Batch API now accepts JSONL file uploads via the Files API, supporting chat, image, and video requests in a single file.