Skip to main content

​
Reasoning is off-surface by default

Every chat endpoint hides the model’s chain-of-thought unless the request explicitly opted in. That default is deliberate: an unsolicited thinking block breaks strict clients — Claude Code with thinking disabled, for one — and a client that never asked for reasoning should never have to parse it. Nothing changes about the model’s behavior. Reasoning models still reason. The flag controls whether those tokens are surfaced to you, not whether they are produced.

​
Asking for it

Each dialect has its own opt-in, and each returns the reasoning in that dialect’s native shape.
reasoning_content is the DeepSeek/GLM/OSS convention rather than anything OpenAI publishes, because OpenAI’s own API does not return chain-of-thought at all. Read it defensively — treat a missing field as “no reasoning”, never as an error.

​
Effort levels

Reasoning models that expose effort levels accept them on every dialect, and an effort level a model doesn’t offer is translated to the nearest one it does — you get an answer at a supported level rather than an error. That matters for agents whose config bakes in xhigh for a model that tops out at high: the request runs at high. The same translation applies to the other knobs an egress needs (an output ceiling a model can’t express is clamped to its maximum, for example). If a request declares a hard requirement no placement of the model can honour at all — a forced tool_choice, a strict response_format — you get a 422 before anything is sent, not a silently weaker request. See Errors.

​
Which models reason

Check the catalog rather than assuming: capabilities.reasoning on each GET /v1/models entry, and the Reasoning capability tag on the Models page. It is a large slice of the catalog and it is not confined to one tier — several workhorse models reason, and some frontier models do not surface it. Check before you set an effort level: a model without a reasoning mode can’t honour one exactly, so it is handled like any other effort mismatch — see Effort levels.

​
Budget for it

This is the part that surprises people:
  • Hidden reasoning still costs output tokens. It is generated, so it is billed and it burns your credits at the model’s output rate exactly like visible output.
  • It counts against max_tokens. On a reasoning model, a tight output ceiling can be consumed entirely by thinking, leaving a truncated or empty answer with finish_reason: "length". Budget generously — a ceiling that is comfortable on a non-reasoning model is often too small here.
  • reasoning_effort is a dial, not a switch. Higher effort means more reasoning tokens and a slower, more expensive turn. Start at the low end and raise it only where the answers justify it.
A ceiling that leaves room to think

​
Streaming

Reasoning streams like any other content. On the Messages dialect it arrives as a thinking content block that opens, deltas, and closes before the text block starts — so a UI can show “thinking…” and then swap to the answer. See Streaming.

​
Reasoning and caching

Reasoning output is not reusable context: it is regenerated each turn and is not what prompt caching discounts. The savings on an agent loop come from the stable prefix — system prompt, tool definitions, conversation history — which is unaffected by whether reasoning is on. See Prompt caching.