Guía de migración a Claude Haiku 5.5

Esta guía cubre cómo migrar código que llama a Claude Haiku 4.5 a Claude Haiku 5.5. Para código que llama a Claude Haiku 3.5 o Claude Haiku 3, realiza también los cambios de Migrar a Claude Haiku 5.5 desde Claude Haiku 3.5 y modelos Haiku anteriores. Para pasar en su lugar a un modelo Sonnet u Opus, consulta Actualizar entre versiones de modelos. Para saber cuánto tiempo seguirá disponible Claude Haiku 4.5, consulta Deprecaciones de modelos.

Lista de verificación de migración por modelo de partida

Recorre los grupos en orden y detente después del que nombra tu modelo actual. Si usas Claude Haiku 4.5, el primer grupo es la lista completa. Cada elemento es un cambio que debes hacer en tu código.

Todos los modelos de partida

1. Reemplaza el ID de modelo por el ID de Claude Haiku 5.5 para tu plataforma. Consulta Usa el ID de modelo de Claude Haiku 5.5.
2. Vuelve a contar los tokens de tus prompts y revisa los límites de max_tokens y las estimaciones de costos, porque el mismo texto cuenta como más tokens y las imágenes grandes cuentan como más tokens visuales. Consulta Vuelve a contar los tokens.
3. Si tus solicitudes envían thinking: {"type": "enabled", "budget_tokens": N}, cambia thinking a {"type": "adaptive"}. Consulta Configura el pensamiento.
4. Si tu código lee el primer bloque de contenido como la respuesta, selecciona los bloques por type en su lugar. Consulta Configura el pensamiento.
5. Elimina temperature, top_p y top_k de tus solicitudes. Consulta Elimina los parámetros de muestreo.
6. Si tus solicitudes terminan messages con un turno del asistente para que el modelo lo continúe, termínalas con un turno del usuario en su lugar. Consulta Reemplaza el prefill del asistente.
7. Si usas el uso de computadora, reemplaza computer_20250124: en la Claude API y Google Cloud, por el conjunto de herramientas computer_toolset_20260801; en Amazon Bedrock, por computer_20251124 y el encabezado beta computer-use-2025-11-24. Consulta Migra el uso de computadora al conjunto de herramientas.
8. Si reproduces conversaciones almacenadas a través de una cuenta diferente, reproduce cada una a través de la cuenta que la produjo. Consulta Reproduce los bloques de pensamiento a través de la cuenta que los produjo.
9. Si tu código cambia system, tools o messages anteriores entre solicitudes de una conversación y devuelve bloques de pensamiento, mantén la conversación en modo de solo anexar. Consulta Mantén sin cambios los turnos anteriores.
10. Maneja stop_reason: "refusal". Claude Haiku 5.5 ejecuta clasificadores de seguridad que pueden rechazar una solicitud, y no tiene fallback del lado del servidor. Consulta Rechazos de las salvaguardas.
11. Si usas salidas estructuradas (output_config.format o herramientas con strict: true) en Amazon Bedrock, describe el formato en el prompt o usa una herramienta sin strict, y valida la salida en tu código. Las salidas estructuradas no están disponibles para Claude Haiku 5.5 en Amazon Bedrock.

Si tu organización tiene un compromiso de Priority Tier en Claude Haiku 4.5, planifica la capacidad por separado: Priority Tier no es compatible con Claude Haiku 5.5.

Claude Haiku 3.5 o anterior

1. Reemplaza el ID de modelo de Claude Haiku 3.5 o Claude Haiku 3 por el ID de Claude Haiku 5.5 para tu plataforma. Consulta Migrar a Claude Haiku 5.5 desde Claude Haiku 3.5 y modelos Haiku anteriores.
2. Si usas la herramienta heredada code_execution_20250522, pasa a code_execution_20250825 o posterior.
3. Si usas la herramienta de editor de texto, pasa a text_editor_20250728.
4. Maneja los motivos de detención refusal y model_context_window_exceeded.
5. Si tu código compara exactamente los parámetros de cadena de las llamadas a herramientas, ten en cuenta los saltos de línea finales.
6. Revisa tus prompts.

Usa el ID de modelo de Claude Haiku 5.5

Reemplaza el ID de modelo de Claude Haiku 4.5 por el ID de Claude Haiku 5.5 para tu plataforma.

claude-haiku-5-5 es un ID de modelo fijo sin sufijo de fecha y sin un alias separado.

Vuelve a contar los tokens

Claude Haiku 5.5 usa el mismo "tokenizer" (tokenizador) más reciente que Claude 4.7 y los modelos posteriores. Como ocurre con todos los modelos que usan este tokenizador, el mismo texto de entrada produce aproximadamente un 30% más de tokens en Claude Haiku 5.5 que en Claude Haiku 4.5. El aumento exacto depende del contenido. Las solicitudes, las respuestas y los eventos de streaming mantienen la misma forma. Lo que cambia es todo lo que midas o presupuestes en tokens:

• Los campos de usage y los resultados del conteo de tokens son más altos para el mismo texto.
• Una cantidad determinada de tokens contiene menos texto.
• Un límite de max_tokens ajustado para Claude Haiku 4.5 puede cortar una salida equivalente.
• Las estimaciones de costos hechas a partir de los conteos de tokens de Claude Haiku 4.5 deben recalcularse con los conteos y los precios de Claude Haiku 5.5, incluidos sus precios más altos para prompts largos. Consulta Precios de contexto largo.

Las imágenes grandes también pueden costar más tokens. Claude Haiku 5.5 usa el nivel de imagen de alta resolución, que reduce la escala de las imágenes de más de 2,576 píxeles en el lado largo o de más de 4,784 tokens visuales. Claude Haiku 4.5 y los modelos Haiku anteriores usan el nivel estándar, que reduce la escala de las imágenes de más de 1,568 píxeles en el lado largo o de más de 1,568 tokens visuales. Una imagen de 2,000 por 1,500 píxeles cuesta aproximadamente 2.5 veces más tokens visuales en Claude Haiku 5.5 que en Claude Haiku 4.5. Consulta Resolución y costo en tokens.

Cuenta tus prompts con model establecido en claude-haiku-5-5 en lugar de reutilizar los conteos medidos en Claude Haiku 4.5.

Configura el pensamiento

Claude Haiku 5.5 configura el pensamiento de forma diferente a Claude Haiku 4.5. Un valor de thinking de {"type": "enabled", "budget_tokens": N} devuelve un error 400, por lo que una solicitud que lo envíe necesita un nuevo valor de thinking.

Antes, una solicitud a Claude Haiku 4.5 establecía thinking en enabled con un presupuesto de tokens:

{
  "model": "claude-haiku-4-5",
  "max_tokens": 16000,
  "thinking": { "type": "enabled", "budget_tokens": 8000 },
  "messages": [{ "role": "user", "content": "..." }]
}

Después, la misma solicitud a Claude Haiku 5.5 usa el "adaptive thinking" (pensamiento adaptativo). El valor de thinking cambia, y output_config.effort establece cuánto piensa el modelo:

{
  "model": "claude-haiku-5-5",
  "max_tokens": 16000,
  "thinking": { "type": "adaptive" },
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

El pensamiento adaptativo está activado de forma predeterminada, por lo que una respuesta puede comenzar con uno o más bloques thinking incluso cuando la solicitud no establece thinking. Deja thinking sin establecer o establécelo en {"type": "adaptive"}, y usa el esfuerzo como palanca: donde Claude Haiku 4.5 se ejecutaba sin pensamiento, o con un presupuesto pequeño para ahorrar tokens, elige un nivel de esfuerzo más bajo. En un nivel más bajo, el modelo piensa menos y puede omitir el pensamiento por completo en solicitudes más simples. Para obtener orientación sobre prompts, consulta Usa el esfuerzo para controlar el pensamiento. Selecciona los bloques de contenido por su campo type en lugar de por su posición, y devuelve los bloques thinking sin modificar junto con los resultados de las herramientas.

Los tokens de pensamiento cuentan para max_tokens, por lo que una solicitud con un max_tokens pequeño puede detenerse con stop_reason: "max_tokens" después de un bloque thinking y antes de cualquier texto. Si estableciste un max_tokens pequeño para Claude Haiku 4.5, auméntalo para dejar espacio para el pensamiento, o elige un nivel de esfuerzo más bajo.

Los bloques de pensamiento de turnos anteriores del asistente permanecen en el contexto y cuentan como tokens de entrada, mientras que Claude Haiku 4.5 conservaba solo los del último turno. Por lo tanto, las conversaciones de varios turnos llevan más tokens de entrada de lo que explica el cambio de tokenizador por sí solo. Para eliminar los bloques más antiguos, usa la eliminación de bloques de pensamiento. Consulta Preservación de bloques de pensamiento por modelo.

De forma predeterminada, Claude Haiku 5.5 devuelve cada bloque thinking con un campo thinking vacío y solo una signature, mientras que Claude Haiku 4.5 devolvía el pensamiento resumido. Para recibir el pensamiento resumido, establece thinking: {"type": "adaptive", "display": "summarized"}.

Claude Haiku 5.5 acepta un tool_choice forzado (any o una herramienta con nombre), pero la respuesta comienza con la llamada a la herramienta y no tiene ningún bloque thinking. Para permitir que el modelo piense antes de llamar a una herramienta, usa tool_choice: {"type": "auto"} e indica en el prompt cuándo usar la herramienta.

Claude Haiku 5.5 lee los bloques de pensamiento de Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 y modelos anteriores, por lo que una conversación que cambies de Claude Haiku 4.5 a Claude Haiku 5.5 conserva su razonamiento. No lee los bloques de Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 ni de ningún modelo Claude Fable o Claude Mythos; la API los descarta sin error. En la Claude API y Google Cloud, Claude Opus 5.5 y Claude Sonnet 5.5 leen los bloques de Claude Haiku 5.5. Consulta Cambiar de modelo a mitad de la conversación.

Elimina los parámetros de muestreo

Claude Haiku 4.5 acepta temperature, top_p y top_k. En Claude Haiku 5.5, omite los tres y usa los prompts para guiar el comportamiento del modelo en su lugar. Si una solicitud incluye temperature, debe ser 1. Si incluye top_p, debe ser 0.99, su valor predeterminado. Cualquier otro valor de temperature o top_p devuelve un error 400, incluido un top_p de 1. Lo mismo ocurre con cualquier valor de top_k, y con una solicitud que incluya tanto temperature como top_p.

Reemplaza el prefill del asistente

Un "prefill" (prellenado) es un turno final del asistente en messages que el modelo continúa. Claude Haiku 4.5 lo acepta cuando el pensamiento está desactivado. Claude Haiku 5.5 lo rechaza con un error 400, incluso con el pensamiento desactivado. Termina messages con un turno del usuario y reemplaza cada prefill según su propósito:

• Formato de salida: usa salidas estructuradas, o herramientas con campos enum para la clasificación. En Amazon Bedrock, las salidas estructuradas no están disponibles para Claude Haiku 5.5. Allí, describe el formato en el prompt o usa una herramienta sin strict, y valida la salida en tu código.
• Preámbulos: pide en la indicación del sistema una respuesta directa.
• Continuaciones: muévelas al mensaje del usuario, por ejemplo "Tu respuesta anterior se interrumpió y terminó con [previous_response]. Continúa desde donde te quedaste."
• Recordatorios de contexto: colócalos en el turno del usuario.

Migra el uso de computadora al conjunto de herramientas

Claude Haiku 4.5 admite el "computer use" (uso de computadora) mediante la herramienta computer_20250124, con el encabezado beta computer-use-2025-01-24. En la Claude API y Google Cloud, Claude Haiku 5.5 admite el uso de computadora solo mediante el conjunto de herramientas computer_toolset_20260801, y una solicitud que declare computer_20250124 devuelve un error 400. En Amazon Bedrock, Claude Haiku 5.5 tampoco acepta computer_20250124; usa la versión de herramienta computer_20251124 con el encabezado beta computer-use-2025-11-24.

Para trasladar una integración al conjunto de herramientas, elimina el encabezado beta computer-use-2025-01-24 y reemplaza la entrada de tools por {"type": "computer_toolset_20260801"}. Luego realiza los demás cambios en la solicitud y en el bucle del agente descritos en Migrar desde computer_20251124: despacha según el name y el toolset_name de cada bloque tool_use miembro en lugar de según input.action, gestiona todos esos bloques en un turno y repite toolset_name en los resultados. El zoom está activado de forma predeterminada en el conjunto de herramientas; si tu entorno no lo implementa, agrega "configs": {"zoom": {"enabled": false}}. Si envías el encabezado beta fine-grained-tool-streaming-2025-05-14, elimínalo. Junto con una entrada de conjunto de herramientas, devuelve un error 400. Para otras plataformas, consulta la sección Compatibilidad de la herramienta de uso de computadora.

En la Claude API y en Google Cloud, Claude Haiku 5.5 también admite la herramienta de uso del navegador (browser_toolset_20260801) para tareas dentro de páginas web. Claude Haiku 4.5 no la admite.

Reproduce los bloques de pensamiento a través de la cuenta que los produjo

Los bloques de pensamiento de Claude Haiku 5.5 funcionan solo en la cuenta que los produjo, o en una cuenta vinculada a ella. Cuando otra cuenta envía uno de estos bloques, la API descarta el bloque antes de que el modelo lo vea, y la solicitud se completa correctamente sin ese razonamiento. Esto afecta al código que almacena conversaciones y las reproduce a través de una cuenta diferente, por ejemplo, un servicio que atiende a varios clientes desde un único almacén de conversaciones. Reproduce cada conversación a través de la cuenta que la produjo. Consulta Los bloques de pensamiento permanecen con la cuenta que los produjo.

Mantén sin cambios los turnos anteriores

Un bloque de pensamiento de Claude Haiku 5.5 sigue siendo válido solo mientras todo lo enviado antes de él permanezca sin cambios: una solicitud que devuelve un bloque de pensamiento después de un cambio en system, tools o messages anteriores devuelve un error 400. Claude Haiku 4.5 no realiza esta comprobación. Mantén las conversaciones en modo de solo anexar. En las cuentas creadas antes del 31 de agosto de 2026, 00:00 UTC, el error se produce solo en las solicitudes que establecen thinking.block_binding.prefix_mismatch_behavior. Para conocer los cambios que provocan el error y qué hacer en su lugar, consulta Quién necesita cambiar algo.

Migrar a Claude Haiku 5.5 desde Claude Haiku 3.5 y modelos Haiku anteriores

Claude Haiku 3.5 está retirado en la Claude API y Amazon Bedrock, y Claude Haiku 3 está retirado en la Claude API y Google Cloud. Las solicitudes a un modelo retirado fallan. Google Cloud indica que Claude Haiku 3.5 está obsoleto y disponible solo para clientes existentes. Consulta Deprecaciones de modelos.

Desde cualquiera de los dos modelos, aplica primero todas las secciones anteriores y luego estos cambios:

• ID de modelo: Reemplaza claude-3-5-haiku-20241022, su alias claude-3-5-haiku-latest o claude-3-haiku-20240307 por claude-haiku-5-5. En Google Cloud, reemplaza claude-3-5-haiku@20241022 por claude-haiku-5-5. En Amazon Bedrock, usa el ID de Claude Haiku 5.5 de Usa el ID de modelo de Claude Haiku 5.5.
• Ejecución de código: Claude Haiku 5.5 acepta code_execution_20250825 y versiones posteriores. Si usas la herramienta heredada code_execution_20250522, solo para Python, pasa a una de ellas. Consulta Actualizar a la última versión de la herramienta.
• Editor de texto: Si usas la herramienta de editor de texto, pasa a text_editor_20250728 (nombre de herramienta str_replace_based_edit_tool), que no tiene el comando undo_edit. Consulta Herramienta de editor de texto.
• Motivos de detención: Maneja refusal y model_context_window_exceeded. Consulta Manejo de motivos de detención.
• Saltos de línea finales: Claude 4.5 y los modelos posteriores conservan los saltos de línea finales en los parámetros de cadena de las llamadas a herramientas. Si tu código compara esas cadenas exactamente, tenlos en cuenta.
• Prompts: Claude 4 y los modelos posteriores tienen un estilo de comunicación más conciso y directo, y necesitan instrucciones explícitas. Revisa tus prompts según Cómo escribir prompts para Claude Haiku 5.5 y las mejores prácticas de prompting.