# Cerebras — Provider Research (Phase 0)

Researched 2026-07-30 against official docs (https://inference-docs.cerebras.ai) and a live authenticated GET /v1/models probe (/tmp/zyquo-probe/cerebras.json). Cerebras runs inference on wafer-scale hardware — its differentiator is extreme speed (1,000–3,000 output tokens/s), not catalog breadth.

# 1. Base URL & Endpoints

• Base URL: https://api.cerebras.ai/v1
• POST /v1/chat/completions — chat (used by Zyquo Cloud)
• POST /v1/completions — text completion
• GET /v1/models, GET /v1/models/{id} — model listing

Reference: https://inference-docs.cerebras.ai/api-reference/chat-completions

# 2. Authentication

Authorization: Bearer <CEREBRAS_API_KEY> — standard Bearer (key from cloud.cerebras.ai console). Confirmed.

# 3. Chat Model Catalog

Live /models probe returned exactly 3 models — and the docs models page (https://inference-docs.cerebras.ai/models/overview) lists the same 3 public models, so there is no discrepancy between /models and docs today (older models like llama-3.3-70b, qwen-3-*, and llama3.1-8b no longer appear in either — treat as removed). Additional models exist only via paid Dedicated Endpoints. Context windows are tier-dependent (free vs paid).

Notes:

• 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.
• 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.
• Note the probe listing order (gemma-4-31b, gpt-oss-120b, zai-glm-4.7) matches docs exactly.

# 4. Request/Response Format

OpenAI-compatible with notable deviations:

• 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.
• 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).
• Roles: system, user, assistant, tool, plus developer (gpt-oss-120b only; system maps to developer-level).
• Reasoning models return chain-of-thought in choices[].message.reasoning (top-level field).
• 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.
• n (multiple completions) and stream_options are not documented (assume unsupported — unverified).
• Optional: Content-Type: application/vnd.msgpack, gzip request encoding, queue_threshold header (50–20000 ms) for flex/auto tiers.

# 5. Streaming

• stream: true → SSE chat.completion.chunk objects with choices[].delta (content, tool_calls, and reasoning deltas on reasoning models), terminated by data: [DONE].
• usage appears in the final streamed chunk per the documented streaming response schema (no stream_options.include_usage needed — the parameter is not documented).
• 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).

# 6. Special Parameters

• 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.
• 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).
• response_format: text | json_object | json_schema with strict: true schema enforcement via constrained decoding — Cerebras's structured outputs are genuinely strict.
• tools/tool_choice (none|auto|required|named) + parallel_tool_calls (default true); strict: true supported on tool schemas.
• prediction (predicted outputs), prompt_cache_key (grouping for prompt caching), service_tier (priority|default|auto|flex), user.
• Known quirks (docs): gpt-oss-120b may emit unexpected EOS with min_tokens, and may hallucinate tool calls outside schema (reprompt to correct).

# 7. Rate Limits & Errors

(https://inference-docs.cerebras.ai/support/rate-limits)

• 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.
• 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.
• 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.)
• Enterprise: custom.
• 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).
• 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.

# 8. /models Listing

GET /v1/models returns standard OpenAI shape, minimal fields only:

{"object":"list","data":[
  {"id":"gemma-4-31b","object":"model","created":0,"owned_by":"Cerebras"},
  {"id":"gpt-oss-120b","object":"model","created":0,"owned_by":"Cerebras"},
  {"id":"zai-glm-4.7","object":"model","created":0,"owned_by":"Cerebras"}
]}

No context/pricing/capability metadata — dynamic refresh can only diff IDs; everything else must come from the built-in catalog (this document).