> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reasoning models

> Use GPT-5.6 Sol, Claude Opus 5, and other reasoning models through the AI Gateway with reasoning_effort and thinking controls per provider.

Reasoning and thinking models perform internal deliberation before generating a response. Each provider exposes this differently: OpenAI uses `reasoning_effort`, while Google Gemini and Anthropic use a `thinking` object. The **AI Gateway** accepts all three controls and normalizes values to what each model actually supports before forwarding the request.

| Provider | Control | Values |
| - | - | - |
| OpenAI o-series | `reasoning_effort` | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` |
| Google Gemini 3 preview | `thinking.thinking_level` | `low`, `high` |
| Google Gemini 2.5 | `thinking.budget_tokens` | integer |
| Anthropic Claude | `thinking.budget_tokens` | integer |

**Use Cases**

* Problems requiring multi-step logical deduction (math proofs, code debugging, planning).
* Complex analysis where a standard model produces shallow or incorrect results.
* Research tasks where depth of reasoning matters more than response speed.
* Benchmarking reasoning quality across providers on identical prompts.

***

## Quick Start

The **AI Gateway** supports three reasoning controls:

* `reasoning` object on `POST /responses` for OpenAI reasoning models.
* `reasoning_effort` on `POST /chat/completions` for OpenAI reasoning models.
* `thinking` on `POST /chat/completions` for Google Gemini and Anthropic extended thinking.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Analyze the logical flaw in this argument.",
    "reasoning": {"effort": "medium"}
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: 'https://router.toqan.ai/eu/v3/router',
});

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Analyze the logical flaw in this argument.',
  reasoning: { effort: 'medium' },
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Analyze the logical flaw in this argument.",
    extra_body={"reasoning": {"effort": "medium"}},
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: 'https://router.toqan.ai/eu/v3/router',
});

const response = await client.chat.completions.create({
  model: 'openai/gpt-5.4-mini',
  messages: [{ role: 'user', content: 'Analyze the logical flaw in this argument.' }],
  reasoning_effort: 'medium',
});
console.log(response.choices[0].message.content ?? "");

const geminiLevel = await client.chat.completions.create({
  model: 'google/gemini-2.5-pro',
  messages: [{ role: 'user', content: 'Plan a 3-day Tokyo itinerary under $500.' }],
  thinking: { type: 'enabled', budget_tokens: 4096 },
});
console.log(geminiLevel.choices[0].message.content ?? "");

const anthropicThinking = await client.chat.completions.create({
  model: 'anthropic/claude-sonnet-5',
  messages: [{ role: 'user', content: 'Design a rate limiting strategy for a global API.' }],
  thinking: { type: 'enabled', budget_tokens: 4096 },
  max_tokens: 8000,
});
console.log(anthropicThinking.choices[0].message.content ?? "");
```

## Request Fields

| Field | Type | Values | Notes |
| - | - | - | - |
| `reasoning_effort` | string | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | OpenAI-style reasoning control |
| `thinking.type` | string | `enabled`, `disabled`, `adaptive`, `between_tools` | Used by Google Gemini and Anthropic thinking paths |
| `thinking.budget_tokens` | number | integer | Budget-based thinking; optional with `between_tools` |
| `thinking.thinking_level` | string | `minimal`, `low`, `medium`, `high` | Level-based thinking for Gemini 3 preview models |
| `thinking.display` | string | `summarized`, `omitted`, `updates` | Anthropic thinking summaries; `updates` streams progress between tool calls |

> [!WARNING]
>
> Treat `thinking.budget_tokens` and `thinking.thinking_level` as mutually
> exclusive. On the Google path, if `thinking_level` is present it takes
> precedence over `budget_tokens`.

## Provider Behavior

### OpenAI reasoning models

Use `reasoning_effort` on `POST /chat/completions`.

Current registry examples:

* `openai/gpt-5.6-sol`.
* `openai/gpt-5.4-mini`.
  The **AI Gateway** schema accepts all six enum values, but model support is ultimately model-specific.

> [!NOTE]
>
> The router normalizes `reasoning_effort` to the nearest value a model supports before forwarding the request. For example, `openai/gpt-5.4` does not support `xhigh`: it maps to `high`. Models that do support `xhigh` receive the value as-is.

> [!NOTE]
>
> The **AI Gateway** automatically drops `temperature` and `top_p` before
> forwarding the request whenever the model reasons. For OpenAI and Azure
> reasoning models, that covers any `reasoning_effort` other than `none` and the
> case where `reasoning_effort` is not set at all, since these models reason by
> default. Set `reasoning_effort: none` to forward sampling parameters. These
> parameters are incompatible with OpenAI reasoning models and will cause an
> error if sent directly.

> [card] [OpenAI](/docs/ai-studio/integrations/providers/openai.md)
>
> Set up the OpenAI API key and explore all supported models including the GPT-5.x reasoning family.

### Google Gemini

Use the `thinking` object.

Level-based (`thinking_level`) examples:

* `google/gemini-3-flash-preview`.

* `google/gemini-3.1-pro-preview`.
  Budget-based (`budget_tokens`) examples:

* `google/gemini-2.5-flash`.

* `google/gemini-2.5-flash-lite`.

* `google/gemini-2.5-pro`.
  Router behavior:

* `thinking: { "type": "disabled" }` is valid

* On `thinking_enforced` models such as `google/gemini-2.5-pro`, disabling thinking is coerced to a minimum budget of `128`

* On non-enforced Gemini models, disabling thinking becomes a budget of `0`

> [card] [Google AI](/docs/ai-studio/integrations/providers/google-ai.md)
>
> Set up the Google AI API key and explore Gemini 2.5 and Gemini 3 thinking models.

### Anthropic Claude

On `POST /chat/completions`, Anthropic uses `thinking: { type, budget_tokens }`.

Current registry examples:

* `anthropic/claude-sonnet-5`.

* `anthropic/claude-opus-5`.
  Router behavior:

* Anthropic chat completions forward `enabled`, `adaptive`, and `between_tools`. On models that support it, `between_tools` returns progress updates between tool calls without extended thinking.

* `budget_tokens` must be greater than `0` to be forwarded with `enabled`; omit it with `between_tools`.

* `thinking_level` is not used for Anthropic chat completions.

An Agent can save the same `thinking` object in its model parameters (`model.parameters.thinking`). A request that sets neither `thinking` nor `reasoning_effort` inherits the saved value; either one overrides it.

> [card] [Anthropic](/docs/ai-studio/integrations/providers/anthropic.md)
>
> Set up the Anthropic API key and explore Claude extended thinking capabilities.

## Responses API

On `POST /v3/router/responses`, use the OpenAI-style `reasoning` object with `effort` instead of `reasoning_effort` for OpenAI models. Configure Anthropic Claude models with the `thinking` object.

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "openai/gpt-5.4-mini",
  "input": "Solve this step by step.",
  "reasoning": {
    "effort": "medium"
  }
}
```

### Progress updates between tool calls

Add these fields to a tool-use request on a model that supports `between_tools` to receive progress summaries without up-front thinking:

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "model": "google/global.claude-sonnet-5-5",
  "thinking": { "type": "between_tools" },
  "stream": true
}
```

On Chat Completions, send the same `thinking` object to `/v3/router/chat/completions`. Omit `display` and `budget_tokens` with `between_tools`. Keep reasoning effort at `low`, `medium`, or `high` when setting it explicitly.

To keep adaptive thinking and receive progress updates, use `thinking: { "type": "adaptive", "display": "updates" }`. Use `display: "summarized"` to receive both reasoning summaries and progress summaries.

Render non-empty `response.reasoning_summary_text.delta` events as they arrive. In completed responses, read `summary[].text` from items with `type: "reasoning"`. These summaries are separate from `output_text`. Preserve the complete reasoning items, including signatures, when returning tool results.

## Usage and Output

Reasoning token usage is returned under `usage.completion_tokens_details.reasoning_tokens`.

```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "usage": {
    "prompt_tokens": 120,
    "completion_tokens": 980,
    "total_tokens": 1100,
    "completion_tokens_details": {
      "reasoning_tokens": 640
    }
  }
}
```

> [!NOTE]
>
> Anthropic's API does not always report thinking tokens separately. When it does not, `reasoning_tokens` is `0` and thinking tokens are included in the total `completion_tokens` count. Google Gemini and OpenAI reasoning models typically report `reasoning_tokens` correctly.

### Streaming reasoning chunks

In streaming mode, thinking models deliver chain-of-thought content as a `reasoning` field on chunks that carry reasoning content. Text-only chunks do not include this field.

> [!NOTE]
>
> The `reasoning` streaming field is available for both Anthropic and Google Gemini thinking models. OpenAI reasoning models stream thinking content through `reasoning_summary_text.delta` events instead. Do not rely on this field being present across all providers.

> [!WARNING]
>
> Do not rely on visible chain-of-thought text being present in every response.
> The stable contract is the request fields above plus token usage.
> Provider-specific fields such as `reasoning`, `reasoning_signature`, or
> `redacted_reasoning` may appear, but they are optional.

## Code Examples

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/responses \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4-mini",
    "input": "Solve this step by step: What is 15% of 250?",
    "reasoning": {"effort": "medium"}
  }'
```

```bash cURL (Chat Completions) theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://router.toqan.ai/eu/v3/router/chat/completions \
  -H "Authorization: Bearer $TOQAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic/claude-opus-5",
    "messages": [
      {
        "role": "user",
        "content": "Break down the tradeoffs of event-driven vs request-response systems."
      }
    ],
    "thinking": { "type": "enabled", "budget_tokens": 8192 },
    "max_tokens": 16000
  }'
```

```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: 'https://router.toqan.ai/eu/v3/router',
});

const response = await client.responses.create({
  model: 'openai/gpt-5.4-mini',
  input: 'Solve this step by step: What is 15% of 250?',
  reasoning: { effort: 'medium' },
});

console.log(response.output_text);
```

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.responses.create(
    model="openai/gpt-5.4-mini",
    input="Solve this step by step: What is 15% of 250?",
    extra_body={"reasoning": {"effort": "medium"}},
)

print(response.output_text)
```

```typescript TypeScript (Chat Completions: Anthropic thinking) theme={"theme":{"light":"github-light","dark":"github-dark"}}
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.TOQAN_API_KEY,
  baseURL: 'https://router.toqan.ai/eu/v3/router',
});

const response = await client.chat.completions.create({
  model: 'anthropic/claude-opus-5',
  messages: [
    {
      role: 'user',
      content: 'Break down the tradeoffs of event-driven vs request-response systems.',
    },
  ],
  thinking: { type: 'enabled', budget_tokens: 8192 },
  max_tokens: 16000,
});

console.log(response.choices[0].message.content ?? "");
```

```python Python (Chat Completions: Anthropic thinking) theme={"theme":{"light":"github-light","dark":"github-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ.get("TOQAN_API_KEY"),
    base_url="https://router.toqan.ai/eu/v3/router",
)

response = client.chat.completions.create(
    model="anthropic/claude-opus-5",
    messages=[
        {
            "role": "user",
            "content": "Break down the tradeoffs of event-driven vs request-response systems.",
        }
    ],
    max_tokens=16000,
    extra_body={
        "thinking": {
            "type": "enabled",
            "budget_tokens": 8192,
        }
    },
)

print(response.choices[0].message.content or "")
```

## Choosing a Setting

Use `reasoning_effort` when the model is in an OpenAI reasoning family such as `gpt-5.x`, `o1`, or `o3`. Use `thinking_level` for Gemini 3 preview models. Use `budget_tokens` for Anthropic and budget-based Gemini models.

For the current model catalog, see [Supported Models](/docs/ai-gateway/supported-models.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.