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 continuar funcionando sin modificación, aunque el comportamiento de la API ha cambiado ligeramente en los modelos Claude 4 (consulta las notas de lanzamiento de la API para más detalles).

​

Qué hay de nuevo en Claude 4

​

Nueva razón de parada por rechazo

Los modelos Claude 4 introducen una nueva razón de parada 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":"I would be happy to assist you. You can "}],
"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 parada refusal.

​

Pensamiento resumido

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

Aunque la API es consistente entre los modelos Claude 3.7 y 4, las respuestas de streaming para el pensamiento extendido podrían devolver 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 soportan intercalar el uso de herramientas con pensamiento extendido, permitiendo conversaciones más naturales donde los usos de herramientas y 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_20250728
• Nombre de 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 usando 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_20250728",
        "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 usando 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á 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á efecto.

​

Consideraciones de rendimiento

​

Claude Sonnet 4

• Capacidades de razonamiento e inteligencia mejoradas comparadas 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 de migración

• Actualizar el id del modelo en tus llamadas API
• Probar solicitudes existentes (deberían funcionar sin cambios)
• Eliminar el encabezado beta token-efficient-tools-2025-02-19 si aplica
• Eliminar el encabezado beta output-128k-2025-02-19 si aplica
• Manejar la nueva razón de parada refusal
• Actualizar el tipo y nombre de la herramienta de editor de texto si la usas
• 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 de Claude 4 para resultados óptimos
• Probar en desarrollo antes del despliegue en producción

​

¿Necesitas ayuda?

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