Migración 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, con un precio de $2/$10 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. Primero, el pensamiento adaptativo está activado por defecto y el "extended thinking" (pensamiento extendido) manual (thinking: {type: "enabled", budget_tokens: N}) devuelve un error 400, por lo que las solicitudes que se ejecutaban sin pensamiento ahora pueden devolver bloques thinking antes del primer bloque text, y el código que lee el contenido por posición debe seleccionar los bloques de contenido por type. Segundo, los parámetros de muestreo (temperature, top_p, top_k) establecidos en valores no predeterminados devuelven un error 400. Usa el pensamiento adaptativo con el parámetro effort para controlar la profundidad del pensamiento. Claude Sonnet 5 admite el mismo conjunto de funciones que Claude Sonnet 4.6, incluyendo la "context window" (ventana de contexto) de 1M de tokens, el pensamiento adaptativo, el "prompt caching" (almacenamiento en caché de prompts), el procesamiento por lotes, la Files API, la compatibilidad con PDF, la visión y el conjunto completo de herramientas del lado del servidor y del lado del cliente. En la Claude API y Google Cloud, Claude Sonnet 5 también admite el uso de computadora como el conjunto de herramientas estable computer_toolset_20260801 y la herramienta de uso de navegador para tareas dentro de páginas web, ninguna de las cuales es compatible con Claude Sonnet 4.6; las integraciones existentes en la versión anterior computer_20251124 siguen funcionando sin cambios en ambos modelos. Para actualizar una integración existente, consulta Migrar desde computer_20251124. Priority Tier no está disponible en Claude Sonnet 5. Claude Sonnet 5 también usa un nuevo tokenizador.

Migración 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 las 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 es más bajo ($2/$10 USD frente a los $3/$15 USD de Claude Sonnet 4.6 por millón de tokens de entrada/salida), pero el costo de una solicitud equivalente no disminuye en proporción directa. Vuelve a ejecutar el conteo de tokens contra Claude Sonnet 5 en lugar de reutilizar conteos medidos contra modelos anteriores.

2. 128k tokens de salida máximos (sin cambios): Claude Sonnet 5 admite hasta 128k tokens de salida, igual 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 por defecto: 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.

   Con el pensamiento activado, una respuesta puede comenzar con uno o más bloques thinking antes del primer bloque text, devueltos con un campo thinking vacío con el valor predeterminado display: "omitted". El código que lee la respuesta por posición, como content[0].text o un manejador de stream que trata el primer bloque de contenido como texto, debe seleccionar los bloques de contenido por su campo type en su lugar, y los bucles de uso de herramientas deben devolver los bloques thinking completos y sin modificar junto con sus resultados de herramientas (consulta Preservar bloques de pensamiento). Los tokens de pensamiento se facturan como tokens de salida incluso cuando el texto del pensamiento no se devuelve. Si usabas pensamiento en Claude Sonnet 4.6 y muestras el texto de pensamiento devuelto, ten en cuenta que thinking.display tenía como valor predeterminado "summarized" allí y tiene como valor predeterminado "omitted" en Claude Sonnet 5; establece display: "summarized", como lo hace el siguiente ejemplo, para seguir recibiendo resúmenes legibles (consulta Controlar la visualización del pensamiento).

   Claude Sonnet 5Claude Sonnet 4.6

   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 cibernéticas en tiempo real en Claude Opus y Sonnet para saber qué bloquean las salvaguardas y cómo el trabajo de seguridad legítimo puede postularse al Cyber Verification Program.

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 sea más bajo. El aumento exacto depende del contenido y de 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 por defecto; pasa {type: "disabled"} para desactivarlo, o usa el parámetro effort para controlar la profundidad.
• Actualiza el análisis de respuestas que lee el contenido por posición, como content[0].text: con el pensamiento activado, los bloques thinking llegan antes de los bloques text. Selecciona los bloques de contenido por type en su lugar, y devuelve los bloques thinking sin modificar en los bucles de uso de herramientas; los bloques modificados devuelven un error 400.
• Verifica que cualquier código que analice el campo thinking lo trate solo como texto de visualización. thinking.display tiene como valor predeterminado "omitted" en Claude Sonnet 5 (tenía como valor predeterminado "summarized" en Claude Sonnet 4.6), por lo que los bloques de pensamiento llegan con un campo thinking vacío; establece display: "summarized" para recibir resúmenes legibles. Consulta Controlar la visualización del pensamiento.
• 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 costos en tu carga de trabajo típica antes del despliegue en producción.
• Revisa max_tokens para las cargas de trabajo que anteriormente se ejecutaban sin pensamiento.

Migración 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 Migración 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

   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 del 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 (quitar 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 te quedaste."

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

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

   El escape de cadenas JSON en los parámetros de herramientas puede diferir de los 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 con Claude Sonnet 5 y devuelven un error 400. El pensamiento adaptativo está activado por defecto, 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

3. Elimina los parámetros de muestreo

   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.

4. Actualiza las versiones de herramientas

   Actualiza a las últimas versiones de herramientas (text_editor_20250728, code_execution_20260521). Elimina cualquier código que use el comando undo_edit.

5. Maneja el motivo de parada refusal

   Actualiza tu aplicación para manejar los motivos de parada refusal.

6. 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 sobre optimización.

Migración 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 por defecto), una ventana de contexto de 200k tokens y hasta 64k tokens de salida, mientras que Claude Sonnet 5 se ejecuta con pensamiento adaptativo activado por defecto, ofrece una ventana de contexto de 1M de tokens por defecto 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 del pensamiento: Claude Haiku 4.5 admite pensamiento extendido manual (thinking: {type: "enabled", budget_tokens: N}) y rechaza thinking: {type: "adaptive"}. En Claude Sonnet 5, la compatibilidad se invierte: el pensamiento adaptativo está activado por defecto 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 tiene como valor predeterminado high en Claude Sonnet 5.

   La forma de la respuesta cambia para ambos tipos de solicitud de Claude Haiku 4.5. Las solicitudes que se ejecutaban sin pensamiento extendido ahora pueden devolver uno o más bloques thinking antes del primer bloque text, por lo que el código que lee la respuesta por posición, como content[0].text, debe seleccionar los bloques de contenido por su campo type en su lugar, y los bucles de uso de herramientas deben devolver los bloques thinking completos y sin modificar junto con sus resultados de herramientas (consulta Preservar bloques de pensamiento). Las solicitudes que usaban pensamiento extendido siguen recibiendo bloques thinking, pero thinking.display tiene como valor predeterminado "omitted" en Claude Sonnet 5 en lugar de "summarized", por lo que esos bloques llegan con un campo thinking vacío; establece display: "summarized" para seguir recibiendo resúmenes legibles (consulta Controlar la visualización del pensamiento). Los tokens de pensamiento se facturan como tokens de salida incluso cuando el texto del pensamiento no se devuelve.

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 por defecto, 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 conteos medidos contra Claude Haiku 4.5.

5. Precios: Claude Haiku 4.5 tiene un precio de $1/$5 USD por millón de tokens de entrada/salida. Claude Sonnet 5 tiene un precio de $2/$10 USD por millón de tokens de entrada/salida. Consulta 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 cibernéticas en tiempo real en Claude Opus y Sonnet para saber qué bloquean las salvaguardas y cómo el trabajo de seguridad legítimo puede postularse al Cyber Verification Program.

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 por defecto; pasa thinking: {type: "disabled"} para preservar el comportamiento sin pensamiento, y revisa max_tokens para las cargas de trabajo que se ejecutaban sin pensamiento.
• Actualiza el análisis de respuestas que lee el contenido por posición, como content[0].text: con el pensamiento activado, los bloques thinking llegan antes de los bloques text. Selecciona los bloques de contenido por type en su lugar, y devuelve los bloques thinking sin modificar en los bucles de uso de herramientas; los bloques modificados devuelven un error 400.
• Si tu interfaz de usuario muestra contenido de pensamiento, establece display: "summarized". thinking.display tiene como valor predeterminado "omitted" en Claude Sonnet 5, por lo que de otro modo los bloques de pensamiento llegan con un campo thinking vacío. Consulta Controlar la visualización del 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 traslada.
• 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 costos en tu carga de trabajo típica antes del despliegue en producción; el precio por token difiere.