Migración a Claude 4

Esta página proporciona orientación sobre la migración de los modelos Claude 3.7 a los modelos Claude 4 (Opus 4 y Sonnet 4).

En la mayoría de los casos, puedes cambiar a los modelos Claude 4 con cambios mínimos:

1. Actualiza el nombre de tu modelo:

   • De: claude-3-7-sonnet-20250219
   • A: claude-sonnet-4-20250514 o claude-opus-4-20250514

2. Las llamadas API existentes deberían seguir funcionando sin modificaciones, aunque el comportamiento de la API ha cambiado ligeramente en los modelos Claude 4 (consulta las notas de la versión de la API para más detalles).

​

Novedades en Claude 4

​

Nueva razón de detención por rechazo

Los modelos Claude 4 introducen una nueva razón de detención refusal para contenido que el modelo se niega a generar por razones de seguridad, debido a la mayor inteligencia de los modelos Claude 4:

{"id":"msg_014XEDjypDjFzgKVWdFUXxZP",
"type":"message",
"role":"assistant",
"model":"claude-sonnet-4-20250514",
"content":[{"type":"text","text":"Estaré encantado de ayudarte. Puedes "}],
"stop_reason":"refusal",
"stop_sequence":null,
"usage":{"input_tokens":564,"cache_creation_input_tokens":0,"cache_read_input_tokens":0,"output_tokens":22}
}

Al migrar a Claude 4, debes actualizar tu aplicación para manejar las razones de detención refusal.

​

Pensamiento resumido

Con el pensamiento extendido habilitado, la API de Mensajes para los modelos Claude 4 devuelve un resumen del proceso de pensamiento completo de Claude. El pensamiento resumido proporciona todos los beneficios de inteligencia del pensamiento extendido, al tiempo que previene el uso indebido.

Aunque la API es consistente entre los modelos Claude 3.7 y 4, las respuestas en streaming para el pensamiento extendido podrían devolverse en un patrón de entrega “fragmentado”, con posibles retrasos entre eventos de streaming.

Para más información, consulta la documentación de Pensamiento extendido.

​

Pensamiento intercalado

Los modelos Claude 4 admiten intercalar el uso de herramientas con el pensamiento extendido, permitiendo conversaciones más naturales donde los usos de herramientas y las respuestas pueden mezclarse con mensajes regulares.

Para más información, consulta la documentación de Pensamiento extendido.

​

Herramienta de editor de texto actualizada

La herramienta de editor de texto ha sido actualizada para los modelos Claude 4 con los siguientes cambios:

• Tipo de herramienta: text_editor_20250429
• Nombre de la herramienta: str_replace_based_edit_tool
• El comando undo_edit ya no es compatible con los modelos Claude 4.

Si estás migrando desde Claude Sonnet 3.7 y utilizando la herramienta de editor de texto:

# Claude Sonnet 3.7
tools=[
    {
        "type": "text_editor_20250124",
        "name": "str_replace_editor"
    }
]

# Claude 4
tools=[
    {
        "type": "text_editor_20250429",
        "name": "str_replace_based_edit_tool"
    }
]

Para más información, consulta la documentación de la herramienta de editor de texto.

​

Uso de herramientas eficiente en tokens ya no es compatible

El uso de herramientas eficiente en tokens solo está disponible en Claude Sonnet 3.7.

Si estás migrando desde Claude Sonnet 3.7 y utilizando el uso de herramientas eficiente en tokens, recomendamos eliminar el encabezado beta token-efficient-tools-2025-02-19 de tus solicitudes.

El encabezado beta token-efficient-tools-2025-02-19 aún puede incluirse en las solicitudes de Claude 4, pero no tendrá ningún efecto.

​

Salida extendida ya no es compatible

El encabezado beta output-128k-2025-02-19 para salida extendida solo está disponible en Claude Sonnet 3.7.

Si estás migrando desde Claude Sonnet 3.7, recomendamos eliminar output-128k-2025-02-19 de tus solicitudes.

El encabezado beta output-128k-2025-02-19 aún puede incluirse en las solicitudes de Claude 4, pero no tendrá ningún efecto.

​

Consideraciones de rendimiento

​

Claude Sonnet 4

• Capacidades de razonamiento e inteligencia mejoradas en comparación con Claude Sonnet 3.7
• Precisión mejorada en el uso de herramientas

​

Claude Opus 4

• Modelo más capaz con razonamiento e inteligencia superiores
• Más lento que los modelos Sonnet
• Mejor para tareas complejas que requieren análisis profundo

​

Lista de verificación para la migración

• Actualizar el ID del modelo en tus llamadas API
• Probar las solicitudes existentes (deberían funcionar sin cambios)
• Eliminar el encabezado beta token-efficient-tools-2025-02-19 si corresponde
• Eliminar el encabezado beta output-128k-2025-02-19 si corresponde
• Manejar la nueva razón de detención refusal
• Actualizar el tipo y nombre de la herramienta de editor de texto si la estás utilizando
• Eliminar cualquier código que use el comando undo_edit
• Explorar las nuevas capacidades de intercalado de herramientas con pensamiento extendido
• Revisar las mejores prácticas de ingeniería de prompts para Claude 4 para obtener resultados óptimos
• Probar en desarrollo antes de la implementación en producción

​

¿Necesitas ayuda?

• Consulta nuestra documentación de la API para especificaciones detalladas.
• Revisa las capacidades del modelo para comparaciones de rendimiento.
• Revisa las notas de la versión de la API para actualizaciones de la API.
• Contacta con soporte si encuentras algún problema durante la migración.