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

# Modelos de raciocínio

> Use o GPT-5.6 Sol, o Claude Opus 5 e outros modelos de raciocínio pelo AI Gateway com os controles reasoning_effort e thinking de cada provedor.

Os modelos de raciocínio e de thinking fazem uma deliberação interna antes de gerar uma resposta. Cada provedor expõe isso de forma diferente: a OpenAI usa `reasoning_effort`, enquanto o Google Gemini e a Anthropic usam um objeto `thinking`. O **AI Gateway** aceita os três controles e normaliza os valores para o que cada modelo realmente suporta antes de encaminhar a solicitação.

| Provedor | Controle | Valores |
| - | - | - |
| 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` | inteiro |
| Anthropic Claude | `thinking.budget_tokens` | inteiro |

**Casos de uso**

* Problemas que exigem dedução lógica em várias etapas (provas matemáticas, depuração de código, planejamento).
* Análises complexas em que um modelo padrão produz resultados superficiais ou incorretos.
* Tarefas de pesquisa em que a profundidade do raciocínio importa mais do que a velocidade da resposta.
* Comparação da qualidade do raciocínio entre provedores com prompts idênticos.

***

## Início rápido

O **AI Gateway** oferece três controles de raciocínio:

* Objeto `reasoning` em `POST /responses` para modelos de raciocínio da OpenAI.
* `reasoning_effort` em `POST /chat/completions` para modelos de raciocínio da OpenAI.
* `thinking` em `POST /chat/completions` para o extended thinking do Google Gemini e da Anthropic.

```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 ?? "");
```

## Campos da solicitação

| Campo | Tipo | Valores | Observações |
| - | - | - | - |
| `reasoning_effort` | string | `none`, `minimal`, `low`, `medium`, `high`, `xhigh` | Controle de raciocínio no estilo da OpenAI |
| `thinking.type` | string | `enabled`, `disabled`, `adaptive`, `between_tools` | Usado pelos fluxos de thinking do Google Gemini e da Anthropic |
| `thinking.budget_tokens` | number | inteiro | Thinking baseado em orçamento; opcional com `between_tools` |
| `thinking.thinking_level` | string | `minimal`, `low`, `medium`, `high` | Thinking baseado em nível para modelos Gemini 3 preview |
| `thinking.display` | string | `summarized`, `omitted`, `updates` | Resumos de thinking da Anthropic; `updates` transmite o progresso entre chamadas de tools |

> [!WARNING]
>
> Trate `thinking.budget_tokens` e `thinking.thinking_level` como mutuamente
> exclusivos. No fluxo do Google, se `thinking_level` estiver presente, ele tem
> precedência sobre `budget_tokens`.

## Comportamento por provedor

### Modelos de raciocínio da OpenAI

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

Exemplos atuais do registro:

* `openai/gpt-5.6-sol`.
* `openai/gpt-5.4-mini`.
  O schema do **AI Gateway** aceita os seis valores do enum, mas o suporte depende, em última instância, de cada modelo.

> [!NOTE]
>
> O router normaliza `reasoning_effort` para o valor mais próximo suportado pelo modelo antes de encaminhar a solicitação. Por exemplo, `openai/gpt-5.4` não suporta `xhigh`: ele é mapeado para `high`. Modelos que suportam `xhigh` recebem o valor sem alterações.

> [!NOTE]
>
> O **AI Gateway** remove automaticamente `temperature` e `top_p` antes de
> encaminhar a solicitação sempre que o modelo raciocina. Para modelos de
> raciocínio da OpenAI e do Azure, isso abrange qualquer `reasoning_effort`
> diferente de `none` e o caso em que `reasoning_effort` não é definido, já que
> esses modelos raciocinam por padrão. Defina `reasoning_effort: none` para
> encaminhar os parâmetros de amostragem. Esses parâmetros são incompatíveis com
> modelos de raciocínio da OpenAI e causam um erro se enviados diretamente.

> [card] [OpenAI](/docs/pt-BR/ai-studio/integrations/providers/openai.md)
>
> Configure a chave de API da OpenAI e explore todos os modelos compatíveis, incluindo a família de raciocínio GPT-5.x.

### Google Gemini

Use o objeto `thinking`.

Exemplos baseados em nível (`thinking_level`):

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

* `google/gemini-3.1-pro-preview`.
  Exemplos baseados em orçamento (`budget_tokens`):

* `google/gemini-2.5-flash`.

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

* `google/gemini-2.5-pro`.
  Comportamento do router:

* `thinking: { "type": "disabled" }` é válido

* Em modelos `thinking_enforced`, como `google/gemini-2.5-pro`, desativar o thinking é convertido em um orçamento mínimo de `128`

* Em modelos Gemini sem essa obrigatoriedade, desativar o thinking resulta em um orçamento de `0`

> [card] [Google AI](/docs/pt-BR/ai-studio/integrations/providers/google-ai.md)
>
> Configure a chave de API do Google AI e explore os modelos de thinking Gemini 2.5 e Gemini 3.

### Anthropic Claude

Em `POST /chat/completions`, a Anthropic usa `thinking: { type, budget_tokens }`.

Exemplos atuais do registro:

* `anthropic/claude-sonnet-5`.

* `anthropic/claude-opus-5`.
  Comportamento do router:

* As chat completions da Anthropic encaminham `enabled`, `adaptive` e `between_tools`. Nos modelos compatíveis, `between_tools` retorna atualizações de progresso entre chamadas de tools sem extended thinking.

* `budget_tokens` precisa ser maior que `0` para ser encaminhado com `enabled`; omita-o com `between_tools`.

* `thinking_level` não é usado nas chat completions da Anthropic.

Um Agent pode salvar o mesmo objeto `thinking` nos parâmetros do modelo (`model.parameters.thinking`). Uma solicitação que não define `thinking` nem `reasoning_effort` herda o valor salvo; qualquer um dos dois o substitui.

> [card] [Anthropic](/docs/pt-BR/ai-studio/integrations/providers/anthropic.md)
>
> Configure a chave de API da Anthropic e explore os recursos de extended thinking do Claude.

## Responses API

Em `POST /v3/router/responses`, use o objeto `reasoning` no estilo da OpenAI com `effort`, em vez de `reasoning_effort`, para modelos da OpenAI. Configure os modelos Anthropic Claude com o objeto `thinking`.

```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"
  }
}
```

### Atualizações de progresso entre chamadas de tools

Adicione estes campos a uma solicitação de uso de ferramentas em um modelo compatível com `between_tools` para receber resumos de progresso sem thinking antecipado:

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

Em Chat Completions, envie o mesmo objeto `thinking` para `/v3/router/chat/completions`. Omita `display` e `budget_tokens` com `between_tools`. Mantenha o esforço de raciocínio em `low`, `medium` ou `high` ao defini-lo explicitamente.

Para manter o thinking adaptativo e receber atualizações de progresso, use `thinking: { "type": "adaptive", "display": "updates" }`. Use `display: "summarized"` para receber tanto resumos de raciocínio quanto resumos de progresso.

Renderize os eventos `response.reasoning_summary_text.delta` não vazios à medida que chegam. Em respostas concluídas, leia `summary[].text` dos itens com `type: "reasoning"`. Esses resumos são separados de `output_text`. Preserve os itens de raciocínio completos, incluindo as assinaturas, ao retornar resultados de ferramentas.

## Uso e saída

O uso de tokens de raciocínio é retornado em `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]
>
> A API da Anthropic nem sempre informa os tokens de thinking separadamente. Quando não informa, `reasoning_tokens` é `0` e os tokens de thinking são incluídos na contagem total de `completion_tokens`. Os modelos de raciocínio do Google Gemini e da OpenAI normalmente informam `reasoning_tokens` corretamente.

### Chunks de raciocínio em streaming

No modo de streaming, os modelos de thinking entregam o conteúdo da cadeia de raciocínio como um campo `reasoning` nos chunks que contêm conteúdo de raciocínio. Chunks apenas de texto não incluem esse campo.

> [!NOTE]
>
> O campo de streaming `reasoning` está disponível para os modelos de thinking da Anthropic e do Google Gemini. Os modelos de raciocínio da OpenAI transmitem o conteúdo de thinking por meio de eventos `reasoning_summary_text.delta`. Não conte com a presença desse campo em todos os provedores.

> [!WARNING]
>
> Não conte com a presença de texto visível da cadeia de raciocínio em todas as respostas.
> O contrato estável são os campos da solicitação acima, além do uso de tokens.
> Campos específicos de provedores, como `reasoning`, `reasoning_signature` ou
> `redacted_reasoning`, podem aparecer, mas são opcionais.

## Exemplos de código

```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 "")
```

## Escolher uma configuração

Use `reasoning_effort` quando o modelo pertencer a uma família de raciocínio da OpenAI, como `gpt-5.x`, `o1` ou `o3`. Use `thinking_level` para modelos Gemini 3 preview. Use `budget_tokens` para modelos da Anthropic e modelos Gemini baseados em orçamento.

Para o catálogo atual de modelos, consulte [Modelos compatíveis](/docs/pt-BR/ai-gateway/supported-models.md).


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