<!--
  xai.md
  Zyquo Cloud
  Author: Simon-Pierre Boucher
  Mail: contact@spboucher.ai
-->

# 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).

| Model ID | Key aliases | Context | Max output | $/1M in / cached / out (<200K) | ≥200K in/out | Vision | Reasoning | Status |
|---|---|---|---|---|---|---|---|---|
| `grok-4.5` | `grok-4.5-latest`, `grok-build-latest` | 500K | unverified | 2.00 / 0.30 / 6.00 | 4.00 / 12.00 | ✅ | ✅ (`reasoning_effort` low/medium/high, default high) | **Recommended default** — "most intelligent and fastest model"; knowledge cutoff 2026-02-01 |
| `grok-4.3` | `grok-4.3-latest`, **`grok-latest`** | 1M | unverified | 1.25 / 0.20 / 2.50 | 2.50 / 5.00 | ✅ | ✅ (unverified whether `reasoning_effort` accepted) | Previous flagship |
| `grok-4.20-0309-reasoning` | `grok-4.20`, `grok-4.20-reasoning`, `grok-4.20-reasoning-latest`, `grok-4.20-beta`, … | 1M | unverified | 1.25 / 0.20 / 2.50 | 2.50 / 5.00 | ✅ | ✅ (always reasons) | Older; reasoning variant |
| `grok-4.20-0309-non-reasoning` | `grok-4.20-non-reasoning`, `grok-4.20-non-reasoning-latest`, … | 1M | unverified | 1.25 / 0.20 / 2.50 | 2.50 / 5.00 | ✅ | ❌ | Older; fast non-reasoning variant |
| `grok-4.20-multi-agent-0309` | `grok-4.20-multi-agent`, `grok-4.20-multi-agent-latest`, … | 1M | unverified | 1.25 / 0.20 / 2.50 | 2.50 / 5.00 | ✅ | ✅ (`reasoning_effort` controls **agent count**, not depth) | Specialized multi-agent |
| `grok-build-0.1` | `grok-code-fast-1`, `grok-code-fast` | 256K | unverified | 1.00 / 0.20 / 2.00 | 2.00 / 4.00 | ✅ (price listed) | ✅ (fast coding reasoner, unverified effort support) | Coding/build model |

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:

```json
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.