Tabla de contenidos

1. A quién va dirigida esta guía

Como contamos en el artículo de lanzamiento de Claude Opus 4.7, Opus 4.7 es el sucesor directo de 4.6. Sin embargo, a nivel de API trae varios breaking changes a la vez, así que cambiar solo el nombre del modelo puede dejarte con errores 400 Bad Request.

Este artículo está pensado para quienes se encuentren en alguno de estos casos:

  • Personas desarrolladoras que llaman a claude-opus-4-6 y familia vía la API o el SDK de Anthropic
  • Equipos que usan Claude a través de Bedrock o Vertex AI
  • Quien se quedó en Opus 4.5 o 4.1 y quiere saltar directamente a 4.7
  • Quien usa en producción extended thinking (thinking: enabled) o temperature

Partimos de la guía de migración oficial de Anthropic y ponemos el foco en los puntos donde es fácil atascarse en el día a día del desarrollo. La información oficial está en la guía de migración de platform.claude.com.

Visión general de la guía de migración a Claude Opus 4.7

2. Resumen en 3 líneas — visión rápida

El TL;DR para quien no tenga tiempo.

  1. Cambia el nombre del modelo de claude-opus-4-6 a claude-opus-4-7 (y actualiza la versión del SDK)
  2. Tres breaking changes principales: se retira extended thinking enabled (pasa a adaptive thinking + effort), se retiran temperature/top_p/top_k y el nuevo tokenizador sube los tokens hasta 1,35 veces para el mismo texto
  3. A cambio ganas: mejor rendimiento en programación, contexto de 1M (tarifa estándar) y un nuevo nivel de esfuerzo llamado xhigh

El detalle, en los siguientes capítulos.

3. Actualizar el nombre del modelo

Lo primero es simple: cambiar el identificador del modelo.

# Before
model = "claude-opus-4-6"

# After
model = "claude-opus-4-7"

Si lo gestionas por variables de entorno o ficheros de configuración, déjalo en un único sitio: así la siguiente migración será aún más fácil.

// .env
// CLAUDE_MODEL=claude-opus-4-6
CLAUDE_MODEL=claude-opus-4-7

// app.ts
const model = process.env.CLAUDE_MODEL ?? "claude-opus-4-7";

Pero ojo: en muchos casos no basta con cambiar el nombre del modelo. Lo difícil de esta migración son los breaking changes. Vamos uno a uno.

4. Breaking change 1: extended thinking retirado, llega adaptive

En Opus 4.6, para activar el extended thinking había que indicar thinking: {type: "enabled", budget_tokens: N}. En 4.7 ese formato da error 400.

En su lugar, se usa «adaptive thinking», donde es el modelo quien ajusta por sí solo cuánto piensa. Además, en 4.7 el thinking viene OFF por defecto: si omites el campo thinking, no piensa. Si no lo activas explícitamente, no tendrás el razonamiento profundo al que quizá estabas acostumbrado.

Before (4.6) / After (4.7)

# Before: Opus 4.6
client.messages.create(
    model="claude-opus-4-6",
    max_tokens=64000,
    thinking={"type": "enabled", "budget_tokens": 32000},
    messages=[{"role": "user", "content": "..."}],
)

# After: Opus 4.7
client.messages.create(
    model="claude-opus-4-7",
    max_tokens=64000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},  # "max", "xhigh", "high", "medium", "low"
    messages=[{"role": "user", "content": "..."}],
)

// Before: Opus 4.6
await client.messages.create({
  model: "claude-opus-4-6",
  max_tokens: 64000,
  thinking: { type: "enabled", budget_tokens: 32000 },
  messages: [{ role: "user", content: "..." }],
});

// After: Opus 4.7
await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 64000,
  thinking: { type: "adaptive" },
  output_config: { effort: "high" },
  messages: [{ role: "user", content: "..." }],
});

Puntos clave

  • Ya no hace falta controlar directamente la «cantidad de pensamiento» con budget_tokens
  • Ahora se indica «cuánto se lo va a pensar» a través de output_config.effort
  • Si no incluyes el campo thinking, responde sin pensar (ojo: cambia el comportamiento respecto a 4.6)

5. Breaking change 2: parámetros de muestreo retirados

Si pasas un valor distinto al por defecto en temperature, top_p o top_k, la API devuelve error 400. Es la aplicación total del criterio de Anthropic: «el comportamiento del modelo se controla desde el prompt».

# Before
client.messages.create(
    model="claude-opus-4-6",
    temperature=0.7,
    top_p=0.9,
    top_k=40,
    messages=[...],
)

# After
client.messages.create(
    model="claude-opus-4-7",
    # temperature / top_p / top_k se eliminan por completo
    messages=[...],
)

Si hasta ahora conseguías «respuestas estables» con temperature=0.2, deberás indicarlo en el prompt («mantén respuestas lo más consistentes posible ante la misma pregunta») o combinarlo con salidas estructuradas (structured outputs) vía esquemas JSON.

Y si usabas temperature=1.2 para pedir «creatividad», mete instrucciones de tono en el prompt: «usa expresiones metafóricas e inesperadas», por ejemplo.

6. Breaking change 3: contenido del thinking oculto por defecto

En 4.6, al activar el thinking, el «resumen del pensamiento (summarized)» llegaba por defecto en el stream de la respuesta. Muchas apps lo mostraban en la UI como «pensando...».

En 4.7 el comportamiento cambió silenciosamente: los bloques de thinking aparecen en la respuesta, pero el campo thinking queda vacío. Si no lo activas explícitamente, no recibes el contenido.

Síntoma

El indicador de «pensando...» se queda girando eternamente en la UI y la persona usuaria siente que hay una espera rarísima antes de que empiece la respuesta. Es el típico caso del «¿se ha quedado colgado?».

Solución

# Para mostrar el resumen del thinking en la UI como en 4.6
client.messages.create(
    model="claude-opus-4-7",
    thinking={
        "type": "adaptive",
        "display": "summarized",  # hay que indicarlo explícitamente
    },
    output_config={"effort": "high"},
    messages=[...],
)

await client.messages.create({
  model: "claude-opus-4-7",
  thinking: {
    type: "adaptive",
    display: "summarized",
  },
  output_config: { effort: "high" },
  messages: [...],
});

Si solo lo usas por detrás sin enseñar el thinking a la persona usuaria, puedes dejar display fuera sin problema.

7. Breaking change 4: nuevo tokenizador (~1,35x)

Opus 4.7 estrena un nuevo tokenizador interno. Contribuye al aumento de rendimiento, pero tiene un efecto secundario: para un mismo texto, el conteo de tokens sube entre 1,0 y 1,35 veces respecto a 4.6.

¿Qué provoca esto?

  • Procesos que iban al filo de max_tokens se cortan a medio hacer
  • Las estimaciones tipo tiktoken del lado cliente (facturación, longitud) se desalinean
  • El resultado de /v1/messages/count_tokens cambia entre 4.7 y 4.6
  • El mismo prompt sale ligeramente más caro y más lento

Cómo afrontarlo

# Before: en 4.6, buffer de 16k tokens para la salida
response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    messages=[...],
)

# After: deja margen con un factor aproximado de 1,35
response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=22000,  # 16000 * 1,35 ≒ 21600 → redondeo al alza
    messages=[...],
)

La buena noticia: en 4.7 la ventana de 1M de contexto está disponible con la tarifa estándar de la API (sin prima por contexto largo). Aunque suban un poco los tokens, compensa en el sentido de que ahora es más asumible la estrategia de «meterlo todo en la entrada y listo».

8. Breaking change 5: prefill retirado

Es un breaking change heredado de 4.6. El prefill del mensaje assistant, el truco de meter al final del array messages un {role: "assistant", content: "```json"} para forzar «una respuesta que empiece con JSON», devuelve error 400.

# Before: prefill para forzar salida JSON
client.messages.create(
    model="claude-opus-4-6",
    messages=[
        {"role": "user", "content": "Devuélveme la información del usuario en JSON"},
        {"role": "assistant", "content": "```json\n{"},  # prefill
    ],
)

# After: usar structured outputs
client.messages.create(
    model="claude-opus-4-7",
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "age": {"type": "integer"},
                },
                "required": ["name", "age"],
            },
        },
    },
    messages=[
        {"role": "user", "content": "Devuélveme la información del usuario en JSON"},
    ],
)

Hay tres alternativas al prefill.

  1. Structured outputs (output_config.format) — ata el formato de salida con un esquema JSON
  2. Indicarlo desde el system prompt: «devuelve solo JSON, sin markdown ni preámbulos»
  3. Recibirlo por tool use como una llamada a función (los argumentos llegan como JSON estructurado)
Los 5 breaking changes de Opus 4.7 en Before/After

9. Cómo elegir el nivel de esfuerzo (llega xhigh)

output_config.effort admite estos 5 niveles. En 4.7 llega xhigh como novedad.

effortPosicionamientoCasos de uso principales
maxPensar sin topeBenchmarks y problemas difíciles. Ojo al exceso de pensamiento y al rendimiento decreciente
xhigh (NUEVO)Óptimo para programación y agentesValor por defecto recomendado para Claude Code y tareas autónomas
highEquilibrioMínimo aceptable para tareas de alta carga intelectual
mediumPrioriza el costeAdmite algo menos de agudeza a cambio de precio y velocidad
lowTareas cortas rutinariasClasificación, formateo, resúmenes... cuando la latencia manda

Quienes en la era 4.6 indicaban budget_tokens a mano, en 4.7 con elegir effort ya es suficiente. Regla práctica:

  • Para agentes de programación (uso tipo Claude Code), empieza en xhigh
  • Para Q&A por chat o RAG, high es una apuesta segura
  • Para workers ligeros de etiquetado, extracción JSON o clasificación: medium o low
  • max solo para «quiero darle todo el pensamiento del mundo a una sola consulta»

10. Cómo encajar los cambios de comportamiento

Aunque a nivel de API sean compatibles, la forma en que reacciona al prompt cambia respecto a 4.6. Si pasas a producción sin saberlo, acabarás oyendo a las personas usuarias comentar que «ahora contesta más seco».

10.1 La longitud de la respuesta se adapta a la tarea

4.7 ajusta por sí mismo la longitud según la complejidad. Se acabó el «escribe en tres párrafos» impuesto como verbosidad fija. Dicho al revés, conviene quitar los «prompts de control de longitud» existentes y revisar el comportamiento.

10.2 Interpreta las instrucciones más al pie de la letra

Se nota sobre todo con effort bajo. Si pides «sé conciso», lo será de verdad; si pides «enumera 3», no añadirá un cuarto por libre. Es cómodo, pero se pierde la tendencia tipo 4.6 de «completar por ti las instrucciones ambiguas».

10.3 Tono más directo

Bajan las frases de validación («¡qué buena pregunta!»), los emojis decorativos y los saludos iniciales. Si quieres mantener un tono amable, indícalo desde el system prompt.

10.4 Actualizaciones de progreso integradas en el seguimiento de agentes

Si en tus agentes habías montado un andamiaje para imprimir «voy a hacer X», «estoy con X» a mano, en 4.7 lo da por sí mismo, así que puedes retirar ese scaffolding duplicado.

10.5 Menos subagentes y menos llamadas a herramientas

Por defecto, se reduce el spawn de subagentes y el número de llamadas a herramientas. Cuando cree que puede «resolverlo razonando», contestará sin tocar herramientas. Actualiza tus expectativas en el diseño del agente.

10.6 Salvaguardas de ciberseguridad en tiempo real

En tareas legítimas de seguridad ofensiva (red teaming, PoC de vulnerabilidades, etc.) puede haber rechazos según el contexto. Si la seguridad es un caso de uso real en producción, considera solicitar acceso al programa de verificación cyber de Anthropic.

10.7 Soporte de imágenes en alta resolución

Ahora se procesan imágenes de hasta 2576px sin reescalar. Pero cada imagen a resolución completa consume unas 3 veces más tokens. En cargas con muchas imágenes, elige entre (a) reajustar max_tokens o (b) hacer downsample antes de enviarlas.

A partir de aquí, cosas que «no hacen falta para que funcione, pero conviene hacer».

  1. Revisar max_tokens: con el nuevo tokenizador la salida también crece, así que parte del valor actual multiplicado por 1,2-1,35 y vuelve a probar
  2. Auditar la estimación de tokens en cliente: si tenías lógica propia de facturación o de longitud, migra a count_tokens o revisa los factores
  3. Introducir task_budgets (beta): para agentes. Añade la cabecera task-budgets-2026-03-13, mínimo 20k. Ojo: es un «tope orientativo», no un «tope duro»
  4. Ajustar max_tokens a 64k o más: si usas xhigh o max, recomendado ≥ 64k entre thinking y salida
  5. Downsample de imágenes: si no hace falta alta resolución, reduce antes de enviar para ahorrar tokens y coste

11.1 Ejemplo mínimo de task_budgets (SDK oficial, Python)

task_budgets es beta, así que hay que llamar al endpoint client.beta.messages.create y declarar el argumento betas. La forma de invocar es distinta a las funciones GA.

response = client.beta.messages.create(
    model="claude-opus-4-7",
    max_tokens=128000,
    output_config={
        "effort": "high",
        "task_budget": {"type": "tokens", "total": 128000},
    },
    messages=[
        {"role": "user", "content": "Review the codebase and propose a refactor plan."}
    ],
    betas=["task-budgets-2026-03-13"],
)

Puntos clave:

  • Mínimo 20.000 tokens. Por debajo no lo acepta
  • max_tokens es un tope duro por petición (no se le muestra al modelo); task_budget es un tope orientativo del bucle entero del agente (el modelo lo ve como una cuenta atrás)
  • Si quieres acotar el coste con mano firme, usa max_tokens; si buscas el equilibrio calidad-eficiencia, usa task_budget
  • En tareas abiertas donde prima la calidad sobre la velocidad, se recomienda no configurar task_budget (tiende a cortar antes de tiempo)

12. Migración desde Opus 4.5 / 4.1 o anteriores

Si saltas de 4.5 o 4.1 directamente a 4.7, además de lo anterior hay que tener en cuenta lo siguiente.

  • Eliminar los parámetros de muestreo: quien viene de Claude 3.x lleva usando temperature con normalidad. Fuera por completo
  • Limpiar cabeceras beta: cosas como effort-2025-11-24, fine-grained-tool-streaming-2025-05-14 o interleaved-thinking-2025-05-14 ya están integradas en core: quítalas
  • Cambiar de endpoint: migra las llamadas a client.beta.messages.create a client.messages.create
  • Migrar output_format → output_config.format: la clave ha cambiado de nombre
  • Parseo de argumentos de tools: a partir de 4.6 hay casos en que el escapado JSON se comporta distinto al pasado. Usa parsers formales (JSON.parse, json.loads) en vez de parseo de strings a pelo

Sobre las novedades del propio Opus 4.7, consulta también el artículo previo: Llega Claude Opus 4.7: novedades, benchmarks y precios.

13. Checklist de migración (todos los apartados)

Checklist de migración a Opus 4.7

Para que se pueda imprimir y repartir por el equipo, ponemos todos los puntos en plano.

13.1 Obligatorio (sin esto, error 400 o comportamiento roto)

  • ☐ Cambiar el nombre del modelo de claude-opus-4-6 a claude-opus-4-7
  • ☐ Eliminar temperature / top_p / top_k
  • ☐ Sustituir thinking: {type: "enabled", budget_tokens: N} por {type: "adaptive"} + output_config.effort
  • ☐ Eliminar el prefill del mensaje assistant y sustituirlo por structured outputs o system prompt
  • ☐ Si muestras el thinking en la UI, configurar explícitamente thinking.display: "summarized"

13.2 Tuning (optimización de coste y calidad)

  • ☐ Rebenchmarkear coste y latencia con el nuevo tokenizador
  • ☐ Reajustar max_tokens partiendo del factor 1,35
  • ☐ Retestar la lógica de estimación de tokens del lado cliente
  • ☐ Si mandas imágenes, reasignar tokens contando con la alta resolución
  • ☐ Si usas xhigh/max, configurar max_tokens ≥ 64k
  • ☐ Para casos de agente, valorar introducir task_budgets (beta)

13.3 Revisión de prompts y operativa

  • ☐ Comprobar con prompts reales la adaptación de longitud, la interpretación literal y el cambio de tono
  • ☐ Eliminar los prompts existentes de control de longitud y medir la línea base de nuevo
  • ☐ Si tu operativa es de seguridad y hay rechazos, solicitar acceso al programa de verificación cyber
  • ☐ Simplificar el scaffolding de agentes (salidas de progreso manuales, etc.)
  • ☐ Si vienes de 4.5 o anterior, limpiar también las cabeceras beta y migrar a client.messages.create

14. Herramientas de migración automática

Si usas Claude Code, puedes automatizar la reescritura mecánica con la skill de Claude API que ofrece Anthropic. Basta con invocarla desde Claude Code así:

/claude-api migrate

Migra todo el proyecto de Claude Opus 4.6 a 4.7.
- Cambia el nombre del modelo
- Elimina temperature / top_p / top_k
- Sustituye thinking: enabled por adaptive + effort: high
- Si queda algún prefill, cámbialo por structured outputs

La skill recorre el repo, identifica los ficheros que importan el SDK anthropic y propone cambios. Eso sí, los ajustes finos del prompt y el rebenchmark no se pueden automatizar: remátalo siempre con el checklist.

Preguntas frecuentes

P. ¿Funciona si solo cambio el nombre del modelo?

Si en tu código no usas ni temperature, ni top_p, ni top_k, ni thinking: {type: "enabled"}, ni prefill, sí. Pero con el nuevo tokenizador la salida puede cortarse a la mitad, así que conviene revisar al menos una vez max_tokens.

P. Si no incluyo el campo thinking, ¿4.7 contesta sin pensar?

Así es: por defecto, 4.7 va con thinking OFF. Igual que con el OFF por defecto en 4.6, pero los cambios de comportamiento asociados a adaptive solo se obtienen si activas explícitamente: añade thinking: {type: "adaptive"} y ajusta la intensidad con output_config.effort.

P. Si elimino temperature por completo, ¿saldrá siempre lo mismo?

No: Claude sigue generando respuestas de forma estocástica, así que con el mismo prompt habrá algo de variación. Si quieres respuestas muy consistentes, usa (a) salidas estructuradas (esquema JSON) para atar el formato o (b) instrucciones explícitas en el prompt del tipo «ante la misma entrada, devuelve lo mismo» o «los puntos, siempre en el mismo orden».

P. ¿task_budgets es un tope duro?

No es un tope duro, es un «tope orientativo» para el modelo. No hay garantía de que el consumo se mantenga dentro. Si quieres acotar coste de verdad, combínalo como siempre con max_tokens y con lógica de timeout o aborto en tu aplicación. Para la beta hace falta la cabecera task-budgets-2026-03-13.

P. ¿Se comporta igual desde Claude Code que tirando directo a la API?

A nivel de spec de API, sí. Pero Claude Code trae valores por defecto recomendados (xhigh pegado a «valor por defecto para programación») y hay skills que configuran task_budgets por detrás. Si notas diferencias, lo más rápido es loguear el JSON de la petición y compararlo.

P. En apps con muchas imágenes el consumo se dispara, ¿qué hago?

(1) Baja la resolución por debajo de 2576px antes de enviar; (2) combina varias imágenes en una sola hoja; (3) haz el OCR de la imagen en tu app y envía solo el texto. Reserva el envío en resolución completa para casos obligatorios (imagen médica, planos, etc.) y ahí sí aumenta max_tokens: ese suele ser el equilibrio práctico.

P. Uso Bedrock / Vertex AI, ¿el procedimiento es el mismo?

Los cambios de parámetros son básicamente iguales. Otra cosa es el identificador de modelo (por ejemplo, en Bedrock, la familia anthropic.claude-opus-4-7) y el calendario de disponibilidad en cada nube: guíate por los anuncios de cada plataforma. La estructura de thinking y output_config es común a todas.

P. ¿Cuánto puedo delegar en la migración automática?

La skill de Claude API (/claude-api migrate) es muy buena con la parte mecánica: «cambiar el nombre del modelo», «eliminar parámetros de muestreo», «reescribir extended thinking». Pero el tono de prompts, el control de longitud y el rebenchmark siguen requiriendo criterio humano. Tras la migración automática, lo realista es revisar una a una las líneas del checklist de este artículo.

Este artículo se basa en la guía oficial de migración a Claude Opus 4.7 de Anthropic (a fecha de abril de 2026). La spec de la API puede cambiar, así que antes de pasar a producción consulta siempre la documentación oficial.