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

# Modelos de raciocínio

> Usando modelos de raciocínio com pensamento visível na API Venice

Alguns modelos pensam em voz alta antes de responder. Eles resolvem problemas passo a passo e então dão a resposta final. Isso os torna mais fortes em matemática, código e tarefas intensivas em lógica.

<div id="reasoning-models-placeholder" />

Veja a lista completa de modelos, preços e limites de contexto na [página de modelos](/models/overview). Nem todos os modelos de raciocínio suportam o parâmetro [`reasoning_effort`](#reasoning-effort). Veja [suporte por modelo](#model-support) para detalhes.

## Lendo a saída

Modelos de raciocínio retornam seu pensamento em um campo separado `reasoning_content`, mantendo `content` limpo:

<CodeGroup>
  ```python Python theme={"dark"}
  response = client.chat.completions.create(
      model="zai-org-glm-5-1",
      messages=[{"role": "user", "content": "What is 15% of 240?"}]
  )

  thinking = response.choices[0].message.reasoning_content
  answer = response.choices[0].message.content
  ```

  ```javascript Node.js theme={"dark"}
  const response = await client.chat.completions.create({
      model: "zai-org-glm-5-1",
      messages: [{ role: "user", content: "What is 15% of 240?" }]
  });

  const thinking = response.choices[0].message.reasoning_content;
  const answer = response.choices[0].message.content;
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org-glm-5-1",
      "messages": [{"role": "user", "content": "What is 15% of 240?"}]
    }'
  ```
</CodeGroup>

<Info>
  Alguns provedores (Anthropic, Google, OpenAI, Qwen) retornam tokens de raciocínio criptografados ou resumidos. Quando isso acontece, `reasoning_content` contém um placeholder `"[Some reasoning content is encrypted]"`.
</Info>

### Streaming

Ao fazer streaming, `reasoning_content` chega no delta antes da resposta final:

<CodeGroup>
  ```python Python theme={"dark"}
  stream = client.chat.completions.create(
      model="zai-org-glm-5-1",
      messages=[{"role": "user", "content": "Explain photosynthesis"}],
      stream=True
  )

  for chunk in stream:
      if chunk.choices:
          delta = chunk.choices[0].delta
          if delta.reasoning_content:
              print(delta.reasoning_content, end="")
          if delta.content:
              print(delta.content, end="")
  ```

  ```javascript Node.js theme={"dark"}
  const stream = await client.chat.completions.create({
      model: "zai-org-glm-5-1",
      messages: [{ role: "user", content: "Explain photosynthesis" }],
      stream: true
  });

  for await (const chunk of stream) {
      if (chunk.choices?.[0]?.delta) {
          const delta = chunk.choices[0].delta;
          if (delta.reasoning_content) process.stdout.write(delta.reasoning_content);
          if (delta.content) process.stdout.write(delta.content);
      }
  }
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "zai-org-glm-5-1",
      "messages": [{"role": "user", "content": "Explain photosynthesis"}],
      "stream": true
    }'
  ```
</CodeGroup>

## Esforço de raciocínio

O parâmetro `reasoning_effort` controla quanto pensamento um modelo faz antes de responder. Maior esforço significa raciocínio mais profundo, mas mais tokens e latência.

### Valores aceitos

| Valor     | Descrição                                        |
| --------- | ------------------------------------------------ |
| `none`    | Desabilita o raciocínio por completo             |
| `minimal` | Raciocínio básico com esforço mínimo             |
| `low`     | Raciocínio leve para problemas simples           |
| `medium`  | Raciocínio balanceado para complexidade moderada |
| `high`    | Raciocínio profundo para problemas complexos     |
| `xhigh`   | Profundidade de raciocínio extra alta            |
| `max`     | Capacidade máxima de raciocínio                  |

<Warning>
  Nem todos os modelos suportam todos os valores. A Venice **não** mapeia automaticamente para o nível compatível mais próximo. Valores não suportados retornam um erro 400 do provedor upstream. Por exemplo, enviar `xhigh` para o Claude ou `max` para o GPT-5.2 falhará.

  Em caso de dúvida, use `low`, `medium` ou `high`. Esses são os valores mais amplamente suportados.
</Warning>

### Suporte por modelo

#### OpenAI

| Modelo                       | Valores suportados                       |
| ---------------------------- | ---------------------------------------- |
| GPT-5.2                      | `none`, `low`, `medium`, `high`, `xhigh` |
| GPT-5.2 Codex, GPT-5.3 Codex | `low`, `medium`, `high`, `xhigh`         |

#### Anthropic

| Modelo                                  | Valores suportados             |
| --------------------------------------- | ------------------------------ |
| Claude Opus 4.6, Opus 4.6 Fast          | `low`, `medium`, `high`, `max` |
| Claude Opus 4.5, Sonnet 4.5, Sonnet 4.6 | `low`, `medium`, `high`        |

#### Google

| Modelo                 | Valores suportados                 |
| ---------------------- | ---------------------------------- |
| Gemini 3 Pro Preview   | `low`, `high`                      |
| Gemini 3.1 Pro Preview | `low`, `medium`, `high`            |
| Gemini 3 Flash Preview | `minimal`, `low`, `medium`, `high` |

#### xAI

Modelos Grok (Grok 4.1 Fast, Grok Code Fast) **não** suportam `reasoning_effort`. Especificá-lo resultará em erro.

#### Outros modelos

| Modelo                                      | Valores suportados                            |
| ------------------------------------------- | --------------------------------------------- |
| Qwen 3 235B A22B Thinking, Qwen 3.5 35B A3B | `low`, `medium`, `high`                       |
| Kimi K2.5                                   | `low`, `medium`, `high`                       |
| MiniMax M2.5, M2.1                          | `low`, `medium`, `high`                       |
| Família GLM 5.1                             | Raciocínio integrado apenas, não configurável |
| DeepSeek R1                                 | Raciocínio integrado apenas, não configurável |

### Uso

Passe `reasoning_effort` como parâmetro de nível superior ou use o formato aninhado `reasoning.effort`:

<CodeGroup>
  ```python Python theme={"dark"}
  response = client.chat.completions.create(
      model="minimax-m25",
      messages=[{"role": "user", "content": "Prove that there are infinitely many primes"}],
      extra_body={"reasoning": {"effort": "high"}}
  )
  ```

  ```javascript Node.js theme={"dark"}
  const response = await client.chat.completions.create({
      model: "minimax-m25",
      messages: [{ role: "user", content: "Prove that there are infinitely many primes" }],
      reasoning: { effort: "high" }
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "minimax-m25",
      "messages": [{"role": "user", "content": "Prove that there are infinitely many primes"}],
      "reasoning": {"effort": "high"}
    }'
  ```
</CodeGroup>

O formato plano `"reasoning_effort": "high"` também é aceito.

## Desabilitando o raciocínio

Há duas formas de desabilitar o raciocínio:

| Método                     | Sintaxe                           | Como funciona                                                                                           |
| -------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `reasoning.enabled: false` | `"reasoning": {"enabled": false}` | Toggle no nível da Venice que impede o envio de parâmetros de raciocínio ao provedor. **Recomendado.**  |
| `reasoning.effort: "none"` | `"reasoning": {"effort": "none"}` | Passado ao provedor, que decide como lidar. Suportado apenas por alguns modelos (por exemplo, GPT-5.x). |

Para modelos que suportam, `reasoning.enabled: false` é a opção mais confiável:

| Modelo                                       | Pode desabilitar?                       |
| -------------------------------------------- | --------------------------------------- |
| GPT-5.2                                      | Sim                                     |
| GPT-5.2 Codex, GPT-5.3 Codex                 | Sim (mas effort `none` não é suportado) |
| Qwen 3 235B A22B Thinking, Qwen 3.5 35B A3B  | Sim                                     |
| Família GLM 5.1                              | Sim                                     |
| Claude Opus 4.5/4.6/4.6 Fast, Sonnet 4.5/4.6 | Não (sempre raciocina)                  |
| Gemini 3 Pro, 3.1 Pro, 3 Flash               | Não (sempre raciocina)                  |
| DeepSeek R1                                  | Não (sempre raciocina)                  |

<CodeGroup>
  ```python Python theme={"dark"}
  response = client.chat.completions.create(
      model="openai-gpt-52",
      messages=[{"role": "user", "content": "What's the capital of France?"}],
      extra_body={"reasoning": {"enabled": False}}
  )
  ```

  ```javascript Node.js theme={"dark"}
  const response = await client.chat.completions.create({
      model: "openai-gpt-52",
      messages: [{ role: "user", content: "What's the capital of France?" }],
      reasoning: { enabled: false }
  });
  ```

  ```bash cURL theme={"dark"}
  curl https://api.venice.ai/api/v1/chat/completions \
    -H "Authorization: Bearer $VENICE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "openai-gpt-52",
      "messages": [{"role": "user", "content": "What is the capital of France?"}],
      "reasoning": {"enabled": false}
    }'
  ```
</CodeGroup>

## Limites de tokens

Modelos de raciocínio geram tokens de resposta visível (em `content`) e tokens de raciocínio (em `reasoning_content`). Ambos contam para seu orçamento de tokens.

### Definindo um limite de tokens

Use `max_completion_tokens` para limitar o número total de tokens que o modelo gera, incluindo o raciocínio:

```json theme={"dark"}
{
  "model": "deepseek-v4-flash",
  "messages": [...],
  "max_completion_tokens": 500
}
```

`max_tokens` também é aceito e se comporta da mesma forma. Se ambos forem definidos, `max_completion_tokens` tem precedência.

Para obter mais saída visível, aumente o limite, reduza `reasoning_effort` ou [desabilite o raciocínio](#disabling-reasoning).

### Lendo o detalhamento

O objeto `usage` mostra como seu orçamento foi gasto:

```json theme={"dark"}
"usage": {
  "completion_tokens": 501,
  "completion_tokens_details": { "reasoning_tokens": 169 },
  "prompt_tokens": 13,
  "total_tokens": 514
}
```

Neste exemplo, 169 tokens foram gastos em raciocínio e 332 na resposta visível. Quando o limite é atingido, `finish_reason` é `length`.

O limite superior de cada modelo está disponível como `maxCompletionTokens` no endpoint [`/v1/models`](/api-reference/endpoint/models/list).

### Modelos sem raciocínio

`max_tokens` e `max_completion_tokens` se comportam da mesma forma em modelos sem raciocínio, limitando diretamente a saída visível.

## Descoberta de capacidades

Verifique o que um modelo suporta pelo endpoint [`/v1/models`](/api-reference/endpoint/models/list):

| Campo                     | Significado                                                         |
| ------------------------- | ------------------------------------------------------------------- |
| `supportsReasoning`       | O modelo tem capacidade de raciocínio (chain-of-thought)            |
| `supportsReasoningEffort` | O modelo aceita o parâmetro `reasoning_effort` / `reasoning.effort` |

## Melhores práticas

* Use `medium` como padrão para uso geral
* Use `high` ou `xhigh` para tarefas complexas (matemática, código, análise)
* Use `low` para aplicações sensíveis à latência
* Use `reasoning.enabled: false` ou defina effort como `none` para desabilitar o raciocínio
* Em caso de dúvida, use `low`, `medium` ou `high`. Esses são os valores mais amplamente suportados.