# xAI (Grok) — API Research (Phase 0)

Researched: 2026-07-30. Sources: https://docs.x.ai/docs/models , https://docs.x.ai/docs/guides/chat , https://docs.x.ai/docs/guides/reasoning , https://docs.x.ai/docs/guides/live-search (now "Web Search tool"), https://docs.x.ai/docs/api-reference . Live model list verified against GET /v1/models with a real key on 2026-07-30 (/tmp/zyquo-probe/xai.json) — the live response includes aliases, context length, and pricing per model (authoritative).

# 1. Base URL & endpoints

• Base URL: https://api.x.ai/v1
• Chat completions (what Zyquo Cloud uses): POST /v1/chat/completions — OpenAI-compatible, fully supported (not deprecated).
• Responses API also exists (POST /v1/responses, plus GET/DELETE /v1/responses/{id}, POST /v1/responses/compact) — xAI's docs now lead with it, but chat completions remains concurrently supported.
• Deferred completions: GET /v1/chat/deferred-completion/{request_id}.
• Model listing: GET /v1/models (verified live; xAI-extended shape, see §8).

# 2. Authentication

• Header: Authorization: Bearer <XAI_API_KEY> (standard OpenAI-style).
• Content-Type: application/json. No version header.

# 3. Chat model catalog

Verified live 2026-07-30. Pricing per 1M tokens (input / cached input / output); xAI uses long-context tiered pricing: above the long_context_threshold (200K tokens for all current models) input/output prices double. All chat models: streaming ✅, function calling/tools ✅, structured outputs (json_schema) ✅, vision (image input) ✅ (image tokens priced same as text input).

Excluded (non-chat): grok-imagine-image, grok-imagine-image-quality (image gen, per-image pricing), grok-imagine-video, grok-imagine-video-1.5.

Notes:

• Older models (grok-4, grok-4-fast, grok-3, grok-2-vision, …) are gone from the live /models list — do not ship them in the catalog.
• Max output token caps are not published per model — mark unverified and default max_tokens conservatively (e.g. 16K); verify in Phase 7.
• logprobs is NOT supported on grok-4.20 and newer.

# 4. Request/response format

OpenAI-compatible — the shared OpenAICompatibleClient works as-is:

POST /v1/chat/completions
{
  "model": "grok-4.5",
  "messages": [
    {"role": "system", "content": "You are Grok."},
    {"role": "user", "content": [
      {"type": "text", "text": "Describe this image"},
      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,....", "detail": "high"}}
    ]}
  ],
  "reasoning_effort": "high",
  "stream": true,
  "stream_options": {"include_usage": true}
}

• Response: standard OpenAI chat.completion object (choices[].message.content, finish_reason, usage). Reasoning token counts appear under usage.completion_tokens_details.reasoning_tokens.
• Vision: OpenAI-style image_url content parts (https URL or base64 data URI; images up to 20 MiB).
• The Responses API additionally offers stored conversations (previous_response_id, 30-day retention, store: false to opt out) and include: ["reasoning.encrypted_content"] — not needed for chat completions.

# 5. Streaming format

• OpenAI-style SSE: unnamed data: lines of chat.completion.chunk objects with choices[].delta.content, finish_reason on the last content chunk, terminated by data: [DONE].
• stream_options: {"include_usage": true} → final chunk with usage (use for token/cost display).
• Reasoning models stream summarized reasoning alongside the answer; on chat completions this has historically surfaced as a delta.reasoning_content field for models that expose it (grok-4-era models did not expose raw thinking). Whether grok-4.5 emits reasoning_content chunks on /v1/chat/completions is unverified — the StreamingService should parse delta.reasoning_content if present and route it to the Thinking section; verify in Phase 7.

# 6. Special parameters

• reasoning_effort: "low" | "medium" | "high" (default high) on grok-4.5 and grok-4.20-multi-agent (where it controls the number of collaborating agents). Not applicable to grok-4.20-0309-non-reasoning. NOTE: xAI's value set differs from OpenAI's — no none/minimal/xhigh/max.
• Reasoning cannot be disabled on reasoning models; reasoning tokens are billed as output.
• Parameter restrictions on reasoning models: presence_penalty, frequency_penalty, and stop are rejected with errors — the client must not send them to Grok reasoning models. logprobs unsupported on 4.20+. temperature/top_p are accepted.
• Web search / live search: the legacy search_parameters live-search field has been superseded by a web_search tool (tools array; options: allowed_domains / excluded_domains (max 5, mutually exclusive), enable_image_understanding, enable_image_search) — documented for the Responses API; citations retrievable from results (docs: https://docs.x.ai/developers/tools/citations). Support via plain chat completions is unverified — treat search as a vNext feature for the xAI provider and verify in Phase 7.
• Deferred completions (async) exist but are out of scope.

# 7. Rate limits & errors

• Errors are generally OpenAI-shaped ({"error": {"message", "type", "code"}}), but xAI has also returned a flat {"code": "...", "error": "<message>"} shape on some 4xx responses — the error mapper should handle both shapes defensively.
• HTTP: 400 invalid request/params (including sending stop/penalties to reasoning models), 401 bad key, 403 blocked, 404 model, 429 rate limited, 5xx server. Retry 429/5xx with exponential backoff.
• Rate limits are per-model, per-team, shown in the xAI Console; not exhaustively documented publicly (marked unverified). Reasoning requests can run long — use generous read timeouts (xAI docs suggest up to 3600 s for reasoning models).

# 8. /models listing

• GET /v1/models exists (verified live). xAI extends the OpenAI shape — each entry: {"id", "aliases": [...], "context_length", "created", "object": "model", "owned_by": "xai", "prompt_text_token_price", "cached_prompt_text_token_price", "prompt_image_token_price", "completion_text_token_price", "prompt_text_token_price_long_context", "completion_text_token_price_long_context", "long_context_threshold"} wrapped in {"data": [...], "object": "list"}.
• Price unit: divide the integer by 10,000 to get USD per 1M tokens (e.g. 20000 → $2.00/1M; cross-checked against the official pricing table for grok-4.5/4.3/build-0.1).
• Image models instead carry image_price (per-image, same 10,000 divisor → USD per 10K images… treat image models as excluded).
• Zyquo Cloud can use this endpoint for dynamic refresh of context length AND live pricing — unique among the three providers. Filter out entries lacking completion_text_token_price (image/video models).

# Catalog guidance for ModelCatalog

• Default: grok-4.5. Fast/cheap: grok-4.20-0309-non-reasoning (or its grok-4.20-non-reasoning alias). Coding: grok-build-0.1.
• Prefer the stable aliases (grok-4.5, grok-4.3, grok-4.20, grok-4.20-non-reasoning, grok-4.20-multi-agent, grok-code-fast-1) as user-facing IDs.
• Gate per model: reasoning_effort (low/medium/high only), and strip stop/presence_penalty/frequency_penalty for reasoning models.