Reasoning effort

reasoning_effort controls how much internal reasoning a model may use before it answers. ModelRelay exposes one provider-neutral ladder:

none → minimal → low → medium → high → xhigh → max

Leave the field empty to use the provider’s default. Model support is a subset of the ladder: a recognized value outside a matched model’s subset is rejected instead of being silently downgraded.

Supported values by model

Models without a mapped reasoning control omit the field and retain the provider default. Do not infer support from the provider alone; use the model-specific discovery response described below.

Mapping semantics

The ladder describes intent, not identical upstream parameters:

• GPT-6.1 Sol rejects none and minimal; use low for its lowest effort. GPT-6 Luna supports none but rejects minimal.
• Claude Opus 5.5 defaults to medium; none maps to low because thinking is always enabled. Claude Sonnet 5.5 defaults to high; explicit none uses between_tools thinking with low effort.
• Always-reasoning models cannot disable thinking, so none means the least reasoning the model can do rather than an error. For Claude Fable and Mythos, none maps to Anthropic effort low; for Grok 4.6 and other xAI reasoning models, it maps to xAI effort low; for GLM 5.3 Flash on Fireworks and Together, and Kimi K3 on Fireworks, it is sent as low. On NEAR AI, GLM 5.3 Flash honours none directly.
• Claude Opus 5 and Sonnet 5 use medium when reasoning_effort is omitted, including requests through /v1/messages and /v1/chat/completions. Thinking remains on at medium effort; explicit none disables thinking.
• Gemini 3.8 Flash rejects both none and minimal; low is its lowest supported thinking level.
• Gemini medium forwards to the provider’s distinct medium thinking level; it is not reduced to low.
• Omitting Gemini effort leaves the choice to the model rather than pinning a hidden relay default. Request low explicitly when Gemini 3.8 Flash cost and latency must stay bounded. Thinking tokens consume the output-token budget, so leave enough room for visible output.
• Omitting Cerebras effort on Qwen3.8 27B selects the model’s DEEPEST mode, not a middle one: Cerebras defaults this model to high, which reaches Qwen’s native xhigh. Request low or none explicitly when latency and billed output must stay bounded.
• minimal, xhigh, and max are available only where the upstream effort ladder exposes them. They are distinct levels, not aliases for neighboring values.
• Support is per route, not per model. GLM 5.3 Flash accepts max on Fireworks, its serving route, but not on its Together or NEAR AI failover routes. If one of those routes serves the request, max is rejected with that route’s supported values rather than quietly sent as high.

Why effort matters

Reasoning affects both latency and billed output. In same-prompt production probes, GPT-5.6 Luna at none answered in about 0.7 seconds with 5 output tokens. At the provider’s default medium, equivalent runs took about 2.5–2.8 seconds and used 200–312 output tokens.

Reasoning tokens are provider-billed output tokens. Lower effort can therefore reduce latency and cost when the task does not benefit from deeper reasoning; use higher effort when the expected quality gain justifies that budget.

Reasoning support is validated after ModelRelay resolves a concrete provider
route. It is intentionally absent from the logical model catalog because two
providers may expose different controls for the same public model. Use
POST /api/v1/responses/resolve to inspect the selected route’s
reasoning_efforts before execution.

Validation errors

An unrecognized ladder value is rejected with HTTP 400 and an INVALID_REQUEST classification. Model-gated provider adapters use this message shape:

unsupported reasoning_effort "ultra"

A recognized value outside a matched model’s supported subset is also rejected with HTTP 400. Model-gated adapters name the model and may list its supported values:

reasoning_effort "minimal" is not supported by model claude-sonnet-5-5

Provider allowlists use the corresponding provider-scoped form. Google AI reports unsupported recognized values with the resolved model and supported subset, and reports an unrecognized value as invalid reasoning_effort "ultra".