> ## 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.

# Modelli di ragionamento

> Usare modelli di ragionamento con thinking visibile nell'API Venice

Alcuni modelli pensano ad alta voce prima di rispondere. Lavorano sui problemi passo dopo passo, quindi forniscono una risposta finale. Questo li rende più forti su matematica, codice e compiti ad alto contenuto logico.

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

Consulta l'elenco completo dei modelli, dei prezzi e dei limiti di contesto nella [pagina Modelli](/models/overview). Non tutti i modelli di ragionamento supportano il parametro [`reasoning_effort`](#reasoning-effort). Vedi il [supporto dei modelli](#model-support) per i dettagli.

## Leggere l'output

I modelli di ragionamento restituiscono il loro thinking in un campo separato `reasoning_content`, mantenendo `content` pulito:

<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>
  Alcuni provider (Anthropic, Google, OpenAI, Qwen) restituiscono token di ragionamento cifrati o riassunti. Quando questo accade, `reasoning_content` contiene un placeholder `"[Some reasoning content is encrypted]"`.
</Info>

### Streaming

In streaming, `reasoning_content` arriva nel delta prima della risposta finale:

<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>

## Reasoning effort

Il parametro `reasoning_effort` controlla quanto thinking fa un modello prima di rispondere. Più sforzo significa ragionamento più profondo ma più token e latenza.

### Valori accettati

| Valore    | Descrizione                                      |
| --------- | ------------------------------------------------ |
| `none`    | Disabilita completamente il ragionamento         |
| `minimal` | Ragionamento di base con sforzo minimo           |
| `low`     | Ragionamento leggero per problemi semplici       |
| `medium`  | Ragionamento bilanciato per complessità moderata |
| `high`    | Ragionamento profondo per problemi complessi     |
| `xhigh`   | Profondità di ragionamento extra-alta            |
| `max`     | Capacità di ragionamento massima                 |

<Warning>
  Non tutti i modelli supportano tutti i valori. Venice **non** mappa automaticamente al livello supportato più vicino. I valori non supportati restituiscono un errore 400 dal provider upstream. Ad esempio, inviare `xhigh` a Claude o `max` a GPT-5.2 fallirà.

  In caso di dubbi, usa `low`, `medium` o `high`. Sono i valori più ampiamente supportati.
</Warning>

### Supporto dei modelli

#### OpenAI

| Modello                      | Valori supportati                        |
| ---------------------------- | ---------------------------------------- |
| GPT-5.2                      | `none`, `low`, `medium`, `high`, `xhigh` |
| GPT-5.2 Codex, GPT-5.3 Codex | `low`, `medium`, `high`, `xhigh`         |

#### Anthropic

| Modello                                 | Valori supportati              |
| --------------------------------------- | ------------------------------ |
| 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

| Modello                | Valori supportati                  |
| ---------------------- | ---------------------------------- |
| Gemini 3 Pro Preview   | `low`, `high`                      |
| Gemini 3.1 Pro Preview | `low`, `medium`, `high`            |
| Gemini 3 Flash Preview | `minimal`, `low`, `medium`, `high` |

#### xAI

I modelli Grok (Grok 4.1 Fast, Grok Code Fast) **non** supportano `reasoning_effort`. Specificarlo comporterà un errore.

#### Altri modelli

| Modello                                     | Valori supportati                              |
| ------------------------------------------- | ---------------------------------------------- |
| 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`                        |
| Serie GLM 5.1                               | Solo ragionamento integrato, non configurabile |
| DeepSeek R1                                 | Solo ragionamento integrato, non configurabile |

### Utilizzo

Passa `reasoning_effort` come parametro di primo livello o usa il formato nidificato `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>

Anche il formato piatto `"reasoning_effort": "high"` è accettato.

## Disabilitare il ragionamento

Ci sono due modi per disabilitare il ragionamento:

| Metodo                     | Sintassi                          | Come funziona                                                                                            |
| -------------------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `reasoning.enabled: false` | `"reasoning": {"enabled": false}` | Toggle a livello Venice che impedisce l'invio di parametri di ragionamento al provider. **Consigliato.** |
| `reasoning.effort: "none"` | `"reasoning": {"effort": "none"}` | Passato al provider, che decide come gestirlo. Supportato solo da alcuni modelli (es. GPT-5.x).          |

Per i modelli che lo supportano, `reasoning.enabled: false` è l'opzione più affidabile:

| Modello                                      | Disabilitabile?                      |
| -------------------------------------------- | ------------------------------------ |
| GPT-5.2                                      | Sì                                   |
| GPT-5.2 Codex, GPT-5.3 Codex                 | Sì (ma effort `none` non supportato) |
| Qwen 3 235B A22B Thinking, Qwen 3.5 35B A3B  | Sì                                   |
| Serie GLM 5.1                                | Sì                                   |
| Claude Opus 4.5/4.6/4.6 Fast, Sonnet 4.5/4.6 | No (ragiona sempre)                  |
| Gemini 3 Pro, 3.1 Pro, 3 Flash               | No (ragiona sempre)                  |
| DeepSeek R1                                  | No (ragiona sempre)                  |

<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>

## Limiti di token

I modelli di ragionamento generano token di risposta visibili (in `content`) e token di ragionamento (in `reasoning_content`). Entrambi contano verso il tuo budget di token.

### Impostare un limite di token

Usa `max_completion_tokens` per limitare il numero totale di token generati dal modello, ragionamento incluso:

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

Anche `max_tokens` è accettato e si comporta allo stesso modo. Se entrambi sono impostati, `max_completion_tokens` ha la precedenza.

Per ottenere più output visibile, alza il limite, abbassa `reasoning_effort` o [disabilita il ragionamento](#disabling-reasoning).

### Leggere il dettaglio

L'oggetto `usage` mostra come è stato speso il tuo budget:

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

In questo esempio, 169 token sono stati spesi per il ragionamento e 332 per la risposta visibile. Quando viene raggiunto il limite, `finish_reason` è `length`.

Il limite superiore di ciascun modello è disponibile come `maxCompletionTokens` nell'endpoint [`/v1/models`](/api-reference/endpoint/models/list).

### Modelli senza ragionamento

`max_tokens` e `max_completion_tokens` si comportano allo stesso modo sui modelli senza ragionamento, limitando direttamente l'output visibile.

## Discovery delle capacità

Controlla cosa supporta un modello tramite l'endpoint [`/v1/models`](/api-reference/endpoint/models/list):

| Campo                     | Significato                                                             |
| ------------------------- | ----------------------------------------------------------------------- |
| `supportsReasoning`       | Il modello ha capacità di ragionamento (chain-of-thought)               |
| `supportsReasoningEffort` | Il modello accetta il parametro `reasoning_effort` / `reasoning.effort` |

## Best practice

* Per uso generale, imposta come default `medium`
* Usa `high` o `xhigh` per compiti complessi (matematica, codice, analisi)
* Usa `low` per applicazioni sensibili alla latenza
* Usa `reasoning.enabled: false` o imposta effort su `none` per disabilitare il ragionamento
* In caso di dubbi, usa `low`, `medium` o `high`. Sono i valori più ampiamente supportati