spb/zyquo-cloud Public MIT

1<!--2  cerebras.md3  Zyquo Cloud4  Author: Simon-Pierre Boucher5  Mail: contact@spboucher.ai6-->78# Cerebras — Provider Research (Phase 0)910Researched 2026-07-30 against official docs (https://inference-docs.cerebras.ai) and a live11authenticated `GET /v1/models` probe (`/tmp/zyquo-probe/cerebras.json`). Cerebras runs inference on12wafer-scale hardware — its differentiator is **extreme speed** (1,000–3,000 output tokens/s), not13catalog breadth.1415---1617## 1. Base URL & Endpoints1819- **Base URL:** `https://api.cerebras.ai/v1`20- `POST /v1/chat/completions` — chat (used by Zyquo Cloud)21- `POST /v1/completions` — text completion22- `GET /v1/models`, `GET /v1/models/{id}` — model listing2324Reference: https://inference-docs.cerebras.ai/api-reference/chat-completions2526## 2. Authentication2728`Authorization: Bearer <CEREBRAS_API_KEY>` — standard Bearer (key from cloud.cerebras.ai console). Confirmed.2930## 3. Chat Model Catalog3132Live `/models` probe returned exactly **3 models** — and the docs models page33(https://inference-docs.cerebras.ai/models/overview) lists the **same 3** public models, so there is34**no discrepancy** between `/models` and docs today (older models like llama-3.3-70b, qwen-3-*, and35llama3.1-8b no longer appear in either — treat as removed). Additional models exist only via paid36Dedicated Endpoints. Context windows are **tier-dependent** (free vs paid).3738| Model ID (exact) | Status | Context (free / paid) | Max output (free / paid) | $ In / $ Out per 1M | Speed | Caps |39|---|---|---|---|---|---|---|40| `gpt-oss-120b` | Production | 65k / 131k | 32k / 40k | 0.35 / 0.75 (docs page; a search snippet also showed 0.25/0.69 — treat exact price as needs-confirmation in Phase 7) | ~3,000 tok/s | Reasoning (`reasoning_effort`, default `medium`), tools, structured outputs, streaming, prompt caching |41| `gemma-4-31b` | Preview | 65k / 131k | 32k / 40k | 0.99 / 1.49 | ~1,850 tok/s | **Vision** (base64 images only), tools (parallel), structured outputs (constrained decoding), reasoning (off by default, enable via `reasoning_effort`), streaming, prompt caching |42| `zai-glm-4.7` | Preview — **deprecated 2026-08-17** | 64k / 131k | 40k / 40k | 2.25 / 2.75 | ~1,000 tok/s | Reasoning (on by default), tools (parallel, `strict: true`), structured outputs, streaming, prompt caching |4344Notes:45- `zai-glm-4.7` is scheduled for discontinuation on **August 17, 2026** (migration guide: https://inference-docs.cerebras.ai/resources/glm-47-migration). Ship it flagged "deprecating soon" in `ModelCatalog`.46- `gemma-4-31b` image limits: max 2 images/request (free) or 10 (paid), 10 MB total, base64 PNG/JPEG data URIs only — **external image URLs not supported**; chat endpoint only.47- Note the probe listing order (`gemma-4-31b`, `gpt-oss-120b`, `zai-glm-4.7`) matches docs exactly.4849## 4. Request/Response Format5051OpenAI-compatible with notable deviations:5253- **`max_tokens` is NOT supported — use `max_completion_tokens`** (includes reasoning tokens). This is the biggest client-side difference; Zyquo Cloud's Cerebras path must map its max-tokens setting to `max_completion_tokens`.54- `temperature` range 0–2 (default 0); `top_p` 0–1; `stop` up to 4 sequences; `seed` for determinism; `frequency_penalty`/`presence_penalty`; `logit_bias`; `logprobs` (boolean) + `top_logprobs` (0–20).55- Roles: `system`, `user`, `assistant`, `tool`, plus `developer` (gpt-oss-120b only; `system` maps to developer-level).56- Reasoning models return chain-of-thought in **`choices[].message.reasoning`** (top-level field).57- Response includes extras: `time_info` (queue/prompt/completion/total seconds — great for a latency badge), `usage.prompt_tokens_details.cached_tokens`, `usage.completion_tokens_details.reasoning_tokens`.58- `n` (multiple completions) and `stream_options` are not documented (assume unsupported — unverified).59- Optional: `Content-Type: application/vnd.msgpack`, gzip request encoding, `queue_threshold` header (50–20000 ms) for flex/auto tiers.6061## 5. Streaming6263- `stream: true` → SSE `chat.completion.chunk` objects with `choices[].delta` (content, tool_calls, and `reasoning` deltas on reasoning models), terminated by `data: [DONE]`.64- **`usage` appears in the final streamed chunk** per the documented streaming response schema (no `stream_options.include_usage` needed — the parameter is not documented).65- Streams are extremely fast (up to ~3,000 tok/s) — Zyquo Cloud's renderer must batch UI updates (Phase 4.3 "no layout thrash" rule matters most here).6667## 6. Special Parameters6869- `reasoning_effort`: `low | medium | high | none`. gpt-oss-120b default `medium`; gemma-4-31b reasoning off by default (enable via this param; no `raw`/`hidden` formats); zai-glm-4.7 reasoning on by default.70- `clear_thinking` (boolean): whether prior turns' thinking content is included in prompt context — off by default, recommended on for agentic use (zai-glm-4.7).71- `response_format`: `text` | `json_object` | `json_schema` with **`strict: true` schema enforcement via constrained decoding** — Cerebras's structured outputs are genuinely strict.72- `tools`/`tool_choice` (`none|auto|required|named`) + `parallel_tool_calls` (default true); `strict: true` supported on tool schemas.73- `prediction` (predicted outputs), `prompt_cache_key` (grouping for prompt caching), `service_tier` (`priority|default|auto|flex`), `user`.74- Known quirks (docs): gpt-oss-120b may emit unexpected EOS with `min_tokens`, and may hallucinate tool calls outside schema (reprompt to correct).7576## 7. Rate Limits & Errors7778(https://inference-docs.cerebras.ai/support/rate-limits)7980- Measured on RPM/RPH/RPD **and** TPM/TPH/TPD — whichever trips first. **Dual token buckets:** uncached TPM and total TPM (total ≈ 3× uncached) — good caching effectively triples throughput.81- **Free Trial** ($5 credit): **5 RPM across all models, 30k TPM, 1M TPH, 1M TPD** — very tight; Zyquo Cloud error messages should mention upgrading when free-tier users hit 429.82- **Developer (pay-as-you-go):** `gpt-oss-120b` 1M TPM / 1,000 RPM; `zai-glm-4.7` 500k TPM / 500 RPM; no hourly/daily caps. (gemma-4-31b developer-tier numbers not published — unverified.)83- **Enterprise:** custom.84- 429 on limit, with the message stating which bucket (uncached vs total) was exceeded. Error bodies follow the OpenAI `{"error": {...}}` shape (message/type/param/code — shape unverified in fine detail; confirm in Phase 7).85- Free-tier context is also capped (65k vs 131k paid) — a context-length error on free tier may occur below the model's nominal window.8687## 8. `/models` Listing8889`GET /v1/models` returns standard OpenAI shape, minimal fields only:9091```json92{"object":"list","data":[93  {"id":"gemma-4-31b","object":"model","created":0,"owned_by":"Cerebras"},94  {"id":"gpt-oss-120b","object":"model","created":0,"owned_by":"Cerebras"},95  {"id":"zai-glm-4.7","object":"model","created":0,"owned_by":"Cerebras"}96]}97```9899No context/pricing/capability metadata — dynamic refresh can only diff IDs; everything else must come100from the built-in catalog (this document).101