xAI Integration API
Server-side integration reference for Grok chat, Imagine (image & video), and Voice. Keys are server-only — never expose XAI_API_KEY to the browser. Official source of truth: docs.x.ai. Pin grok-imagine-image-2.0 + quality; do not leave grok-imagine-image-quality in templates after November 2, 2026.
Imagine image-quality slug retires November 2, 2026
Hero stills: grok-imagine-image-2.0 + quality medium. Cheap iterate: grok-imagine-image (1.0) or 2.0 low. Do not ride the retired slug.
Consumer Quality Mode on grok.com is grok-imagine-image-2.0 — not the retiring API slug grok-imagine-image-quality.
$0.02
1.0 still (list)
$0.08
2.0 medium 2K
$0.07 / s
Video 1.0 720p
$0.14 / s
Video 1.5 720p
Published API list prices (not draft rate cards). See Pricing for full tables and worked examples.
Spend responsibly
Every call uses the app owner’s personal quota and credits — including anonymous visitors on a deployed app. As of September 2026.
- Cap max_tokens; keep prompts small for visitor-facing chat.
- Image and especially video cost far more than chat per call.
- Iterate on grok-imagine-image (1.0). Hero plates on grok-imagine-image-2.0 quality medium.
- Pin quality on 2.0. Do not ride grok-imagine-image-quality after November 2.
- Never call in a loop, on every keystroke, or on page load.
- Cache or persist results instead of regenerating per visitor.
- Gate expensive media behind sign-in when the product allows.
- On API error: surface it; retry at most once.
The platform injects XAI_API_KEY in preview and deploy. Read it only inside createServerFn / server code. Do not create a .env file or use VITE_ prefixes.
Authorization headerBearer authentication
Every request uses the same header. Missing key → degrade gracefully.
Request / example
const apiKey = process.env.XAI_API_KEY;
if (!apiKey) {
return { ok: false, error: "AI is not available" };
}
fetch("https://api.x.ai/v1/chat/completions", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({ /* … */ }),
});Response
// 401 — invalid or missing key // 429 — rate limited / quota // 5xx — retry at most once, then surface error
Notes
- ·Key belongs to the app owner — every call spends their credits.
- ·Never call xAI from client components.
- ·If key is absent (rollout-gated), show “AI unavailable” UI instead of crashing.
HTTP & job status
Common response codes and async video states.
| Code | Meaning |
|---|---|
| 200 | Success — parse JSON or audio bytes as documented |
| 400 | Bad request — fix body/parameters |
| 401 | Unauthorized — missing or invalid API key |
| 429 | Rate limited or quota pressure — back off |
| 5xx | Server error — retry at most once, then surface |
| pending | Async video job still running — keep polling |
| completed | Async video ready — fetch URL |
| failed | Async job failed — show error, optional single retry |
Common integration errors
Failures from wrong key handling or spend patterns.
AI_NOT_AVAILABLE
XAI_API_KEY missing — show friendly empty state; do not crash.
KEY_EXPOSED_TO_CLIENT
Move fetch into createServerFn; never use VITE_ for the secret.
SPEND_ON_PAGE_LOAD
Remove automatic calls; require button/form submit; debounce.
VIDEO_WITHOUT_PLATE_LOCK
Generate and approve stills first; then start video jobs.
RETIRED_IMAGE_QUALITY_SLUG
Replace grok-imagine-image-quality with grok-imagine-image-2.0 and pin quality (low | medium). After Nov 2 the old slug is 2.0-low.
RETRY_STORM
On error surface message; retry at most once with backoff.
UNAUTHED_PUBLIC_MEDIA
Gate image/video generation behind sign-in for public apps.