«temperature is deprecated for this model»: causas y solución — temperature en la API de Claude y la nueva versión de API 2026-10-21

Si la API de Claude devuelve el siguiente error, la causa es que estás enviando un valor distinto del predeterminado para temperature (o top_p o top_k) a un modelo Claude 4.7 o posterior. La solución es eliminar estos tres parámetros de tus solicitudes. En la nueva versión de la API 2026-10-21, publicada en octubre de 2026, enviar cualquiera de ellos devuelve un error 400 con todos los modelos, sea cual sea el valor.

400 invalid_request_error
`temperature` is deprecated for this model.

Ejemplo de respuesta cuando se envía un valor no predeterminado a un modelo Claude 4.7 o posterior (informado por usuarios). La documentación oficial no indica si el mensaje de error que devuelve la nueva versión de la API es el mismo.

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    temperature=0.2,
    messages=[...],
)

client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[...],
)

Con base en la documentación oficial de Anthropic (consultada el 26 de octubre de 2026), este artículo explica las dos situaciones en las que aparece este error, qué ocurre al actualizar el SDK, los cambios que conviene hacer a la vez con la nueva versión de la API y cómo solucionar el error parecido anthropic-version: header is required. Las versiones de la API se distinguen por color: 2023-06-01 (la anterior) y 2026-10-21 (la nueva).

1. Las dos situaciones en las que aparece el error

La API de Claude elige la versión de la API con el encabezado de solicitud anthropic-version. Si aparece un error depende de la combinación del modelo que usas y de la versión de la API.

Fuentes: Anthropic, «Migrating to API version 2026-10-21» (Claude 4.7 y modelos posteriores solo aceptan el valor predeterminado; Sonnet 4.6 y otros aceptan otros valores; con 2026-10-21, todos los modelos devuelven 400 incluso con el valor predeterminado), y las guías de migración de cada modelo (Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1; la guía de Fable 5.1 indica que tiene las mismas restricciones de muestreo que Opus 5). Consultado el 26 de octubre de 2026.

Las celdas marcadas con «400» de la tabla corresponden a las dos situaciones siguientes.

1. Situación 1: enviaste un valor no predeterminado con 2023-06-01 a un modelo Claude 4.7 o posterior (primera fila de la tabla, columna 2023-06-01)
2. Situación 2: enviaste cualquiera de los tres con 2026-10-21, sin importar el modelo ni el valor (la columna de la derecha de la tabla)

El mensaje de error del inicio, `temperature` is deprecated for this model., aparece en la situación 1 en una respuesta de la API que un usuario informó en GitHub (ejemplo informado). La documentación oficial de Anthropic no incluye el mensaje de error en sí; solo indica que la solicitud devuelve un error 400.

En resumen, eliminar los tres parámetros soluciona ambas situaciones. Si cambiabas valores en un modelo anterior, ten en cuenta que al eliminarlos cambiará la variación de las respuestas (véase el apartado 2).

2. La solución y cómo obtener siempre la misma respuesta

1. Elimina los tres parámetros de tus solicitudesQuita temperature, top_p y top_k de las solicitudes de la Messages API y de cada solicitud de Message Batches. Si un archivo de configuración o una función envoltorio les asigna un valor predeterminado, elimínalo también ahí.
2. Qué ocurre después de eliminarlosSi no envías los tres, se usan los valores predeterminados para elegir el siguiente token (temperature es 1.0 por defecto). Los valores predeterminados de top_p y top_k no se indican como números, así que no enviarlos es lo más seguro. Es lo mismo que ocurría con las versiones anteriores de la API cuando no enviabas los tres. Los modelos Claude 4.7 y posteriores solo aceptan valores predeterminados desde el principio, así que su comportamiento no cambia.
3. Si quieres obtener siempre la misma respuestaNo hay ningún ajuste que lo sustituya. La guía de migración de Anthropic recomienda orientar el comportamiento del modelo mediante prompts. También indica que, incluso con temperature = 0, nunca hubo garantía de respuestas idénticas en los modelos anteriores. Si solo quieres estandarizar el formato de la respuesta, puedes usar Salidas estructuradas (Structured outputs), que permite definir la forma de un JSON y pedir que el modelo lo devuelva.

La excepción es el caso de un modelo que acepta otros valores, como Claude Sonnet 4.6, en el que bajabas el valor para reducir la variación de las respuestas. Con la nueva versión de la API hay que eliminarlo, y ese efecto desaparece. La indicación de Anthropic es mantener esa solicitud con 2023-06-01 o dejar de enviar el parámetro. Para mantener 2023-06-01, quédate con la versión mayor actual del SDK (1.x en Python) o, si llamas a HTTP directamente, deja el encabezado como anthropic-version: 2023-06-01. La guía de migración no explica cómo elegir una versión anterior de la API por solicitud con el SDK nuevo.

Cómo solucionarlo en TypeScript y HTTP

// TypeScript (@anthropic-ai/sdk): elimina temperature
const msg = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello, Claude" }],
});

# HTTP (cuerpo JSON): omite las líneas de temperature, top_p y top_k
{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello, Claude"}]
}

3. Cómo encontrar en tu código dónde se envían los parámetros

Si no sabes de dónde viene el error, busca en tu código los nombres de los tres parámetros. Aunque no lo hayas escrito tú, es habitual que los valores predeterminados estén en archivos de configuración, funciones compartidas o variables de entorno.

# macOS, Linux, WSL: busca en el proyecto (sin distinguir mayúsculas y minúsculas)
grep -rniE "temperature|top_p|top_k" --exclude-dir={node_modules,.venv,venv,.git,dist} \
  --include="*.py" --include="*.ts" --include="*.js" --include="*.json" \
  --include="*.yaml" --include="*.yml" --include="*.toml" --include=".env*" .

# Windows (PowerShell)
Get-ChildItem -Recurse -Include *.py,*.ts,*.js,*.json,*.yaml,*.yml,*.toml,.env* |
  Where-Object { $_.FullName -notmatch "node_modules|\\.?venv|\\.git\\|\\dist\\" } |
  Select-String -Pattern "temperature|top_p|top_k"

Las reglas de la nueva versión de la API se aplican a las solicitudes de la Messages API, a las solicitudes de conteo de tokens y a cada solicitud de Message Batches (guía de migración de Anthropic).

4. Qué ocurre al actualizar el SDK

Los SDK oficiales envían automáticamente la versión de la API que estaba vigente cuando salió su versión mayor. A partir de las versiones de SDK de la tabla siguiente, envían 2026-10-21, y los tres parámetros eliminados también han desaparecido de los tipos del SDK (guía de migración de Anthropic). Por eso, al actualizar el SDK, el problema puede aparecer primero como un error de comprobación de tipos o de «argumento no esperado», en lugar de como un 400 de la API. Si añades parámetros al cuerpo sin pasar por los tipos (por ejemplo, con una función que envía campos adicionales en el cuerpo, o si envías solicitudes directamente por HTTP), la API devuelve un 400. La solución es la misma en ambos casos: eliminar los tres parámetros.

Fuente: Anthropic, «Migrating to API version 2026-10-21», Upgrade steps. Si llamas a la API sin SDK, define el encabezado anthropic-version como 2026-10-21 para usar la nueva versión de la API.

La nueva versión de la API está disponible en la Claude API, en Claude Platform on AWS, en Claude en Google Cloud (tanto administrado por Anthropic como por Google) y en Microsoft Foundry. En Amazon Bedrock, la nueva versión solo está disponible para los modelos Claude 4.7 y posteriores. Si llamas allí a modelos anteriores, Anthropic recomienda mantener la versión actual del SDK (o tu anthropic-version actual) (Versions).

Pasos para actualizar el SDK

1. Cambia a la nueva versión de la APIActualiza el SDK a la versión de la tabla anterior. Si llamas a HTTP directamente, define anthropic-version: 2026-10-21.
2. Corrige los cambios incompatiblesElimina los tres parámetros y corrige los elementos de la tabla del apartado 5 que te afecten. Revisa también los cambios en la forma de escribir del SDK nuevo (como los nombres de los tipos) en «SDK and CLI changes» de la guía de migración.
3. Prueba con la nueva versión de la API antes de publicarAntes de pasar a producción, comprueba que tus solicitudes funcionan con la nueva versión de la API. Publica la actualización del SDK y las correcciones en la misma versión.

Fuente: Anthropic, «Migrating to API version 2026-10-21», Upgrade steps (Switch to 2026-10-21 → Update your code for the breaking changes → Test against 2026-10-21).

5. Otros cambios que corregir con la nueva versión de la API

Si cambias a la nueva versión de la API, hay otros cambios además de temperature. (La fila de la clave de API solo corresponde a cambios del SDK y de la CLI; no afecta si llamas a HTTP directamente). Corrige solo los que te afecten (Breaking changes de la misma guía de migración).

6. Cómo solucionar anthropic-version: header is required

El siguiente error aparece cuando una solicitud no tiene el encabezado de la versión de la API.

400 invalid_request_error
anthropic-version: header is required

Los SDK oficiales envían la versión de la API automáticamente, así que este error aparece sobre todo cuando se llama a HTTP directamente, sin SDK. Por ejemplo, en GitHub hay informes de que aparece cuando alguien apunta un cliente o una herramienta pensada para OpenAI a la URL de la API de Claude e intenta listar los modelos (/v1/models) (Ejemplo 1, Ejemplo 2).

La solución es añadir el encabezado. Si escribes código nuevo, usa 2026-10-21; para que el código actual funcione sin cambios, usa 2023-06-01.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello, Claude"}]}'

Fuente: Anthropic, «Versions» (la solicitud requiere el encabezado anthropic-version; los SDK lo envían automáticamente). El mensaje de error procede de una respuesta de la API que un usuario informó en GitHub. La API acepta la clave de API en el encabezado x-api-key o en Authorization: Bearer (guía de migración).

Si la herramienta que usas no te permite añadir encabezados, comprueba si esa herramienta es compatible con la API de Claude (y si la estás llamando como si usara el formato de OpenAI).

Resumen

Preguntas frecuentes

P. ¿Puedo enviar temperature con 1.0 (el valor predeterminado)?

Con la nueva versión de la API 2026-10-21, enviarlo devuelve un 400 incluso con el valor predeterminado. Si llamas a un modelo Claude 4.7 o posterior con 2023-06-01, el valor predeterminado funciona, pero no tiene sentido enviarlo, así que eliminarlo es lo más seguro.

P. Usaba temperature = 0 para obtener siempre la misma respuesta. ¿Qué uso en su lugar?

No hay ningún ajuste que lo sustituya. La guía de migración de Anthropic indica que, incluso con temperature = 0, nunca hubo garantía de respuestas idénticas. Si quieres estandarizar el formato de la respuesta (como los campos de un JSON), usa Salidas estructuradas, y especifica con detalle la redacción y los criterios de decisión en el prompt.

P. ¿Puedo seguir usando la versión actual sin cambiar a la nueva versión de la API?

Sí. Anthropic indica que mantiene los campos de entrada y salida existentes en cada versión de la API, y que 2023-06-01 se puede seguir especificando como antes. La página de Versions no indica cuándo se dejará de ofrecer 2023-06-01 (Versions, consultada el 26 de octubre de 2026). Sin embargo, con los modelos Claude 4.7 y posteriores, un temperature u otro valor no predeterminado sigue devolviendo un 400 aunque uses 2023-06-01. Además, Anthropic recomienda usar la versión más reciente de la API siempre que sea posible, y al actualizar el SDK pasas automáticamente a la nueva.

P. Cambié a un modelo Claude 4.7 o posterior y aparece un error

Al cambiar a un modelo Claude 4.7 o posterior, un temperature u otro valor no predeterminado sigue devolviendo un 400 aunque la versión de la API no cambie. Para otros puntos que corregir al cambiar de modelo (como la configuración de thinking o el prefill), consulta la «Guía de migración de Claude Opus 4.7».