Razonamiento

Los modelos de razonamiento piensan antes de responder: resuelven un problema en pasos ocultos o visibles y luego contestan. Esto los hace notablemente mejores en matemáticas, código, planificación y preguntas de varios pasos, a costa de más tokens de salida y más tiempo.

Los modelos que razonan tienen capabilities.reasoning: true en la lista de modelos. Muchos razonan de forma predeterminada; los parámetros de abajo te permiten aumentar, reducir o desactivar el razonamiento.

Chat Completions: reasoning_effort

{
  "model": "gpt-5.5",
  "reasoning_effort": "high",
  "messages": [{ "role": "user", "content": "How many weekdays are there between 3 March and 17 April 2027?" }]
}

Valor	Cuándo usarlo
`none` / `minimal`	Las respuestas más rápidas, con poco o ningún razonamiento. No todos los modelos aceptan ambos.
`low`	Preguntas simples en las que pensar un poco ayuda.
`medium`	Un valor predeterminado razonable para la mayoría de las tareas.
`high`	Problemas difíciles: código complicado, demostraciones, planes largos.
`xhigh`, `max`	Los niveles más profundos, en los modelos que los ofrecen.

Los modelos difieren en los valores que aceptan. Un valor que un modelo no admite se rechaza con un 400, así que revisa la página del modelo antes de depender de un ajuste extremo.

Responses API: reasoning.effort

{
  "model": "gpt-5.5",
  "reasoning": { "effort": "medium" },
  "input": "Plan a three-step migration from REST to gRPC."
}

Messages API: extended thinking

En el formato Anthropic, activa el thinking con un presupuesto de tokens. El presupuesto debe ser menor que max_tokens:

{
  "model": "claude-opus-4-8",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "Find the bug in this function: ..." }]
}

La respuesta contiene bloques thinking antes de los bloques text. Cuando continúes una conversación que usó thinking con herramientas, devuelve esos bloques sin modificarlos.

Qué recibes y cuánto cuesta

Los tokens de razonamiento son tokens de salida: se cobran al precio de salida del modelo, incluso cuando el razonamiento en sí no se muestra. Se reportan por separado para que veas en qué se usaron los tokens:

"usage": {
  "prompt_tokens": 42,
  "completion_tokens": 1180,
  "total_tokens": 1222,
  "completion_tokens_details": { "reasoning_tokens": 960 }
}

Tus registros de solicitudes también muestran los tokens de razonamiento de cada solicitud.

Si se devuelve o no el texto del razonamiento depende del modelo. Algunos devuelven un resumen o el razonamiento completo junto con la respuesta; otros lo mantienen oculto y solo reportan la cantidad de tokens.

Consejos

Deja margen en max_tokens. El razonamiento cuenta para ese límite, y un modelo que gasta su presupuesto pensando devuelve una respuesta vacía o truncada con finish_reason: "length".
Empieza con low o medium y súbelo solo donde las respuestas se queden cortas. Un esfuerzo mayor puede multiplicar los tokens de salida.
Para agentes que llaman a muchas herramientas, un esfuerzo menor por paso suele ser más rápido y más barato en general.