spb/zyquo-cloud Public MIT

1<!--2  xai.md3  Zyquo Cloud4  Author: Simon-Pierre Boucher5  Mail: contact@spboucher.ai6-->78# xAI (Grok) — API Research (Phase 0)910Researched: 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).1112## 1. Base URL & endpoints1314- Base URL: `https://api.x.ai/v1`15- Chat completions (what Zyquo Cloud uses): `POST /v1/chat/completions` — OpenAI-compatible, fully supported (not deprecated).16- 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.17- Deferred completions: `GET /v1/chat/deferred-completion/{request_id}`.18- Model listing: `GET /v1/models` (verified live; xAI-extended shape, see §8).1920## 2. Authentication2122- Header: `Authorization: Bearer <XAI_API_KEY>` (standard OpenAI-style).23- `Content-Type: application/json`. No version header.2425## 3. Chat model catalog2627Verified 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).2829| Model ID | Key aliases | Context | Max output | $/1M in / cached / out (<200K) | ≥200K in/out | Vision | Reasoning | Status |30|---|---|---|---|---|---|---|---|---|31| `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 |32| `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 |33| `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 |34| `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 |35| `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 |36| `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 |3738Excluded (non-chat): `grok-imagine-image`, `grok-imagine-image-quality` (image gen, per-image pricing), `grok-imagine-video`, `grok-imagine-video-1.5`.3940Notes:41- 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.42- Max output token caps are not published per model — mark unverified and default `max_tokens` conservatively (e.g. 16K); verify in Phase 7.43- `logprobs` is NOT supported on grok-4.20 and newer.4445## 4. Request/response format4647OpenAI-compatible — the shared `OpenAICompatibleClient` works as-is:4849```json50POST /v1/chat/completions51{52  "model": "grok-4.5",53  "messages": [54    {"role": "system", "content": "You are Grok."},55    {"role": "user", "content": [56      {"type": "text", "text": "Describe this image"},57      {"type": "image_url", "image_url": {"url": "data:image/jpeg;base64,....", "detail": "high"}}58    ]}59  ],60  "reasoning_effort": "high",61  "stream": true,62  "stream_options": {"include_usage": true}63}64```6566- Response: standard OpenAI `chat.completion` object (`choices[].message.content`, `finish_reason`, `usage`). Reasoning token counts appear under `usage.completion_tokens_details.reasoning_tokens`.67- Vision: OpenAI-style `image_url` content parts (https URL or base64 data URI; images up to 20 MiB).68- 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.6970## 5. Streaming format7172- 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]`.73- `stream_options: {"include_usage": true}` → final chunk with `usage` (use for token/cost display).74- 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.7576## 6. Special parameters7778- `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`.79- Reasoning cannot be disabled on reasoning models; reasoning tokens are billed as output.80- **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.81- 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.82- Deferred completions (async) exist but are out of scope.8384## 7. Rate limits & errors8586- 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.87- 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.88- 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).8990## 8. /models listing9192- `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"}`.93- **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).94- Image models instead carry `image_price` (per-image, same 10,000 divisor → USD per 10K images… treat image models as excluded).95- 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).9697### Catalog guidance for ModelCatalog9899- 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`.100- 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.101- Gate per model: `reasoning_effort` (low/medium/high only), and strip `stop`/`presence_penalty`/`frequency_penalty` for reasoning models.102