Guía de migración

/claude-api migrate this project to claude-opus-5



Migrar a Claude Mythos 5 y Claude Fable 5

Claude Fable 5 es el modelo más capaz de Anthropic lanzado de forma amplia, disponible de manera general en la Claude API, Amazon Bedrock, Claude Platform en AWS, Google Cloud y Microsoft Foundry. Claude Mythos 5 comparte las mismas capacidades y se ofrece con disponibilidad limitada a clientes aprobados en Project Glasswing.

La configuración base compartida por claude-fable-5 y claude-mythos-5:

• Pensamiento: El pensamiento adaptativo está siempre activado. El modelo determina cuándo y cuánto pensar en cada solicitud, y no se requiere ninguna configuración de thinking. Tanto thinking: {type: "disabled"} como el pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) devuelven un error 400.
• Prefill: Prellenar el mensaje del asistente devuelve un error 400. Usa instrucciones en la indicación del sistema en su lugar.
• Ventana de contexto y salida: Una ventana de contexto de 1M de tokens de forma predeterminada, y hasta 128k tokens de salida por solicitud.
• Precios: $10 USD por millón de tokens de entrada y $50 USD por millón de tokens de salida. Consulta los precios de Claude.
• Retención de datos: Ambos modelos requieren retención de datos de 30 días y no están disponibles bajo acuerdos de retención cero de datos (ZDR); ambos están designados como Covered Models. En la Claude API, una solicitud a Claude Fable 5 desde una organización cuya configuración de retención de datos no cumple este requisito devuelve un error 400 invalid_request_error. Las organizaciones con un acuerdo ZDR deben contactar a su equipo de cuenta de Anthropic para discutir la configuración de retención de datos. Alternativamente, puedes configurar la retención de datos por workspace. Consulta Requisitos de retención de datos específicos por modelo para detalles por plataforma.

Dónde divergen los dos modelos:

• Disponibilidad: Claude Fable 5 está disponible de manera general. Claude Mythos 5 está disponible solo para clientes aprobados en Project Glasswing.
• Clasificadores de seguridad: Claude Fable 5 ejecuta clasificadores de seguridad que pueden rechazar solicitudes con stop_reason: "refusal". Claude Mythos 5 no incluye estos clasificadores. Consulta Rechazos y fallback.
• Priority Tier: Priority Tier es compatible con Claude Fable 5 pero no con Claude Mythos 5.



Migrar a Claude Mythos 5 y Claude Fable 5 desde Claude Mythos Preview

Claude Mythos 5 es el sucesor con acceso restringido de Claude Mythos Preview, la vista previa de investigación solo por invitación. Claude Fable 5 es el modelo disponible de manera general con las mismas capacidades, y los cambios en esta sección se aplican por igual a ambos destinos.

La migración es en su mayoría directa. Claude Mythos 5 y Claude Fable 5 usan la misma Messages API y los mismos patrones de uso de herramientas que Claude Mythos Preview, y los conteos de tokens son aproximadamente los mismos porque los tres modelos usan el mismo tokenizador. Los cambios clave a verificar son las funcionalidades que ya no están disponibles (listadas en la siguiente sección) y la salida de pensamiento. Si migras a Claude Fable 5, también planifica para los rechazos del clasificador de seguridad, que Claude Mythos Preview y Claude Mythos 5 no tienen; consulta Rechazos y fallback.

Para el cronograma de retiro de Claude Mythos Preview, consulta Desaprobaciones de modelos.



Actualiza el nombre de tu modelo

model = "claude-mythos-preview"  # Before
model = "claude-mythos-5"  # After

# O, para el modelo disponible de forma general con las mismas capacidades:
model = "claude-fable-5"  # After



Funcionalidades no disponibles en Claude Mythos 5 y Claude Fable 5

1. Pensamiento extendido y presupuestos de tokens de pensamiento: El pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) no es compatible con claude-mythos-5 ni claude-fable-5 y devuelve un error 400. El pensamiento adaptativo está siempre activado: el modelo determina cuándo y cuánto pensar en cada solicitud, y no se requiere ninguna configuración de thinking. thinking: {type: "disabled"} devuelve un error. budget_tokens no tiene un reemplazo directo: el pensamiento es adaptativo, y el parámetro effort es un control separado a nivel de salida, no un presupuesto de pensamiento.

   Antes (Claude Mythos Preview):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-mythos-preview",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[{"role": "user", "content": "..."}],
   )

   Después (Claude Mythos 5):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-mythos-5",
       max_tokens=16000,
       messages=[{"role": "user", "content": "..."}],
   )

   El cambio para Claude Fable 5 es idéntico, con claude-fable-5 como nombre del modelo.

2. Prefill del asistente: Prellenar el mensaje del asistente no es compatible con claude-mythos-5 ni claude-fable-5 y devuelve un error 400, igual que en Claude Mythos Preview. Usa instrucciones en la indicación del sistema en su lugar.

3. Salida de pensamiento: En claude-mythos-5 y claude-fable-5, la cadena de pensamiento sin procesar nunca se devuelve, pero los bloques de pensamiento aún contienen texto resumido legible cuando thinking.display está configurado en summarized. Devuelve los bloques de pensamiento sin cambios al continuar una conversación en el mismo modelo. Consulta Salida de pensamiento en Claude Fable 5 y Claude Mythos 5.



Conteo de tokens y facturación

claude-mythos-5 y claude-fable-5 usan el mismo tokenizador que claude-mythos-preview (el tokenizador introducido con Claude Opus 4.7). Los conteos de tokens son aproximadamente los mismos al migrar desde claude-mythos-preview. En comparación con los modelos anteriores a Claude Opus 4.7, el mismo contenido puede tokenizarse en aproximadamente un 30% más de tokens, variando según el contenido y la forma de la carga de trabajo.

/v1/messages/count_tokens devuelve valores aproximadamente iguales para claude-mythos-5 y claude-fable-5 en comparación con claude-mythos-preview. Vuelve a establecer una línea base de costo y latencia en tus propias cargas de trabajo.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-mythos-preview a claude-mythos-5, o a claude-fable-5 para el modelo disponible de manera general.
• Elimina la configuración de pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}). El pensamiento adaptativo está siempre activado, y no se requiere ningún campo thinking.
• Elimina cualquier configuración thinking: {type: "disabled"}. Deshabilitar el pensamiento devuelve un error en claude-mythos-5 y claude-fable-5.
• Elimina budget_tokens. No tiene un reemplazo directo: el pensamiento es adaptativo, y el parámetro effort es un control separado a nivel de salida, no un presupuesto de pensamiento.
• Verifica que cualquier código que analice el campo thinking lo trate solo como texto de visualización y devuelva los bloques de pensamiento sin cambios al continuar en el mismo modelo. thinking.display tiene como valor predeterminado "omitted" en claude-mythos-5 y claude-fable-5, igual que en Claude Mythos Preview; configura display: "summarized" para recibir resúmenes legibles. Consulta Salida de pensamiento en Claude Fable 5 y Claude Mythos 5.
• Si reproduces el historial de conversación en otro modelo, primero elimina los bloques thinking y redacted_thinking de los turnos anteriores del asistente. Los bloques de pensamiento de claude-mythos-5 y claude-fable-5 están vinculados al modelo que los produjo, y los modelos distintos de Claude Fable 5 y Claude Mythos 5 los ignoran silenciosamente. Eliminarlos mantiene las solicitudes entre modelos mínimas y uniformes.
• Si migras a Claude Fable 5, maneja stop_reason: "refusal" y lee el campo stop_details.category. Claude Fable 5 ejecuta clasificadores de seguridad que Claude Mythos Preview y Claude Mythos 5 no tienen. Consulta Rechazos y fallback.
• Vuelve a establecer una línea base de conteos de tokens y costos en tus propias cargas de trabajo. Los conteos de tokens son aproximadamente los mismos al migrar desde claude-mythos-preview.



Migrar a Claude Mythos 5 y Claude Fable 5 desde Claude Opus 5

Claude Fable 5 y Claude Mythos 5 usan la misma Messages API y los mismos patrones de uso de herramientas que Claude Opus 5, con la misma ventana de contexto de 1M de tokens de forma predeterminada y el mismo máximo de 128k tokens de salida. Las restricciones de prefill y de parámetros de muestreo, y el comportamiento de visualización del pensamiento, se mantienen sin cambios desde Claude Opus 5. Los cambios a verificar son el pensamiento siempre activado, los precios, Priority Tier y la retención de datos.



Actualiza el nombre de tu modelo

model = "claude-opus-5"  # Before
model = "claude-fable-5"  # After

# O, para el modelo de Project Glasswing con las mismas capacidades:
model = "claude-mythos-5"  # After



Qué cambió

1. El pensamiento ya no se puede deshabilitar: En Claude Opus 5, el pensamiento está activado de forma predeterminada y se puede desactivar con thinking: {type: "disabled"} en un nivel de effort de high o inferior. En claude-fable-5 y claude-mythos-5, el pensamiento adaptativo está siempre activado, y thinking: {type: "disabled"} devuelve un error 400 en cualquier nivel de effort. Elimina la configuración thinking: {type: "disabled"} y usa niveles de effort más bajos para controlar el gasto de tokens en su lugar.

2. Precios: Claude Fable 5 y Claude Mythos 5 tienen un precio de $10 USD por millón de tokens de entrada y $50 USD por millón de tokens de salida, en comparación con $5 USD y $25 USD para Claude Opus 5. Consulta los precios de Claude.

3. Priority Tier: Priority Tier no es compatible con Claude Opus 5, por lo que ningún tráfico existente se ve afectado. Si tu organización tiene un compromiso de Priority Tier, Claude Fable 5 lo admite; Claude Mythos 5 no.

4. Retención de datos: Claude Fable 5 y Claude Mythos 5 requieren retención de datos de 30 días y no están disponibles bajo acuerdos de retención cero de datos (ZDR); ambos están designados como Covered Models. Consulta Requisitos de retención de datos específicos por modelo.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-5 a claude-fable-5 (o claude-mythos-5).
• Elimina cualquier configuración thinking: {type: "disabled"}; devuelve un error 400 en claude-fable-5 y claude-mythos-5. Usa niveles de effort más bajos para controlar el gasto de tokens en su lugar, y revisa max_tokens para las cargas de trabajo que se ejecutaban con el pensamiento deshabilitado en Claude Opus 5.
• Si tu organización tiene un acuerdo de retención cero de datos (ZDR), confirma la elegibilidad antes de migrar. Consulta Requisitos de retención de datos específicos por modelo.
• Vuelve a establecer una línea base de costo en tus propias cargas de trabajo. Los conteos de tokens son aproximadamente los mismos; el precio por token difiere.



Migrar a Claude Mythos 5 y Claude Fable 5 desde Claude Opus 4.8

La migración es en su mayoría directa. Claude Fable 5 y Claude Mythos 5 usan la misma Messages API y los mismos patrones de uso de herramientas que Claude Opus 4.8, con la misma ventana de contexto de 1M de tokens de forma predeterminada y el mismo máximo de 128k tokens de salida. Los conteos de tokens son aproximadamente los mismos porque los modelos usan el mismo tokenizador. Los cambios clave a verificar son el pensamiento adaptativo siempre activado, la salida de pensamiento, los rechazos del clasificador de seguridad (solo Claude Fable 5) y los precios.



Actualiza el nombre de tu modelo

model = "claude-opus-4-8"  # Before
model = "claude-fable-5"  # After

# O, para el modelo de Project Glasswing con las mismas capacidades:
model = "claude-mythos-5"  # After



Qué cambió

Los elementos de esta sección describen las diferencias de API y de comportamiento que vale la pena verificar después de cambiar el ID del modelo. Excepto donde se indique, se aplican por igual a claude-fable-5 y claude-mythos-5.

1. El pensamiento adaptativo está siempre activado: El pensamiento adaptativo es el único modo de pensamiento en claude-fable-5 y claude-mythos-5. El modelo determina cuándo y cuánto pensar en cada solicitud, y no se requiere ninguna configuración de thinking. thinking: {type: "disabled"} devuelve un error. Usa el parámetro effort para controlar la profundidad del pensamiento.

   El cambio de comportamiento a verificar: en Claude Opus 4.8, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en claude-fable-5 y claude-mythos-5, esas mismas solicitudes se ejecutan con pensamiento adaptativo. max_tokens sigue siendo un límite estricto sobre la salida total, pensamiento más texto de respuesta, así que revísalo para las cargas de trabajo que se ejecutaban sin pensamiento en Claude Opus 4.8. Consulta Control de costos.

   Antes (Claude Opus 4.8):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-opus-4-8",
       max_tokens=16000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},
       messages=[{"role": "user", "content": "..."}],
   )

   Después (Claude Fable 5):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-fable-5",
       max_tokens=16000,
       output_config={"effort": "high"},
       messages=[{"role": "user", "content": "..."}],
   )

   El cambio para Claude Mythos 5 es idéntico, con claude-mythos-5 como nombre del modelo.

2. Pensamiento extendido y presupuestos de pensamiento (sin cambios): El pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) no es compatible con claude-fable-5 ni claude-mythos-5 y devuelve un error 400, igual que en Claude Opus 4.8. budget_tokens no tiene un reemplazo directo: el pensamiento es adaptativo, y el parámetro effort es un control separado a nivel de salida, no un presupuesto de pensamiento.

3. Prefill del asistente (sin cambios): Prellenar el mensaje del asistente no es compatible con claude-fable-5 ni claude-mythos-5 y devuelve un error 400, igual que en Claude Opus 4.8. Usa instrucciones en la indicación del sistema en su lugar.

4. Salida de pensamiento: En claude-fable-5 y claude-mythos-5, la cadena de pensamiento sin procesar nunca se devuelve, pero los bloques de pensamiento aún contienen texto resumido legible cuando thinking.display está configurado en summarized. Devuelve los bloques de pensamiento sin cambios al continuar una conversación en el mismo modelo. Consulta Salida de pensamiento en Claude Fable 5 y Claude Mythos 5.

5. Clasificadores de seguridad y la razón de detención refusal (solo Claude Fable 5): claude-fable-5 ejecuta clasificadores de seguridad en las solicitudes y durante la generación de respuestas. Claude Mythos 5 no incluye estos clasificadores. Cuando un clasificador rechaza una solicitud, la Messages API devuelve stop_reason: "refusal" como una respuesta HTTP 200 exitosa, no como un error. El campo stop_details.category informa qué clasificador se activó, con categorías como "cyber", "bio" y "reasoning_extraction", o null cuando el rechazo no corresponde a ninguna categoría nombrada. Consulta la tabla de categorías de rechazo para el conjunto completo.

   No se te factura por los tokens de entrada de una solicitud rechazada antes de que se genere cualquier salida. Cuando un clasificador se activa a mitad del stream, la entrada y la salida ya transmitida se facturan; descarta la salida parcial.

   Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, pasa el parámetro opcional fallbacks, que está en beta en la Claude API. El parámetro no está disponible en la Message Batches API ni en Amazon Bedrock, Google Cloud y Microsoft Foundry; en esas tres plataformas, ejecuta el reintento del lado del cliente o usa el middleware de refusal-fallback del SDK. Consulta Rechazos y fallback.

6. Comienza con effort high: El valor predeterminado del parámetro effort sigue siendo high. En Claude Opus 4.8, la recomendación para trabajo de codificación y de alta autonomía es establecer xhigh explícitamente. En claude-fable-5 y claude-mythos-5, usa high como valor predeterminado para la mayoría de las tareas y reserva xhigh para las cargas de trabajo más sensibles a la capacidad. Los niveles de effort más bajos siguen funcionando bien y a menudo superan el rendimiento de xhigh en modelos anteriores. Reduce el effort si una tarea se completa pero tarda más de lo necesario. Consulta Prompting para Claude Fable 5.

7. Mínimo más bajo para el almacenamiento en caché de prompts: La longitud mínima de prompt almacenable en caché en claude-fable-5 y claude-mythos-5 es de 512 tokens, menor que los 1,024 tokens en Claude Opus 4.8. Los prompts que eran demasiado cortos para almacenarse en caché en Claude Opus 4.8 ahora pueden crear entradas de caché, sin necesidad de cambios en el código. Consulta Almacenamiento en caché de prompts para los mínimos por modelo.



Lista de verificación de migración

• Si tu organización tiene un acuerdo de retención cero de datos (ZDR), confirma la elegibilidad antes de migrar. claude-fable-5 y claude-mythos-5 requieren retención de datos de 30 días; en la Claude API, las solicitudes a claude-fable-5 que no cumplen este requisito devuelven un error 400 invalid_request_error. Claude Opus 4.8 sigue disponible bajo ZDR. Consulta Requisitos de retención de datos específicos por modelo.
• Actualiza el nombre del modelo de claude-opus-4-8 a claude-fable-5 (o claude-mythos-5).
• Elimina cualquier configuración thinking: {type: "disabled"}. Deshabilitar el pensamiento devuelve un error en claude-fable-5 y claude-mythos-5, y las solicitudes sin un campo thinking se ejecutan con pensamiento adaptativo.
• Si eliminaste el pensamiento extendido manual y los prefills del asistente durante migraciones anteriores, no se necesita ninguna acción: ambos siguen sin ser compatibles con claude-fable-5 y claude-mythos-5.
• Verifica que cualquier código que analice el campo thinking lo trate solo como texto de visualización y devuelva los bloques de pensamiento sin cambios al continuar en el mismo modelo. thinking.display tiene como valor predeterminado "omitted" en claude-fable-5 y claude-mythos-5, igual que en Claude Opus 4.8; configura display: "summarized" para recibir resúmenes legibles. Consulta Salida de pensamiento en Claude Fable 5 y Claude Mythos 5.
• Si reproduces el historial de conversación en otro modelo, primero elimina los bloques thinking y redacted_thinking de los turnos anteriores del asistente. Los bloques de pensamiento de claude-fable-5 y claude-mythos-5 están vinculados al modelo que los produjo, y los modelos distintos de Claude Fable 5 y Claude Mythos 5 los ignoran silenciosamente. Eliminarlos mantiene las solicitudes entre modelos mínimas y uniformes. La excepción es canjear un crédito de fallback, que requiere que el cuerpo de la solicitud se replique bajo las reglas exactas de esa funcionalidad.
• Si migras a Claude Fable 5, maneja stop_reason: "refusal" y lee el campo stop_details.category. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro opcional fallbacks (beta). Consulta Rechazos y fallback.
• Reevalúa tu configuración de effort. Comienza con high para la mayoría de las tareas, incluidas las cargas de trabajo que se ejecutaban con xhigh en Claude Opus 4.8.
• Vuelve a establecer una línea base de costo y latencia en tus propias cargas de trabajo. Los conteos de tokens son aproximadamente los mismos al migrar desde claude-opus-4-8; el precio por token difiere.



Migrar a Claude Opus 5

Claude Opus 5 es una mejora sustancial sobre Claude Opus 4.8, fuerte en razonamiento profundo, tareas agénticas y de largo horizonte, y escalado de cómputo en tiempo de prueba. Para diferencias de comportamiento y patrones de prompting específicos del modelo, consulta Prompting para Claude Opus 5.

Claude Opus 5 es una actualización directa para Claude Opus 4.8 con el mismo precio de $5 por millón de tokens de entrada y $25 por millón de tokens de salida; consulta los precios de Claude. Hay dos cambios con ruptura de compatibilidad para el código que ya se ejecuta en Claude Opus 4.8, cubiertos en Cambios con ruptura de compatibilidad a continuación. Claude Opus 5 admite el mismo conjunto de funcionalidades que Claude Opus 4.8, incluida la ventana de contexto de 1M de tokens (el valor predeterminado, sin encabezado beta), máximo de 128k tokens de salida, pensamiento adaptativo, almacenamiento en caché de prompts, procesamiento por lotes, la Files API, soporte de PDF, visión, y herramientas del lado del servidor y del lado del cliente, con dos excepciones: web fetch no está disponible en Claude Opus 5, y Priority Tier no es compatible con Claude Opus 5. Consulta la página de cada herramienta para la disponibilidad por modelo.



Migrar a Claude Opus 5 desde Claude Opus 4.8



Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-8"  # Before
model = "claude-opus-5"  # After

claude-opus-5 es un ID de modelo fijo sin sufijo de fecha, el mismo esquema que claude-opus-4-8 y claude-sonnet-5.



Cambios con ruptura de compatibilidad

1. Pensamiento activado de forma predeterminada: En Claude Opus 4.8, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Opus 5, las mismas solicitudes se ejecutan con pensamiento adaptativo. max_tokens sigue siendo un límite estricto sobre la salida total, pensamiento más texto de respuesta, así que revísalo para las cargas de trabajo que se ejecutaban sin pensamiento en Claude Opus 4.8. Para preservar el comportamiento anterior, pasa thinking: {type: "disabled"}, sujeto al límite de effort del siguiente elemento; ten en cuenta que con el pensamiento deshabilitado el modelo puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible, así que prefiere niveles de effort más bajos con el pensamiento habilitado donde puedas, y consulta Ejecutar con el pensamiento deshabilitado para mitigaciones donde no puedas.

2. Deshabilitar el pensamiento está limitado a effort high: Aún puedes desactivar el pensamiento con thinking: {type: "disabled"}, pero solo en un nivel de effort de high o inferior. Una solicitud que combina thinking: {type: "disabled"} con effort xhigh o max devuelve un error 400. Claude Opus 4.8 acepta esta combinación, así que audita las solicitudes que deshabilitan el pensamiento antes de migrar.

   La verificación se aplica en cada solicitud: la configuración de effort y de pensamiento de cada solicitud se valida de forma independiente, por lo que una solicitud que eleva el effort a xhigh o max mientras el pensamiento está deshabilitado se rechaza incluso si las solicitudes anteriores en la conversación fueron aceptadas.

   Antes (aceptado en Claude Opus 4.8, rechazado en Claude Opus 5):

   client.messages.create(
       model="claude-opus-4-8",
       max_tokens=16000,
       thinking={"type": "disabled"},
       output_config={"effort": "xhigh"},
       messages=[{"role": "user", "content": "..."}],
   )

   

   Después (Claude Opus 5), elimina el campo thinking para volver a habilitar el pensamiento:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   o mantén el pensamiento deshabilitado y reduce el effort:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       thinking={"type": "disabled"},
       output_config={"effort": "high"},  # or "medium", "low"
       messages=[{"role": "user", "content": "..."}],
   )

   



Cambios recomendados

Estos no son obligatorios pero mejorarán tu experiencia:

1. Prueba el effort max para trabajo crítico en capacidad: Claude Opus 5 admite el conjunto completo de niveles de effort (low, medium, high, xhigh, max). Donde la capacidad máxima importa más que el gasto de tokens, prueba el effort max. Puede ofrecer mejoras en las tareas más exigentes, pero puede mostrar rendimientos decrecientes por el mayor uso de tokens y puede ser propenso a pensar en exceso en las más simples. Si ejecutas con effort xhigh o max, establece un max_tokens grande para que el modelo tenga espacio para pensar y actuar; comienza con 64k tokens y ajusta desde ahí.

2. Considera los fallbacks automáticos: Claude Opus 5 se entrega con clasificadores de seguridad de ciberseguridad cuyos rechazos de categoría cyber pueden recurrir a Claude Opus 4.8. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro fallbacks con el modo "default" (fallbacks: "default"), que selecciona un modelo de fallback recomendado según la categoría de rechazo en lugar de una lista de modelos mantenida manualmente. El fallback del lado del servidor está en beta; el modo "default" requiere el encabezado beta server-side-fallback-2026-07-01. Consulta Rechazos y fallback.

3. Almacena en caché prompts más cortos: La longitud mínima de prompt almacenable en caché en Claude Opus 5 es de 512 tokens, reducida desde 1,024 tokens en Claude Opus 4.8. Los prompts que eran demasiado cortos para almacenarse en caché en Claude Opus 4.8 ahora pueden crear entradas de caché, sin necesidad de cambios en el código. Consulta Almacenamiento en caché de prompts para los mínimos por modelo.

4. Cambia herramientas a mitad de conversación (beta): Puedes agregar o eliminar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Envía el encabezado beta mid-conversation-tool-changes-2026-07-01. Esto es útil para cargas de trabajo agénticas que exponen herramientas progresivamente o las retiran a medida que avanza una tarea; sin él, una lista de herramientas modificada invalida el prefijo almacenado en caché.

5. Reajusta los prompts de longitud y verbosidad: Las respuestas visibles predeterminadas y los entregables escritos son más largos en Claude Opus 5 que en Claude Opus 4.8, y reducir el effort disminuye el volumen de pensamiento sin acortar de manera confiable la respuesta visible. En su lugar, indica explícitamente concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad y Longitud de entregables escritos.

6. Elimina las instrucciones de verificación heredadas y restringe el alcance: Claude Opus 5 verifica su propio trabajo sin que se le indique, así que elimina las instrucciones explícitas de verificación o autocomprobación heredadas de prompts ajustados para modelos anteriores; dejarlas causa sobreverificación. Para tareas acotadas, restringe el alcance de la tarea explícitamente. En frameworks multiagente, proporciona orientación explícita sobre qué escenarios justifican la delegación o limita el número de subagentes, porque Claude Opus 5 delega con más facilidad que los modelos anteriores. Consulta Alcance de la tarea y sobreverificación y Controlar la generación de subagentes.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-4-8 a claude-opus-5.
• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: se ejecutan con pensamiento en Claude Opus 5. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), o pasa thinking: {type: "disabled"} con effort high o inferior para preservar el comportamiento anterior. Si deshabilitas el pensamiento, revisa Ejecutar con el pensamiento deshabilitado para los artefactos de salida que pueden aparecer y sus mitigaciones mediante prompting.
• Audita las solicitudes que deshabilitan el pensamiento: thinking: {type: "disabled"} con effort xhigh o max devuelve un error 400, aplicado en cada solicitud. Vuelve a habilitar el pensamiento o reduce el effort a high o inferior.
• Reevalúa tu configuración de effort: ejecuta un barrido nuevo de effort en tus propias evaluaciones en lugar de heredar una configuración ajustada para un modelo anterior. Vale la pena probar los efforts low y medium como controles de costo y latencia, y prueba el effort max donde la capacidad máxima importa más que el gasto de tokens. Si ejecutas con effort xhigh o max, aumenta max_tokens a al menos 64k como punto de partida.
• Revisa los prompts cercanos al mínimo de almacenamiento en caché: los prompts de 512 tokens o más ahora pueden crear entradas de caché, reducido desde 1,024 tokens en Claude Opus 4.8.
• Maneja stop_reason: "refusal", y considera fallbacks: "default" (beta) para volver a ejecutar automáticamente las solicitudes rechazadas en un modelo de fallback recomendado.
• Si tu organización tiene un compromiso de Priority Tier, planifica la capacidad por separado: Priority Tier no es compatible con Claude Opus 5, mientras que Claude Opus 4.8 lo mantiene.
• Para cargas de trabajo agénticas, considera los presupuestos de tareas (beta) y los cambios de herramientas a mitad de conversación (beta).
• Reajusta los prompts de longitud y verbosidad: las respuestas visibles predeterminadas y los entregables escritos son más largos en Claude Opus 5, y reducir el effort disminuye el volumen de pensamiento sin acortar de manera confiable la respuesta visible. Indica explícitamente concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad y Longitud de entregables escritos.
• Elimina las instrucciones de verificación y autocomprobación heredadas de prompts ajustados para modelos anteriores (causan sobreverificación en Claude Opus 5), restringe el alcance de la tarea explícitamente para tareas acotadas, y en frameworks multiagente dirige o limita la delegación a subagentes. Consulta Alcance de la tarea y sobreverificación y Controlar la generación de subagentes.
• Vuelve a establecer una línea base de costo y latencia en tus propias cargas de trabajo.



Migración a Claude Opus 5 desde Claude Opus 4.7

Claude Opus 5 debería tener un rendimiento sólido desde el primer momento con los prompts y evaluaciones existentes de Claude Opus 4.7, con el mismo precio de $5 por millón de tokens de entrada y $25 por millón de tokens de salida. Admite el mismo conjunto de funciones que Claude Opus 4.7, incluyendo la ventana de contexto de 1M de tokens, 128k tokens máximos de salida, pensamiento adaptativo, almacenamiento en caché de prompts, procesamiento por lotes, la Files API, soporte de PDF, visión, y herramientas del lado del servidor y del lado del cliente, con dos excepciones: web fetch no está disponible en Claude Opus 5, y Priority Tier no es compatible con Claude Opus 5. También agrega mensajes del sistema a mitad de conversación y documenta públicamente los detalles de detención por rechazo.



Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-7"  # Before
model = "claude-opus-5"  # After



Cambios incompatibles

1. Pensamiento activado por defecto: En Claude Opus 4.7, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Opus 5, las mismas solicitudes se ejecutan con pensamiento adaptativo. max_tokens sigue siendo un límite estricto sobre la salida total, pensamiento más texto de respuesta, así que revísalo para las cargas de trabajo que se ejecutaban sin pensamiento en Claude Opus 4.7. Para preservar el comportamiento anterior, pasa thinking: {type: "disabled"}, sujeto al límite de esfuerzo del siguiente punto; ten en cuenta que con el pensamiento deshabilitado el modelo puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible, así que prefiere niveles de esfuerzo más bajos con el pensamiento habilitado donde puedas, y consulta Ejecución con el pensamiento deshabilitado para mitigaciones donde no puedas.

2. Deshabilitar el pensamiento está limitado al esfuerzo high: Puedes desactivar el pensamiento con thinking: {type: "disabled"}, pero solo con un nivel de esfuerzo de high o inferior. Una solicitud que combina thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400. Claude Opus 4.7 acepta esta combinación, así que audita las solicitudes que deshabilitan el pensamiento antes de migrar.

   La verificación se aplica en cada solicitud: la configuración de esfuerzo y pensamiento de cada solicitud se valida de forma independiente, por lo que una solicitud que eleva el esfuerzo a xhigh o max mientras el pensamiento está deshabilitado se rechaza incluso si las solicitudes anteriores de la conversación fueron aceptadas.

   Antes (aceptado en Claude Opus 4.7, rechazado en Claude Opus 5):

   client.messages.create(
       model="claude-opus-4-7",
       max_tokens=16000,
       thinking={"type": "disabled"},
       output_config={"effort": "xhigh"},
       messages=[{"role": "user", "content": "..."}],
   )

   

   Después (Claude Opus 5), elimina el campo thinking para ejecutar con pensamiento:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       output_config={"effort": "xhigh"},  # thinking is on by default
       messages=[{"role": "user", "content": "..."}],
   )

   

   o mantén el pensamiento deshabilitado y reduce el esfuerzo:

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       thinking={"type": "disabled"},
       output_config={"effort": "high"},  # or "medium", "low"
       messages=[{"role": "user", "content": "..."}],
   )

   



Qué cambió

Los siguientes elementos no son cambios incompatibles; describen diferencias de comportamiento que vale la pena verificar después de cambiar el ID del modelo.

1. Parámetros de muestreo (sin cambios): Establecer temperature, top_p o top_k en un valor no predeterminado devuelve un error 400 en Claude Opus 5, igual que en Claude Opus 4.7. Los tipos de solicitud del SDK todavía definen estos campos por compatibilidad con modelos anteriores, por lo que el código que los establece pasa la verificación de tipos, pero la API rechaza la solicitud del lado del servidor. Si eliminaste estos parámetros al migrar a Opus 4.7, no se necesitan más cambios.

2. El esfuerzo predeterminado es high: El valor predeterminado del parámetro de esfuerzo en Claude Opus 5 es high en la Claude API y Claude Code. Si ya estableces el esfuerzo explícitamente, tu configuración no cambia.

3. Niveles de esfuerzo recalibrados: La asignación de tokens detrás de cada nivel de esfuerzo cambia en Claude Opus 5 en comparación con Claude Opus 4.7, y Claude Opus 5 admite el conjunto completo de niveles de esfuerzo (low, medium, high, xhigh, max). Ejecuta un barrido de esfuerzo nuevo en tus propias evaluaciones en lugar de trasladar una configuración ajustada para Claude Opus 4.7. Vale la pena probar los esfuerzos low y medium como controles de costo y latencia, y prueba el esfuerzo max donde la capacidad máxima importa más que el gasto de tokens. Si ejecutas con esfuerzo xhigh o max, establece un max_tokens grande para que el modelo tenga espacio para pensar y actuar; comienza con 64k tokens y ajusta desde ahí. Consulta Esfuerzo.

4. La ventana de contexto de 1M es la predeterminada: Claude Opus 5 ofrece la ventana de contexto completa de 1M de tokens de forma predeterminada sin encabezado beta y sin recargo por contexto largo. Si tu cliente pasa un encabezado beta de ventana de contexto por compatibilidad con modelos más antiguos, puedes eliminarlo en Claude Opus 5.

5. Mensajes del sistema a mitad de conversación: Claude Opus 5 acepta mensajes role: "system" inmediatamente después de un turno de usuario en el arreglo messages (sujeto a las reglas de ubicación). Usa el campo system de nivel superior para instrucciones que se aplican desde el inicio. Claude Opus 4.7 rechaza role: "system" en messages con un error 400. Si mantienes rutas de código que reconstruyen el historial completo de mensajes para actualizar instrucciones, puedes simplificarlas y preservar los aciertos de la caché de prompts en turnos anteriores.

6. Detalles de detención por rechazo: El objeto stop_details en las respuestas de rechazo (disponible desde Claude Opus 4.7) ahora está documentado públicamente. Cuando el modelo rechaza una solicitud, identifica la categoría del rechazo, además de la razón de detención refusal existente. No se requiere encabezado beta y no hay opción de exclusión. Consulta Manejo de razones de detención.

7. Mínimo más bajo para el almacenamiento en caché de prompts: La longitud mínima de prompt almacenable en caché en Claude Opus 5 es de 512 tokens, menor que en Claude Opus 4.7. Los prompts que eran demasiado cortos para almacenarse en caché en Claude Opus 4.7 ahora pueden crear entradas de caché, sin necesidad de cambios en el código. Consulta Almacenamiento en caché de prompts para los mínimos por modelo.



Cambios recomendados

Estos no son obligatorios pero mejorarán tu experiencia:

1. Considera los fallbacks automáticos: Claude Opus 5 se entrega con clasificadores de seguridad de ciberseguridad cuyos rechazos de categoría cibernética pueden recurrir a Claude Opus 4.8. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro fallbacks con el modo "default" (fallbacks: "default"), que selecciona un modelo de respaldo recomendado según la categoría del rechazo en lugar de una lista de modelos mantenida manualmente. El fallback del lado del servidor está en beta; el modo "default" requiere el encabezado beta server-side-fallback-2026-07-01. Consulta Rechazos y fallback.

2. Cambia herramientas a mitad de conversación (beta): Puedes agregar o eliminar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Envía el encabezado beta mid-conversation-tool-changes-2026-07-01. Esto es útil para cargas de trabajo agénticas que exponen herramientas progresivamente o las retiran a medida que avanza una tarea; sin esto, una lista de herramientas modificada invalida el prefijo almacenado en caché.

3. Reajusta los prompts de longitud y verbosidad: Las respuestas visibles predeterminadas y los entregables escritos son más largos en Claude Opus 5 que en modelos Opus anteriores, y reducir el esfuerzo disminuye el volumen de pensamiento sin acortar de manera confiable la respuesta visible. En su lugar, indica explícitamente en el prompt la concisión o una longitud objetivo. Consulta Longitud y verbosidad de la respuesta y Longitud de los entregables escritos.

4. Elimina las instrucciones de verificación heredadas y restringe el alcance: Claude Opus 5 verifica su propio trabajo sin que se le indique, así que elimina las instrucciones explícitas de verificación o autocomprobación heredadas de prompts ajustados para modelos anteriores; dejarlas causa una verificación excesiva. Para tareas acotadas, restringe el alcance de la tarea explícitamente. En frameworks multiagente, proporciona orientación explícita sobre qué escenarios justifican la delegación o limita el número de subagentes, porque Claude Opus 5 delega con más facilidad que los modelos anteriores. Consulta Alcance de la tarea y verificación excesiva y Control de la generación de subagentes.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-4-7 a claude-opus-5 (o actualiza los alias).
• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: se ejecutan con pensamiento en Claude Opus 5. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), o pasa thinking: {type: "disabled"} con esfuerzo high o inferior para preservar el comportamiento anterior. Si deshabilitas el pensamiento, revisa Ejecución con el pensamiento deshabilitado para conocer los artefactos de salida que pueden aparecer y sus mitigaciones mediante prompts.
• Audita las solicitudes que deshabilitan el pensamiento: thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400, aplicado en cada solicitud. Vuelve a habilitar el pensamiento o reduce el esfuerzo a high o inferior.
• Si eliminaste los parámetros de muestreo durante la migración a Opus 4.7, no se necesita ninguna acción. Si los volviste a agregar con una ruta de reintento ante errores 400, elimina esa ruta de reintento.
• Reevalúa tu configuración de effort: ejecuta un barrido de esfuerzo nuevo en tus propias evaluaciones en lugar de trasladar una configuración ajustada para Claude Opus 4.7. Prueba los esfuerzos low y medium como controles de costo y latencia, y el esfuerzo max donde la capacidad máxima importa más que el gasto de tokens. Si ejecutas con esfuerzo xhigh o max, aumenta max_tokens a al menos 64k como punto de partida.
• Elimina cualquier encabezado beta de ventana de contexto. La ventana de contexto de 1M es la predeterminada en la Claude API, Amazon Bedrock, Google Cloud y Microsoft Foundry.
• Si reconstruyes el historial de conversación para actualizar instrucciones, considera cambiar a un mensaje del sistema a mitad de conversación para preservar los aciertos de la caché de prompts.
• Verifica que tu manejo de razones de detención lea stop_details en los rechazos (disponible desde Claude Opus 4.7; ahora documentado públicamente), y considera fallbacks: "default" (beta) para volver a ejecutar automáticamente las solicitudes rechazadas en un modelo de respaldo recomendado.
• Revisa los prompts cercanos al mínimo de almacenamiento en caché: los prompts de 512 tokens o más ahora pueden crear entradas de caché.
• Si usas web fetch, planifica una alternativa: no está disponible en Claude Opus 5.
• Si tu organización tiene un compromiso de Priority Tier, ten en cuenta que Priority Tier no es compatible con Claude Opus 5.
• Para cargas de trabajo agénticas, considera los presupuestos de tareas (beta) y los cambios de herramientas a mitad de conversación (beta).
• Reajusta los prompts de longitud y verbosidad, y elimina las instrucciones de verificación y autocomprobación heredadas de prompts ajustados para modelos anteriores.
• Vuelve a establecer la línea base de costo y latencia en el nivel de esfuerzo que elijas.



Migración a Claude Opus 5 desde Claude Opus 4.6 y modelos Opus anteriores

Claude Opus 5 debería tener un rendimiento sólido desde el primer momento con los prompts y evaluaciones existentes de Claude Opus 4.6 al mismo precio, pero hay un puñado de cambios de comportamiento y de API que vale la pena conocer al migrar. La mayoría de estos cambios entraron en vigor en Claude Opus 4.7; dos más, el pensamiento activado por defecto y un límite de esfuerzo al desactivar el pensamiento, entran en vigor en Claude Opus 5. Todos ellos se cubren a continuación, por lo que esta sección está completa para código que proviene directamente de Claude Opus 4.6. Claude Opus 5 admite el mismo conjunto de funciones que Claude Opus 4.6, incluyendo:

• Ventana de contexto de 1M de tokens al precio estándar de la API sin recargo por contexto largo
• 128k tokens máximos de salida
• Pensamiento adaptativo
• Almacenamiento en caché de prompts
• Procesamiento por lotes
• API de Files
• Soporte de PDF
• Visión
• Herramientas del lado del servidor y del lado del cliente (bash, ejecución de código, uso de computadora, editor de texto, búsqueda web, conector MCP, memoria)

Dos excepciones: web fetch no está disponible en Claude Opus 5, y Priority Tier no es compatible con Claude Opus 5.



Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-6"  # Before
model = "claude-opus-5"  # After



Cambios incompatibles

1. Pensamiento extendido eliminado: thinking: {type: "enabled", budget_tokens: N} ya no es compatible con Claude Opus 4.7 ni con modelos posteriores y devuelve un error 400. Cambia al pensamiento adaptativo (thinking: {type: "adaptive"}) y usa el parámetro effort para controlar la profundidad del pensamiento. En Claude Opus 5, el pensamiento adaptativo está activado por defecto: thinking: {type: "adaptive"} es válido y equivalente a omitir el campo thinking por completo (consulta el siguiente punto).

   Antes (Claude Opus 4.6):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-opus-4-6",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 10000},
       messages=[{"role": "user", "content": "..."}],
   )

   Después (Claude Opus 5):

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client.messages.create(
       model="claude-opus-5",
       max_tokens=16000,
       thinking={"type": "adaptive"},
       output_config={"effort": "high"},  # or "max", "xhigh", "medium", "low"
       messages=[{"role": "user", "content": "..."}],
   )

   El pensamiento adaptativo se puede dirigir mediante prompting y el parámetro effort; consulta Elegir un nivel de esfuerzo.

2. Pensamiento activado por defecto: En Claude Opus 4.6 y Claude Opus 4.7, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Opus 5, las mismas solicitudes se ejecutan con pensamiento adaptativo. max_tokens sigue siendo un límite estricto sobre la salida total, pensamiento más texto de respuesta, así que revísalo para las cargas de trabajo que se ejecutaban sin pensamiento. Para preservar el comportamiento anterior, pasa thinking: {type: "disabled"}, sujeto al límite de esfuerzo del siguiente punto; ten en cuenta que con el pensamiento desactivado el modelo puede ocasionalmente emitir llamadas a herramientas como texto plano o incluir etiquetas XML internas en su salida visible, así que prefiere niveles de esfuerzo más bajos con el pensamiento habilitado cuando puedas, y consulta Ejecución con el pensamiento desactivado para mitigaciones cuando no puedas.

3. Desactivar el pensamiento está limitado al esfuerzo high: Puedes desactivar el pensamiento con thinking: {type: "disabled"}, pero solo con un nivel de effort de high o inferior. Una solicitud que combine thinking: {type: "disabled"} con effort xhigh o max devuelve un error 400 en Claude Opus 5, aplicado en cada solicitud. Audita las solicitudes que desactivan el pensamiento antes de migrar: vuelve a habilitar el pensamiento o reduce el esfuerzo a high o inferior.

4. Parámetros de muestreo eliminados: Establecer temperature, top_p o top_k en cualquier valor no predeterminado en Claude Opus 4.7 o modelos posteriores, incluido Claude Opus 5, devuelve un error 400. La ruta de migración más segura es omitir estos parámetros por completo de las cargas útiles de las solicitudes. El prompting es la forma recomendada de guiar el comportamiento del modelo en Claude Opus 5. Si estabas usando temperature = 0 para obtener determinismo, ten en cuenta que nunca garantizó salidas idénticas en modelos anteriores.

5. Contenido de pensamiento omitido por defecto: Los bloques de pensamiento siguen apareciendo en el flujo de respuesta en Claude Opus 4.7 y modelos posteriores, pero su campo thinking está vacío a menos que optes explícitamente por incluirlo. Este es un cambio silencioso respecto a Claude Opus 4.6, donde el valor predeterminado era devolver texto de pensamiento resumido. Para restaurar el contenido de pensamiento resumido, establece thinking.display en "summarized":

   PythonTypeScriptC#GoJavaPHPRuby

   

   thinking = {
       "type": "adaptive",
       "display": "summarized",
   }

   El valor predeterminado es "omitted" en Claude Opus 4.7 y modelos posteriores. Si tu producto transmite el razonamiento a los usuarios mediante streaming, el nuevo valor predeterminado aparece como una pausa larga antes de que comience la salida; establece display: "summarized" para restaurar el progreso visible durante el pensamiento. Consulta Controlar la visualización del pensamiento para más detalles.

6. Conteo de tokens actualizado: Claude Opus 4.7 introdujo un nuevo tokenizador, que los modelos Opus posteriores, incluido Claude Opus 5, también usan. Contribuye a un mejor rendimiento en una amplia gama de tareas, y puede usar aproximadamente de 1x a 1.35x más tokens al procesar texto en comparación con los modelos anteriores a Claude Opus 4.7 (hasta ~35% más, variando según el contenido).

   /v1/messages/count_tokens devuelve un número diferente de tokens para Claude Opus 5 que el que devolvía para Claude Opus 4.6. La eficiencia de tokens puede variar según la forma de la carga de trabajo.

   Las intervenciones de prompting, task_budget y effort pueden ayudar a controlar los costos y garantizar un uso apropiado de tokens. Estos controles pueden sacrificar inteligencia del modelo. Actualiza tus parámetros max_tokens para dar margen adicional, incluidos los disparadores de compactación. Claude Opus 5 proporciona una ventana de contexto de 1M al precio estándar de la API sin recargo por contexto largo.

7. Eliminación del prefill (heredado de Opus 4.6): Prellenar mensajes del asistente devuelve un error 400 en Claude Opus 4.7 y modelos posteriores, incluido Claude Opus 5. Usa salidas estructuradas, instrucciones en la indicación del sistema, o output_config.format en su lugar.



Elegir un nivel de esfuerzo

El parámetro effort te permite ajustar la inteligencia de Claude frente al gasto de tokens, sacrificando capacidad a cambio de mayor velocidad y menores costos. Claude Opus 5 admite el conjunto completo de niveles de esfuerzo y su valor predeterminado es high. Ejecuta un nuevo barrido de esfuerzo en tus propias evaluaciones en lugar de arrastrar una configuración ajustada para un modelo anterior:

• max: Puede ofrecer mejoras en las tareas más exigentes, pero puede mostrar rendimientos decrecientes por el mayor uso de tokens y puede ser propenso a pensar en exceso en las más simples. Pruébalo donde la capacidad máxima importe más que el gasto de tokens.
• xhigh: Capacidad extendida para trabajo agéntico y de codificación de larga duración que necesita más profundidad que el valor predeterminado.
• high: El valor predeterminado. Equilibra el uso de tokens y la inteligencia para la mayoría de las tareas.
• medium: Reducción de costos respecto al valor predeterminado, vale la pena probarlo como control de costos y latencia.
• low: El más eficiente. Resérvalo para tareas cortas y acotadas y cargas de trabajo sensibles a la latencia.

Si ejecutas con esfuerzo xhigh o max, establece un max_tokens grande para que el modelo tenga espacio para pensar y actuar; comienza con 64k tokens y ajusta a partir de ahí. El esfuerzo es más importante para este modelo que para cualquier Opus anterior. Experimenta con él activamente cuando actualices.



Cambios de comportamiento

Claude Opus 4.7 introdujo varias diferencias de comportamiento respecto a Claude Opus 4.6 que no son cambios incompatibles de la API pero que pueden requerir actualizaciones de prompts o la eliminación de andamiaje. Se mantienen en Claude Opus 5, con los ajustes indicados a continuación.

1. La longitud de la respuesta varía según el caso de uso: Claude Opus 4.7 calibra la longitud de la respuesta según la complejidad que juzga que tiene la tarea, en lugar de usar una verbosidad fija por defecto. Esto generalmente significa respuestas más cortas en consultas simples y mucho más largas en análisis abiertos.

   Si tu producto depende de un cierto estilo o verbosidad de salida, es posible que necesites ajustar tus prompts. Por ejemplo, para disminuir la verbosidad, agrega: "Proporciona respuestas concisas y enfocadas. Omite el contexto no esencial y mantén los ejemplos al mínimo." Si observas tipos específicos de sobreexplicación, agrega instrucciones específicas en tu prompt para prevenirlos.

   Los ejemplos positivos que muestran cómo Claude puede comunicarse con el nivel apropiado de concisión tienden a ser más efectivos que los ejemplos negativos o las instrucciones que le dicen al modelo lo que no debe hacer. En Claude Opus 5, las respuestas visibles predeterminadas y los entregables escritos son más largos que en los modelos Opus anteriores, y reducir el esfuerzo disminuye el volumen de pensamiento sin acortar de manera confiable la respuesta visible; indica explícitamente en el prompt la concisión o una longitud objetivo. Consulta Longitud de respuesta y verbosidad.

2. Seguimiento de instrucciones más literal: Claude Opus 4.7 interpreta los prompts de manera más literal y explícita que Claude Opus 4.6, particularmente en niveles de esfuerzo más bajos. No generaliza silenciosamente una instrucción de un elemento a otro, y no infiere solicitudes que no hiciste. La ventaja de este literalismo es la precisión y menos vaivenes. Generalmente funciona mejor para casos de uso de API con prompts cuidadosamente ajustados, extracción estructurada y pipelines donde deseas un comportamiento predecible. Una revisión del prompt y del arnés puede ser especialmente útil para la migración a Claude Opus 5.

3. Tono más directo: Como con cualquier modelo nuevo, el estilo de prosa en la escritura de formato largo puede cambiar. Claude Opus 4.7 es más directo y con más criterio propio, con menos frases orientadas a la validación y menos emojis que el estilo más cálido de Claude Opus 4.6. Si tu producto depende de una voz específica, reevalúa los prompts de estilo frente a la nueva línea base.

4. Actualizaciones de progreso integradas en trazas agénticas: Claude Opus 4.7 proporciona actualizaciones más regulares y de mayor calidad al usuario a lo largo de trazas agénticas largas. Si has agregado andamiaje para forzar mensajes de estado intermedios ("Después de cada 3 llamadas a herramientas, resume el progreso"), intenta eliminarlo. Si encuentras que la longitud o el contenido de las actualizaciones de cara al usuario de Claude Opus 4.7 no están bien calibrados para tu caso de uso, describe explícitamente cómo deberían verse estas actualizaciones en el prompt y proporciona ejemplos.

5. Cambio en la generación de subagentes: Claude Opus 4.7 tiende a generar menos subagentes por defecto que Claude Opus 4.6, mientras que Claude Opus 5 delega a subagentes con más facilidad que los modelos anteriores. El comportamiento se puede dirigir mediante prompting en cualquier dirección; proporciona orientación explícita sobre cuándo son deseables los subagentes, o limita el número de subagentes. Consulta Controlar la generación de subagentes.

6. Calibración de esfuerzo más estricta: Cambiando significativamente respecto a Claude Opus 4.6, Claude Opus 4.7 respeta los niveles de esfuerzo estrictamente, especialmente en el extremo bajo. En low y medium, el modelo acota su trabajo a lo que se le pidió en lugar de hacer más de lo solicitado.

   Esto es bueno para la latencia y el costo, pero en tareas moderadamente complejas ejecutadas con esfuerzo low existe cierto riesgo de pensar de menos. Si observas razonamiento superficial en problemas complejos, aumenta el esfuerzo a high o xhigh en lugar de intentar resolverlo con prompting.

   Si necesitas mantener el esfuerzo en low por latencia, agrega orientación específica: "Esta tarea implica razonamiento de múltiples pasos. Piensa cuidadosamente el problema antes de responder." Consulta Niveles de esfuerzo recomendados para Claude Opus 4.7.

7. Menos llamadas a herramientas por defecto: Claude Opus 4.7 tiene una tendencia a usar herramientas con menos frecuencia que Claude Opus 4.6 y a usar más el razonamiento. Esto produce mejores resultados en la mayoría de los casos.

   Para aumentar el uso de herramientas, eleva la configuración de esfuerzo. Las configuraciones de esfuerzo high o xhigh muestran un uso de herramientas sustancialmente mayor en búsqueda agéntica y codificación. También puedes ajustar tu prompt para instruir explícitamente al modelo sobre cuándo y cómo usar correctamente sus herramientas.

8. Salvaguardas de ciberseguridad en tiempo real: Recién agregadas en Claude Opus 4.7, las solicitudes que involucran temas prohibidos o de alto riesgo pueden dar lugar a rechazos. Para trabajo de seguridad legítimo como pruebas de penetración, investigación de vulnerabilidades o red-teaming, solicita acceso al Cyber Verification Program para pedir restricciones reducidas. Consulta Salvaguardas, advertencias y apelaciones para obtener contexto.

9. Soporte de imágenes de alta resolución: Claude Opus 4.7 es el primer modelo de Claude con soporte de imágenes de alta resolución. La resolución máxima de imagen es de 2,576 píxeles en el lado largo, frente a los 1,568 píxeles de los modelos anteriores. Esto desbloquea mejoras en cargas de trabajo intensivas en visión y es particularmente valioso para el uso de computadora, la comprensión de capturas de pantalla y el análisis de documentos.

   El soporte de alta resolución es automático y no requiere encabezado beta ni activación del lado del cliente. Dos cosas a tener en cuenta:

   • Las imágenes a resolución completa pueden usar hasta aproximadamente 3x más tokens de imagen que en modelos anteriores (hasta 4,784 tokens por imagen, en comparación con el límite anterior de aproximadamente 1,600 tokens por imagen). Vuelve a presupuestar max_tokens y las expectativas de costo para cargas de trabajo intensivas en imágenes, o reduce la resolución antes de enviar si no necesitas la fidelidad adicional.
   • Las coordenadas de señalamiento y de cuadros delimitadores devueltas por el modelo son 1:1 con los píxeles reales de la imagen en Claude Opus 4.7, por lo que no se requiere conversión de factor de escala.

   Consulta Soporte de imágenes de alta resolución en Claude Opus 4.7 para más detalles.



Cambios recomendados

Estos no son obligatorios pero mejorarán tu experiencia:

1. Reevalúa max_tokens: Debido a que el mismo texto produce un conteo de tokens más alto en Claude Opus 4.7 y modelos posteriores, actualiza tus parámetros max_tokens para dar margen adicional, incluidos los disparadores de compactación. Las intervenciones de prompting, task_budget y effort pueden ayudar a controlar los costos y garantizar un uso apropiado de tokens.

2. Audita las expectativas de conteo de tokens: Cualquier ruta de código que estime tokens del lado del cliente o asuma una proporción fija de tokens a caracteres debe volver a probarse con Claude Opus 5. Usa el endpoint de conteo de tokens para verificar.

3. Adopta los presupuestos de tarea (beta): Claude Opus 4.7 introduce los presupuestos de tarea. Estos presupuestos te permiten informar a Claude cuántos tokens tiene para un bucle agéntico completo, incluyendo pensamiento, llamadas a herramientas, resultados de herramientas y salida final. El modelo ve una cuenta regresiva en curso y la usa para priorizar el trabajo y terminar la tarea con elegancia a medida que se consume el presupuesto. Para usarlo, establece el encabezado beta task-budgets-2026-03-13 y agrega lo siguiente a tu configuración de salida:

   PythonTypeScriptC#GoJavaPHPRuby

   

   output_config = {
       "effort": "high",
       "task_budget": {"type": "tokens", "total": 128000},
   }

   Es posible que necesites experimentar con diferentes presupuestos de tarea para tu caso de uso. Si al modelo se le da un presupuesto de tarea demasiado restrictivo, puede completar la tarea con menos exhaustividad, haciendo referencia a su presupuesto como la restricción.

   Para tareas agénticas abiertas donde la calidad importa más que la velocidad, no establezcas un presupuesto de tarea. Reserva los presupuestos de tarea para cargas de trabajo donde necesites que el modelo acote su trabajo a una asignación de tokens. El valor mínimo para un presupuesto de tarea es de 20k tokens.

   Un presupuesto de tarea no es un límite estricto; es una sugerencia de la que el modelo es consciente. Difiere de max_tokens:

   • task_budget: un límite orientativo a lo largo de todo el bucle agéntico. El modelo lo ve y lo usa para regular su ritmo.
   • max_tokens: un techo estricto por solicitud sobre los tokens generados. No se pasa al modelo, por lo que el modelo no es consciente de él.

   Usa task_budget cuando quieras que el modelo se autorregule, y max_tokens como un techo estricto para limitar el uso.

4. Establece un max_tokens grande con esfuerzo max o xhigh: Si estás ejecutando Claude Opus 4.7 o un modelo posterior con esfuerzo max o xhigh, establece un presupuesto grande de tokens máximos de salida para que el modelo tenga espacio para pensar y actuar a través de sus subagentes y llamadas a herramientas. Comienza con 64k tokens y ajusta a partir de ahí.

5. Reduce la resolución de las imágenes si la alta resolución es innecesaria: Claude Opus 4.7 y los modelos posteriores admiten imágenes de hasta 2576px / 3.75MP. Las imágenes de alta resolución usan más tokens. Si la fidelidad adicional de la imagen es innecesaria, reduce la resolución de las imágenes antes de enviarlas a Claude para evitar aumentos en el uso de tokens. Consulta Imágenes y visión.

6. Considera los fallbacks automáticos: Claude Opus 5 se entrega con clasificadores de seguridad de ciberseguridad cuyos rechazos de categoría cibernética pueden recurrir a Claude Opus 4.8. Para volver a ejecutar automáticamente las solicitudes rechazadas en otro modelo, considera el parámetro fallbacks con el modo "default" (fallbacks: "default"), que selecciona un modelo de respaldo recomendado según la categoría de rechazo en lugar de una lista de modelos mantenida manualmente. El fallback del lado del servidor está en beta; el modo "default" requiere el encabezado beta server-side-fallback-2026-07-01. Consulta Rechazos y fallback.

7. Almacena en caché prompts más cortos: La longitud mínima de prompt almacenable en caché en Claude Opus 5 es de 512 tokens, menor que en los modelos Opus anteriores. Los prompts que eran demasiado cortos para almacenarse en caché ahora pueden crear entradas de caché, sin necesidad de cambios en el código. Consulta Almacenamiento en caché de prompts para los mínimos por modelo.

8. Cambia herramientas a mitad de conversación (beta): Puedes agregar o eliminar herramientas entre turnos de una conversación sin invalidar los aciertos de la caché de prompts en turnos anteriores. Envía el encabezado beta mid-conversation-tool-changes-2026-07-01. Esto es útil para cargas de trabajo agénticas que exponen herramientas progresivamente o las retiran a medida que avanza una tarea; sin él, una lista de herramientas modificada invalida el prefijo almacenado en caché.

9. Elimina las instrucciones de verificación heredadas y restringe el alcance: Claude Opus 5 verifica su propio trabajo sin que se le indique, así que elimina las instrucciones explícitas de verificación o autocomprobación heredadas de prompts ajustados para modelos anteriores; dejarlas causa sobreverificación. Para tareas acotadas, restringe el alcance de la tarea explícitamente. Consulta Alcance de la tarea y sobreverificación.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-opus-4-6 a claude-opus-5 (o actualiza los alias).
• Elimina temperature, top_p y top_k de las cargas útiles de las solicitudes.
• Reemplaza thinking: {type: "enabled", budget_tokens: N} con thinking: {type: "adaptive"} más el parámetro effort, o elimina el campo thinking por completo; el pensamiento adaptativo está activado por defecto en Claude Opus 5.
• Revisa las cargas de trabajo que se ejecutaban sin un campo thinking: se ejecutan con pensamiento en Claude Opus 5. Revisa max_tokens, que sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), o pasa thinking: {type: "disabled"} con esfuerzo high o inferior para preservar el comportamiento anterior.
• Audita las solicitudes que desactivan el pensamiento: thinking: {type: "disabled"} con esfuerzo xhigh o max devuelve un error 400, aplicado en cada solicitud. Vuelve a habilitar el pensamiento o reduce el esfuerzo a high o inferior.
• Elimina cualquier prefill de mensajes del asistente.
• Si tu interfaz de usuario muestra contenido de pensamiento, opta explícitamente por la sumarización del pensamiento.
• Vuelve a medir el costo y la latencia de extremo a extremo con la tokenización actualizada.
• Vuelve a ajustar max_tokens para tener en cuenta la tokenización actualizada.
• Vuelve a probar cualquier estimación de conteo de tokens del lado del cliente.
• Si tu aplicación envía imágenes, vuelve a presupuestar para el soporte de imágenes de alta resolución (hasta aproximadamente 3x más tokens de imagen por imagen a resolución completa). Reduce la resolución antes de enviar si no necesitas la fidelidad adicional.
• Si consumes coordenadas de señalamiento o de cuadros delimitadores del modelo, elimina cualquier conversión de factor de escala; las coordenadas son 1:1 con los píxeles reales de la imagen en Claude Opus 4.7 y modelos posteriores.
• Revisa los prompts para los cambios de comportamiento (longitud de respuesta, literalismo, tono, actualizaciones de progreso, subagentes, calibración de esfuerzo, activación de herramientas, salvaguardas cibernéticas, manejo de imágenes de alta resolución).
• Vuelve a establecer la línea base de la longitud de respuesta con los prompts de control de longitud existentes eliminados, luego ajusta explícitamente.
• Si usas esfuerzo xhigh o max, eleva max_tokens a al menos 64k como punto de partida.
• Considera adoptar presupuestos de tarea (beta) y cambios de herramientas a mitad de conversación (beta) para flujos de trabajo agénticos.
• Maneja stop_reason: "refusal", y considera fallbacks: "default" (beta) para volver a ejecutar automáticamente las solicitudes rechazadas en un modelo de respaldo recomendado.
• Revisa los prompts cercanos al mínimo de almacenamiento en caché: los prompts de 512 tokens o más ahora pueden crear entradas de caché en Claude Opus 5.
• Si usas web fetch, planifica una alternativa: no está disponible en Claude Opus 5.
• Si tu organización tiene un compromiso de Priority Tier, ten en cuenta que Priority Tier no es compatible con Claude Opus 5.
• Elimina las instrucciones de verificación y autocomprobación heredadas de prompts ajustados para modelos anteriores; causan sobreverificación en Claude Opus 5.
• Si tu producto realiza trabajo de seguridad legítimo, solicita acceso al Cyber Verification Program para obtener restricciones más bajas sobre contenido cibernético.



Migración desde Claude Opus 4.5 o anterior

Si estás migrando desde Claude Opus 4.5, Opus 4.1 (obsoleto) o un modelo anterior directamente a Claude Opus 5, aplica todos los cambios anteriores de esta sección más los cambios acumulativos a continuación, que entraron en vigor entre Opus 4.5 y Opus 4.7. Si estás migrando desde Opus 4.6, los cambios anteriores de esta sección son todo lo que necesitas.

Actualiza el nombre de tu modelo

# Migración a Opus
model = "claude-opus-4-5"  # Before
model = "claude-opus-5"  # After

Cambios incompatibles

1. La eliminación del prefill se cubre en los cambios incompatibles para migrar desde Claude Opus 4.6.

2. Escape de comillas en parámetros de herramientas: Claude Opus 4.6 y los modelos posteriores pueden producir un escape de cadenas JSON ligeramente diferente en los argumentos de las llamadas a herramientas (por ejemplo, un manejo diferente de los escapes Unicode o del escape de barras diagonales). Si analizas el input de las llamadas a herramientas como una cadena sin procesar en lugar de usar un analizador JSON, verifica tu lógica de análisis. Los analizadores JSON estándar (como json.loads() o JSON.parse()) manejan estas diferencias automáticamente.

Cambios recomendados

Estos cambios mejoran tu experiencia en Claude Opus 4.7 y modelos posteriores. Los elementos marcados como (obligatorio en Opus 4.7) eran recomendaciones opcionales cuando se lanzó Opus 4.6 pero ahora son obligatorios; el resto siguen siendo recomendados.

1. Migra al pensamiento adaptativo (obligatorio en Opus 4.7): thinking: {type: "enabled", budget_tokens: N} devuelve un error 400 en Claude Opus 4.7 y modelos posteriores. Cambia a thinking: {type: "adaptive"} y usa el parámetro effort para controlar la profundidad del pensamiento; en Claude Opus 5, thinking: {type: "adaptive"} es equivalente a omitir el campo thinking, que se ejecuta con pensamiento adaptativo por defecto. Consulta Pensamiento.

   cURLBeforeAfterCLITypeScriptC#GoJavaPHPRuby

   

   response = client.beta.messages.create(
       model="claude-opus-4-5",
       max_tokens=16000,
       thinking={"type": "enabled", "budget_tokens": 32000},
       betas=["interleaved-thinking-2025-05-14"],
       messages=[{"role": "user", "content": "Your prompt here"}],
   )

   Ten en cuenta que la migración también pasa de client.beta.messages.create a client.messages.create. El pensamiento adaptativo y effort son funciones en disponibilidad general (GA) y no requieren el espacio de nombres beta del SDK ni ningún encabezado beta.

2. Elimina el encabezado beta de effort: El parámetro effort ahora está en GA. Elimina betas=["effort-2025-11-24"] de tus solicitudes.

3. Elimina el encabezado beta de streaming de herramientas de grano fino: El streaming de herramientas de grano fino ahora está en GA. Elimina betas=["fine-grained-tool-streaming-2025-05-14"] de tus solicitudes.

4. Elimina el encabezado beta de pensamiento intercalado: El pensamiento adaptativo habilita automáticamente el pensamiento intercalado en Claude Opus 4.7, Opus 4.6 y Sonnet 4.6. Elimina betas=["interleaved-thinking-2025-05-14"] de tus solicitudes. El encabezado sigue siendo funcional en Sonnet 4.6 con pensamiento extendido manual, pero el modo manual está obsoleto.

5. Migra a output_config.format: Si usas salidas estructuradas, actualiza output_format={...} a output_config={"format": {...}}. El parámetro antiguo sigue siendo funcional pero está obsoleto y se eliminará en una futura versión del modelo.



Migración desde Claude 4.1 o anterior

Si estás migrando desde Opus 4.1 (obsoleto) o modelos anteriores directamente a Claude Opus 5, aplica todos los cambios anteriores de esta sección, más los cambios adicionales de esta subsección.

# Desde Opus 4.1
model = "claude-opus-4-1-20250805"  # Before
model = "claude-opus-5"  # After

# Desde Sonnet 3.7
model = "claude-3-7-sonnet-20250219"  # Before
model = "claude-opus-5"  # After

Cambios incompatibles adicionales

1. Elimina los parámetros de muestreo

   

   Este es un cambio incompatible al migrar desde modelos Claude 3.x.

   A partir de Claude Opus 4.7, establecer temperature, top_p o top_k en cualquier valor no predeterminado devuelve un error 400. La ruta de migración más segura es omitir estos parámetros por completo de las solicitudes, y usar prompting para guiar el comportamiento del modelo. Si estabas usando temperature = 0 para obtener determinismo, ten en cuenta que nunca garantizó salidas idénticas.

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Antes - Esto generará un error en los modelos Claude 4+
   response = client.messages.create(
       model="claude-3-7-sonnet-20250219",
       temperature=0.7,
       top_p=0.9,  # Non-default sampling params return 400 on Opus 4.7
       # ...
   )
   
   # Después
   response = client.messages.create(
       model="claude-opus-5",
       # ...
   )

2. Actualiza las versiones de las herramientas

   

   Este es un cambio incompatible al migrar desde modelos Claude 3.x.

   Actualiza a las últimas versiones de las herramientas. Elimina cualquier código que use el comando undo_edit.

   PythonTypeScriptC#GoJavaPHPRuby

   

   # Antes
   tools = [{"type": "text_editor_20250124", "name": "str_replace_editor"}]
   
   # Después
   tools = [{"type": "text_editor_20250728", "name": "str_replace_based_edit_tool"}]

   • Editor de texto: Usa text_editor_20250728 y str_replace_based_edit_tool. Consulta la documentación de la herramienta de editor de texto para más detalles.
   • Ejecución de código: Actualiza a code_execution_20260521. Consulta la documentación de la herramienta de ejecución de código para obtener instrucciones de migración.

3. Maneja la razón de detención refusal

   Actualiza tu aplicación para manejar las razones de detención refusal:

   PythonTypeScriptC#GoJavaPHPRuby

   

   response = client.messages.create(...)
   
   if response.stop_reason == "refusal":
       # Maneja el rechazo apropiadamente
       pass

4. Maneja la razón de detención model_context_window_exceeded

   Los modelos Claude 4.5+ devuelven una razón de detención model_context_window_exceeded cuando la generación se detiene por alcanzar el límite de la ventana de contexto, en lugar del límite max_tokens solicitado. Actualiza tu aplicación para manejar esta nueva razón de detención:

   PythonTypeScriptC#GoJavaPHPRuby

   

   response = client.messages.create(...)
   
   if response.stop_reason == "model_context_window_exceeded":
       # Maneja el límite de la ventana de contexto apropiadamente
       pass

5. Verifica el manejo de parámetros de herramientas (saltos de línea finales)

   Los modelos Claude 4.5+ preservan los saltos de línea finales en los parámetros de cadena de las llamadas a herramientas que anteriormente se eliminaban. Si tus herramientas dependen de una coincidencia exacta de cadenas con los parámetros de las llamadas a herramientas, verifica que tu lógica maneje correctamente los saltos de línea finales.

6. Actualiza tus prompts para los cambios de comportamiento

   Los modelos Claude 4+ tienen un estilo de comunicación más conciso y directo y requieren dirección explícita. Revisa las mejores prácticas de prompting para obtener orientación de optimización.

Cambios recomendados adicionales

• Elimina los encabezados beta heredados: Elimina token-efficient-tools-2025-02-19 y output-128k-2025-02-19. Todos los modelos Claude 4+ tienen uso de herramientas eficiente en tokens integrado y estos encabezados no tienen efecto.



Lista de verificación de migración (desde Claude Opus 4.5 o anterior)

• Actualiza el ID del modelo a claude-opus-5
• Aplica todos los cambios incompatibles para migrar desde Claude Opus 4.6 (pensamiento extendido eliminado, pensamiento activado por defecto, límite de esfuerzo al desactivar el pensamiento, parámetros de muestreo eliminados, visualización del pensamiento omitida por defecto, tokenización actualizada)
• INCOMPATIBLE: Elimina los prefills de mensajes del asistente (devuelve un error 400); usa salidas estructuradas o output_config.format en su lugar
• INCOMPATIBLE en Opus 4.7: Reemplaza thinking: {type: "enabled", budget_tokens: N} con thinking: {type: "adaptive"} más el parámetro effort (devuelve 400 en Opus 4.7)
• Verifica que el análisis JSON de las llamadas a herramientas use un analizador JSON estándar
• Elimina el encabezado beta effort-2025-11-24 (effort ahora está en GA)
• Elimina el encabezado beta fine-grained-tool-streaming-2025-05-14
• Elimina el encabezado beta interleaved-thinking-2025-05-14 (el pensamiento adaptativo habilita el pensamiento intercalado automáticamente)
• Migra output_format a output_config.format (si aplica)
• Si migras desde Claude 4.1 o anterior: elimina temperature, top_p y top_k (los valores no predeterminados devuelven 400 en Opus 4.7)
• Si migras desde Claude 4.1 o anterior: actualiza las versiones de las herramientas (text_editor_20250728, code_execution_20260521)
• Si migras desde Claude 4.1 o anterior: maneja la razón de detención refusal
• Si migras desde Claude 4.1 o anterior: maneja la razón de detención model_context_window_exceeded
• Si migras desde Claude 4.1 o anterior: verifica el manejo de parámetros de cadena de herramientas para los saltos de línea finales
• Si migras desde Claude 4.1 o anterior: elimina los encabezados beta heredados (token-efficient-tools-2025-02-19, output-128k-2025-02-19)
• Revisa y actualiza los prompts siguiendo las mejores prácticas de prompting
• Prueba en un entorno de desarrollo antes del despliegue en producción



Migrar a Claude Opus 5 desde Claude Sonnet 5

Claude Opus 5 y Claude Sonnet 5 comparten la misma superficie de API: ambos se ejecutan con pensamiento adaptativo activado de forma predeterminada, ambos tienen el parámetro effort con valor predeterminado high en la API de Claude y Claude Code, ambos ofrecen una ventana de contexto de 1M de tokens de forma predeterminada con 128k tokens máximos de salida, y ninguno admite Priority Tier. El pensamiento extendido manual y los parámetros de muestreo no predeterminados devuelven un error 400 en ambos modelos, al igual que el prellenado del asistente.



Actualiza el nombre de tu modelo

model = "claude-sonnet-5"  # Before
model = "claude-opus-5"  # After



Qué cambió

1. Precios: Claude Opus 5 tiene un precio de $5 por millón de tokens de entrada y $25 por millón de tokens de salida. Para Claude Sonnet 5, el precio introductorio de $2/$10 por millón de tokens de entrada/salida está vigente hasta el 31 de agosto de 2026, después de lo cual entra en vigor el precio estándar de $3/$15. Consulta los precios de Claude para ver los precios completos.

2. Desactivar el pensamiento está limitado a un effort de high: En Claude Sonnet 5, thinking: {type: "disabled"} se acepta en cualquier nivel de effort. En Claude Opus 5, solo se acepta en un nivel de effort de high o inferior; una solicitud que combine thinking: {type: "disabled"} con effort xhigh o max devuelve un error 400, aplicado en cada solicitud. Audita las solicitudes que desactivan el pensamiento antes de migrar.

3. Mensajes del sistema a mitad de conversación: Claude Opus 5 acepta mensajes role: "system" inmediatamente después de un turno del usuario en el arreglo messages (sujeto a las reglas de ubicación); Claude Sonnet 5 no. Si mantienes rutas de código que reconstruyen el historial completo de mensajes para actualizar instrucciones, puedes simplificarlas y preservar los aciertos de la caché de prompts en turnos anteriores.

4. Web fetch no está disponible: La herramienta de web fetch está disponible en Claude Sonnet 5 pero no en Claude Opus 5.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-sonnet-5 a claude-opus-5.
• Audita las solicitudes que desactivan el pensamiento: thinking: {type: "disabled"} con effort xhigh o max devuelve un error 400 en Claude Opus 5. Vuelve a habilitar el pensamiento o reduce el effort a high o inferior.
• Si usas web fetch, planifica una alternativa: no está disponible en Claude Opus 5.
• Vuelve a ejecutar el conteo de tokens contra Claude Opus 5 en lugar de reutilizar los conteos medidos contra Claude Sonnet 5, y vuelve a establecer la línea base de costo y latencia en tus propias cargas de trabajo; el precio por token difiere.



Migrar a Claude Sonnet 5

Claude Sonnet 5 ofrece la mejor combinación de velocidad e inteligencia en la familia de modelos Claude. Se basa en Claude Sonnet 4.6.

Claude Sonnet 5 es una actualización directa para Claude Sonnet 4.6. El precio introductorio de $2/$10 USD por millón de tokens de entrada/salida está vigente hasta el 31 de agosto de 2026, después de lo cual entrará en vigor el precio estándar de $3/$15 USD por millón de tokens de entrada/salida; consulta Precios para más detalles. Hay dos cambios incompatibles en la API para el código que ya se ejecuta en Claude Sonnet 4.6: el pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) y los parámetros de muestreo (temperature, top_p, top_k) establecidos en valores no predeterminados ya no se aceptan y devuelven un error 400. Usa el pensamiento adaptativo con el parámetro effort en su lugar. Claude Sonnet 5 admite el mismo conjunto de funciones que Claude Sonnet 4.6, incluida la ventana de contexto de 1M de tokens, el pensamiento adaptativo, el almacenamiento en caché de prompts, el procesamiento por lotes, la API de Files, el soporte de PDF, la visión y el conjunto completo de herramientas del lado del servidor y del lado del cliente. Priority Tier no está disponible en Claude Sonnet 5. Claude Sonnet 5 también usa un nuevo tokenizador.



Migrar a Claude Sonnet 5 desde Claude Sonnet 4.6



Actualiza el nombre de tu modelo

# Migración a Sonnet
model = "claude-sonnet-4-6"  # Before
model = "claude-sonnet-5"  # After



Qué cambió

Los elementos 4 y 5 de la siguiente lista son cambios incompatibles. max_tokens sigue siendo un límite estricto sobre la salida total (pensamiento más texto de respuesta), así que revísalo para cargas de trabajo que se ejecutaban sin pensamiento en Claude Sonnet 4.6.

1. Nuevo tokenizador: Claude Sonnet 5 usa un nuevo tokenizador. El mismo texto de entrada produce aproximadamente un 30% más de tokens que en Claude Sonnet 4.6. El aumento exacto depende del contenido. Las solicitudes, respuestas y eventos de streaming mantienen la misma forma, y no se requieren cambios de código, pero todo lo que midas o presupuestes en tokens cambia: los campos usage y los resultados del conteo de tokens para el mismo texto son más altos, la ventana de contexto de 1M de tokens contiene menos texto, y un límite de max_tokens ajustado para Claude Sonnet 4.6 puede truncar una salida equivalente. El precio por token no cambia, por lo que el costo de una solicitud equivalente puede diferir. Vuelve a ejecutar el conteo de tokens contra Claude Sonnet 5 en lugar de reutilizar los conteos medidos contra modelos anteriores.

2. 128k tokens máximos de salida (sin cambios): Claude Sonnet 5 admite hasta 128k tokens de salida, lo mismo que Claude Sonnet 4.6. Los valores existentes de max_tokens siguen siendo válidos. Ten en cuenta el nuevo tokenizador al dimensionarlos.

3. Prellenado de mensajes del asistente (sin cambios): Prellenar el mensaje del asistente devuelve un error 400 en Claude Sonnet 5, igual que en Claude Sonnet 4.6. Si eliminaste el prellenado al migrar a Claude Sonnet 4.6, no se necesitan más cambios. Usa salidas estructuradas, instrucciones en la indicación del sistema o output_config.format en su lugar.

4. Pensamiento adaptativo activado de forma predeterminada: En Claude Sonnet 4.6, las solicitudes sin un campo thinking se ejecutan sin pensamiento; en Claude Sonnet 5, las mismas solicitudes se ejecutan con pensamiento adaptativo. Para desactivar el pensamiento, pasa thinking: {type: "disabled"}. El pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) no es compatible y devuelve un error 400. Usa el parámetro effort (predeterminado high) para controlar la profundidad del pensamiento.

   Claude Sonnet 5

   Claude Sonnet 5

   Claude Sonnet 4.6

   Claude Sonnet 4.6

   

   El pensamiento adaptativo está activado de forma predeterminada para Claude Sonnet 5. El campo thinking se muestra explícitamente aquí para establecer display: "summarized"; si omites thinking, Claude Sonnet 5 omite el contenido de pensamiento de la respuesta de forma predeterminada. Para los valores predeterminados por modelo, consulta Configuraciones que cada modelo rechaza.

   cURLCLIPythonTypeScriptC#GoJavaPHPRuby

   

   client = anthropic.Anthropic()
   
   response = client.messages.create(
       model="claude-sonnet-5",
       max_tokens=16000,
       thinking={"type": "adaptive", "display": "summarized"},
       output_config={"effort": "high"},
       messages=[
           {
               "role": "user",
               "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
           }
       ],
   )
   
   # La respuesta contiene bloques de pensamiento resumidos y bloques de texto
   for block in response.content:
       match block.type:
           case "thinking":
               print(f"\nThinking summary: {block.thinking}")
           case "text":
               print(f"\nResponse: {block.text}")

5. Parámetros de muestreo eliminados: Los parámetros de muestreo (temperature, top_p, top_k) establecidos en un valor no predeterminado no se aceptan y devuelven un error 400.

6. Salvaguardas de ciberseguridad: Claude Sonnet 5 es el primer modelo de nivel Sonnet con salvaguardas de ciberseguridad en tiempo real. Las solicitudes que involucren temas de ciberseguridad prohibidos o de alto riesgo pueden ser rechazadas. Los rechazos se devuelven como una respuesta HTTP 200 exitosa con stop_reason: "refusal", no como un error. Consulta Salvaguardas, advertencias y apelaciones para obtener contexto.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-sonnet-4-6 a claude-sonnet-5.
• Vuelve a ejecutar el conteo de tokens contra Claude Sonnet 5. El nuevo tokenizador produce aproximadamente un 30% más de tokens para el mismo texto, lo que puede cambiar el costo por solicitud aunque el precio por token no cambie. El aumento exacto depende del contenido y la forma de la carga de trabajo.
• Revisa los límites de max_tokens dimensionados cerca de tu longitud de salida esperada, y auméntalos hasta el máximo de 128k (sin cambios respecto a Claude Sonnet 4.6) donde sea útil.
• Elimina la configuración thinking: {type: "enabled", budget_tokens: N} (devuelve un error 400). El pensamiento adaptativo está activado de forma predeterminada; pasa {type: "disabled"} para desactivarlo, o usa el parámetro effort para controlar la profundidad.
• Elimina los parámetros temperature, top_p y top_k establecidos en valores no predeterminados (devuelven un error 400 en Claude Sonnet 5).
• Agrega manejo para stop_reason: "refusal" si tu carga de trabajo puede tocar temas de ciberseguridad.
• Vuelve a establecer la línea base de costo en tu carga de trabajo típica antes del despliegue en producción.
• Revisa max_tokens para cargas de trabajo que anteriormente se ejecutaban sin pensamiento.



Migrar a Claude Sonnet 5 desde Claude Sonnet 4.5 y modelos Sonnet anteriores

Si estás migrando desde Claude Sonnet 4.5 o un modelo Sonnet anterior directamente a Claude Sonnet 5, aplica los cambios de Migrar a Claude Sonnet 5 desde Claude Sonnet 4.6 más los cambios de esta sección.



Cambios incompatibles

Al migrar desde Sonnet 4.5

1. El prellenado de mensajes del asistente ya no es compatible

   

   Este es un cambio incompatible al migrar desde Sonnet 4.5 o anterior.

   Prellenar mensajes del asistente devuelve un error 400 en Claude Sonnet 4.6 y modelos posteriores, incluido Claude Sonnet 5. Usa salidas estructuradas, instrucciones en la indicación del sistema o output_config.format en su lugar.

   Casos de uso comunes de prellenado y sus migraciones:

   • Controlar el formato de salida (forzar salida JSON/YAML): Usa salidas estructuradas o herramientas con campos enum para tareas de clasificación.

   • Eliminar preámbulos (eliminar frases como "Aquí está..."): Agrega instrucciones directas en la indicación del sistema: "Responde directamente sin preámbulo. No comiences con frases como 'Aquí está...', 'Basado en...', etc."

   • Evitar rechazos incorrectos: Claude ahora es mucho mejor en los rechazos apropiados. Una indicación clara en el mensaje del usuario sin prellenado debería ser suficiente.

   • Continuaciones (reanudar respuestas interrumpidas): Mueve la continuación al mensaje del usuario: "Tu respuesta anterior fue interrumpida y terminó con [previous_response]. Continúa desde donde lo dejaste."

   • Hidratación de contexto / consistencia de rol (refrescar el contexto en conversaciones largas): Inyecta lo que antes eran recordatorios prellenados del asistente en el turno del usuario en su lugar.

2. El escape de JSON en parámetros de herramientas puede diferir

   

   Este es un cambio incompatible al migrar desde Sonnet 4.5 o anterior.

   El escape de cadenas JSON en los parámetros de herramientas puede diferir de modelos anteriores. Los analizadores JSON estándar manejan esto automáticamente, pero el análisis personalizado basado en cadenas puede necesitar actualizaciones.

Cambios en el pensamiento extendido: Las configuraciones de budget_tokens de Claude Sonnet 4.5 (thinking: {type: "enabled", budget_tokens: N}) no son compatibles en Claude Sonnet 5 y devuelven un error 400. El pensamiento adaptativo está activado de forma predeterminada, por lo que la mayoría de las cargas de trabajo no necesitan ninguna configuración de thinking; usa el parámetro effort para controlar la profundidad del pensamiento. Si ejecutabas Claude Sonnet 4.5 sin pensamiento extendido, pasa thinking: {type: "disabled"} para preservar ese comportamiento.

Al migrar desde Claude 3.x

1. Elimina los parámetros de muestreo

   

   Este es un cambio incompatible al migrar desde modelos Claude 3.x.

   Los parámetros de muestreo (temperature, top_p, top_k) establecidos en un valor no predeterminado devuelven un error 400 en Claude Sonnet 5. Elimínalos de las solicitudes y usa indicaciones para guiar el comportamiento del modelo en su lugar.

2. Actualiza las versiones de las herramientas

   

   Este es un cambio incompatible al migrar desde modelos Claude 3.x.

   Actualiza a las versiones más recientes de las herramientas (text_editor_20250728, code_execution_20260521). Elimina cualquier código que use el comando undo_edit.

3. Maneja la razón de detención refusal

   Actualiza tu aplicación para manejar las razones de detención refusal.

4. Actualiza tus prompts para los cambios de comportamiento

   Los modelos Claude 4 tienen un estilo de comunicación más conciso y directo. Revisa las mejores prácticas de prompting para obtener orientación de optimización.



Migrar a Claude Sonnet 5 desde Claude Haiku 4.5

Claude Haiku 4.5 y Claude Sonnet 5 difieren más a nivel de API que los modelos adyacentes dentro de una misma clase: Claude Haiku 4.5 usa pensamiento extendido manual (desactivado de forma predeterminada), una ventana de contexto de 200k tokens y hasta 64k tokens de salida, mientras que Claude Sonnet 5 se ejecuta con pensamiento adaptativo activado de forma predeterminada, ofrece una ventana de contexto de 1M de tokens de forma predeterminada y admite hasta 128k tokens de salida.



Actualiza el nombre de tu modelo

model = "claude-haiku-4-5-20251001"  # Before
model = "claude-sonnet-5"  # After



Qué cambió

1. Configuración de pensamiento: Claude Haiku 4.5 admite pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) y rechaza thinking: {type: "adaptive"}. En Claude Sonnet 5, el soporte es el inverso: el pensamiento adaptativo está activado de forma predeterminada, y el pensamiento extendido manual devuelve un error 400. Elimina las configuraciones thinking: {type: "enabled", budget_tokens: N} y confía en el valor predeterminado, o pasa thinking: {type: "disabled"} para desactivar el pensamiento. budget_tokens no tiene un reemplazo directo; usa el parámetro effort para controlar la profundidad del pensamiento. Effort no está disponible en Claude Haiku 4.5 y su valor predeterminado es high en Claude Sonnet 5.

2. Parámetros de muestreo eliminados: temperature y top_p funcionan en Claude Haiku 4.5 (uno a la vez, no ambos). En Claude Sonnet 5, establecer temperature, top_p o top_k en un valor no predeterminado devuelve un error 400. Elimina estos parámetros y usa indicaciones para guiar el comportamiento del modelo.

3. Prellenado del asistente eliminado: Prellenar el mensaje del asistente funciona en Claude Haiku 4.5 pero devuelve un error 400 en Claude Sonnet 5. Usa salidas estructuradas, instrucciones en la indicación del sistema o output_config.format en su lugar.

4. Ventana de contexto y salida más grandes: Claude Sonnet 5 ofrece una ventana de contexto de 1M de tokens de forma predeterminada, frente a los 200k tokens de Claude Haiku 4.5, y admite hasta 128k tokens de salida, frente a 64k. Claude Sonnet 5 también usa un tokenizador diferente, así que vuelve a ejecutar el conteo de tokens en lugar de reutilizar los conteos medidos contra Claude Haiku 4.5.

5. Precios: Claude Haiku 4.5 tiene un precio de $1/$5 por millón de tokens de entrada/salida. Para Claude Sonnet 5, el precio introductorio de $2/$10 por millón de tokens de entrada/salida está vigente hasta el 31 de agosto de 2026, después de lo cual entra en vigor el precio estándar de $3/$15. Consulta los precios de Claude.

6. Salvaguardas de ciberseguridad: Claude Sonnet 5 tiene salvaguardas de ciberseguridad en tiempo real. Las solicitudes que involucren temas de ciberseguridad prohibidos o de alto riesgo pueden ser rechazadas, devueltas como una respuesta HTTP 200 exitosa con stop_reason: "refusal". Consulta Salvaguardas, advertencias y apelaciones para obtener contexto.



Lista de verificación de migración

• Actualiza el nombre del modelo de claude-haiku-4-5-20251001 (o el alias claude-haiku-4-5) a claude-sonnet-5.
• Elimina la configuración thinking: {type: "enabled", budget_tokens: N} (devuelve un error 400). El pensamiento adaptativo está activado de forma predeterminada; pasa thinking: {type: "disabled"} para preservar el comportamiento sin pensamiento, y revisa max_tokens para cargas de trabajo que se ejecutaban sin pensamiento.
• Usa el parámetro effort (predeterminado high) para controlar la profundidad del pensamiento y el gasto de tokens; no está disponible en Claude Haiku 4.5, por lo que ninguna configuración existente se transfiere.
• Elimina las configuraciones de temperature y top_p (los valores no predeterminados devuelven un error 400 en Claude Sonnet 5).
• Elimina cualquier prellenado de mensajes del asistente (devuelven un error 400 en Claude Sonnet 5).
• Vuelve a ejecutar el conteo de tokens contra Claude Sonnet 5, y revisa los límites de max_tokens, que puedes aumentar hasta el máximo de 128k.
• Agrega manejo para stop_reason: "refusal" si tu carga de trabajo puede tocar temas de ciberseguridad.
• Vuelve a establecer la línea base de costo en tu carga de trabajo típica antes del despliegue en producción; el precio por token difiere.



Migrar a Claude Haiku 4.5

Claude Haiku 4.5 es el modelo Haiku más rápido e inteligente con rendimiento cercano a la frontera, ofreciendo calidad de modelo premium para aplicaciones interactivas y procesamiento de alto volumen.

Para una descripción completa de las capacidades, consulta la descripción general de modelos.



Migrar a Claude Haiku 4.5 desde Claude Haiku 3.5 y modelos Haiku anteriores

Actualiza el nombre de tu modelo:

# Desde Haiku 3.5
model = "claude-3-5-haiku-20241022"  # Before
model = "claude-haiku-4-5-20251001"  # After

Revisa los nuevos límites de velocidad: Haiku 4.5 tiene límites de velocidad separados de Haiku 3.5. Consulta la documentación de Límites de velocidad para más detalles.

Explora nuevas capacidades: Consulta la descripción general de modelos para obtener detalles sobre la conciencia de contexto, la mayor capacidad de salida (64k tokens), la mayor inteligencia y la velocidad mejorada.



Cambios incompatibles

Estos cambios incompatibles se aplican al migrar desde modelos Claude 3.x Haiku.

1. Actualiza los parámetros de muestreo

   

   Este es un cambio incompatible al migrar desde modelos Claude 3.x.

   Usa solo temperature O top_p, no ambos. Establecer ambos devuelve un error 400 en Claude Haiku 4.5.

2. Actualiza las versiones de las herramientas

   

   Este es un cambio incompatible al migrar desde modelos Claude 3.x.

   Actualiza a las versiones más recientes de las herramientas (text_editor_20250728, code_execution_20250825). Elimina cualquier código que use el comando undo_edit.

3. Maneja la razón de detención refusal

   Actualiza tu aplicación para manejar las razones de detención refusal.

4. Actualiza tus prompts para los cambios de comportamiento

   Los modelos Claude 4 tienen un estilo de comunicación más conciso y directo. Revisa las mejores prácticas de prompting para obtener orientación de optimización.



Lista de verificación de migración a Haiku 4.5

• Actualiza el ID del modelo a claude-haiku-4-5-20251001
• INCOMPATIBLE: Actualiza las versiones de las herramientas a las más recientes (text_editor_20250728, code_execution_20250825); las versiones heredadas no son compatibles
• INCOMPATIBLE: Elimina cualquier código que use el comando undo_edit (si aplica)
• INCOMPATIBLE: Actualiza los parámetros de muestreo para usar solo temperature O top_p, no ambos (establecer ambos devuelve un error 400)
• Maneja la nueva razón de detención refusal en tu aplicación
• Revisa y ajusta para los nuevos límites de velocidad (separados de Haiku 3.5)
• Revisa y actualiza los prompts siguiendo las mejores prácticas de prompting
• Considera habilitar el pensamiento extendido para tareas de razonamiento complejas
• Prueba en un entorno de desarrollo antes del despliegue en producción



Obtén ayuda

• Consulta la documentación de la API para especificaciones detalladas
• Revisa las capacidades de los modelos para comparaciones de rendimiento
• Revisa las notas de la versión de la API para actualizaciones de la API
• Contacta a soporte si encuentras algún problema durante la migración