Cómo usar la API Claude Opus 4.7

Lena está aquí. Revisé la documentación oficial y los materiales de migración tras el lanzamiento del 16 de abril, esperando que la mayoría me resultara familiar. En su mayoría lo es. Pero hay suficientes cambios estructurales — tres cambios rotos en la API, un nuevo sistema de esfuerzo, un tokenizador que cambia el número de tokens — como para que tratar esto como un simple intercambio de ID de modelo sería un error.

Esto es lo que encontré cuando lo resolví.

Lo que incluye la API Claude Opus 4.7

ID de modelo, ventana de contexto, límites de salida y herramientas

Primero lo básico, porque merece la pena decirlo claramente.

ID de modelo: claude-opus-4-7. Según resumen oficial de modelos de Anthropic, soporta una ventana de contexto de 1M token a precios estándar de API sin premium de contexto largo, y 128k tokens de salida máximo en la API síncrona de Mensajes. En la API de Mensajes por Lotes, Opus 4.7 puede alcanzar hasta 300k tokens de salida usando el encabezado beta output-300k-2026-03-24.

El conjunto completo de herramientas se mantiene de Opus 4.6: bash, ejecución de código, uso del ordenador, editor de texto, búsqueda web, búsqueda web, conector MCP y herramientas de memoria están todos disponibles desde el primer día. El soporte para Vision está presente en todos los ámbitos — y se actualiza de forma significativa, a lo que volveré.

Disponible en la API de Claude, Amazon Bedrock, Google Cloud Vertex AI y Microsoft Foundry — y se despliega en GitHub Copilot para usuarios de Copilot Pro+, Business y Enterprise. Precios: $5 por millón de tokens de entrada, $25 por millón de tokens de salida — sin cambios respecto a Opus 4.6.

Qué hay de nuevo vs Opus 4.6

Tres cosas son realmente nuevas en la superficie de la API:

El pensamiento adaptativo es el único modo de pensar. El patrón antiguo de {"type": "enabled", "budget_tokens": N} ha desaparecido. Enviarlo ahora devuelve un error 400. Opus 4.7 usa {"type": "adaptive"} — el modelo decide dinámicamente cuánto razonar según la complejidad de la tarea. El pensamiento adaptativo está desactivado por defecto; debes activarlo explícitamente si quieres que el modelo piense en absoluto.

El nivel de esfuerzo xhigh****. Esto se sitúa entre high y max, y es el nuevo punto de partida recomendado para la codificación y los casos de uso agentes. El valor predeterminado de la API es high; xhigh configuras explícitamente a través de output_config. Mostraré la estructura a continuación.

Presupuestos de tareas (beta). Un nuevo mecanismo que proporciona al modelo un objetivo de token consultivo para un ciclo agente completo: pensamiento, llamadas a herramientas, resultados de herramientas y salida final combinados. El modelo ve una cuenta regresiva en curso y la usa para priorizar el trabajo y finalizar de manera ordenada a medida que se agota el presupuesto.

También se eliminó: parámetros de muestreo no predeterminados. Establecer temperature, top_p o top_k a cualquier valor que no sea el predeterminado ahora devuelve un error 400. Si estabas usando temperature=0 para determinismo, ten en cuenta que nunca garantizó resultados idénticos de todos modos: la guía de migración recomienda omitir estos parámetros por completo.

Configuración mínima de la API Claude Opus 4.7

Estructura de la primera solicitud

La solicitud mínima funcional para Opus 4.7 es la siguiente:

import anthropic

client = anthropic.Anthropic()

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {"role": "user", "content": "Explain the tradeoffs between BFS and DFS for a graph with cycles."}
    ]
)

print(message.content[0].text)

Esto se ejecuta sin que esté habilitado el pensamiento. El modelo responderá directamente. Para la mayoría de las tareas, este es el punto de partida correcto: agrega complejidad solo cuando tengas una razón para hacerlo.

Elección de niveles de pensamiento y esfuerzo adaptativos

Cuando quieras que el modelo razone antes de responder, agrega la configuración de pensamiento y establece el esfuerzo explícitamente:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16384,
    thinking={"type": "adaptive"},
    output_config={"effort": "xhigh"},
    messages=[
        {"role": "user", "content": "Review this pull request for security vulnerabilities..."}
    ]
)

Algunas cosas que vale la pena saber sobre los niveles de esfuerzo, según la documentación oficial de esfuerzo de Anthropic:

• high es el valor predeterminado de la API. Úsalo para razonamiento complejo, análisis matizado o problemas de codificación difíciles donde la calidad sea la prioridad.
• xhigh es el nuevo nivel, recomendado para tareas de codificación y agenticas. Claude Code ha aumentado su valor predeterminado a xhigh en todos los planes.
• max proporciona el razonamiento más profundo sin restricción de tokens. Se aplica solo a la sesión actual (a menos que se establezca mediante variable de entorno) y no persiste.
• low y medium intercambian precisión por velocidad y costo. Útiles para clasificación o encaminamiento de alto volumen donde las diferencias marginales en calidad no justifican el gasto.

Un detalle que releí dos veces: Opus 4.7 respeta los niveles de esfuerzo más estrictamente que Opus 4.6, especialmente en low y medium. Si observas un razonamiento superficial en una tarea compleja, el movimiento correcto es aumentar el esfuerzo, no agregar escalonamientos de prompt alrededor de él. La documentación es explícita al respecto.

Al ejecutar en xhigh o max, establece max_tokens al menos en 64k para darle al modelo espacio para pensar y actuar a través de subagentes y llamadas a herramientas. Comenzar en 64k y ajustar a partir de ahí es la propia recomendación de Anthropic.

Características Importantes para Agentes de Larga Duración

Visión de Alta Resolución, Esfuerzo Elevado y Flujos de Trabajo con Herramientas

La mejora de visión es la ganancia de capacidad más concreta para los desarrolladores de agentes. Como se documenta en el análisis de referencia de Vellum AI sobre Opus 4.7, OSWorld-Verified (uso de computadora) subió del 72.7% en Opus 4.6 al 78.0%, una ganancia de 5 puntos que, junto con la mejora de resolución, cambia significativamente la economía de la automatización de interfaces.

Opus 4.7 es el primer modelo Claude con soporte de imágenes de alta resolución: la resolución máxima aumentó de 1,568 píxeles (~1.15MP) a 2,576 píxeles (~3.75MP) en el borde largo. Eso es más del triple del presupuesto de píxeles. Para agentes de uso de computadora que leen interfaces densas, flujos de trabajo basados en capturas de pantalla o tuberías de comprensión de documentos, esto es un cambio significativo. Críticamente, las coordenadas ahora se asignan 1:1 con los píxeles reales de la imagen: se elimina la matemática del factor de escala que antes era necesaria para la extracción de coordenadas.

Visión en una solicitud:

message = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "image",
                    "source": {"type": "url", "url": "https://example.com/diagram.png"}
                },
                {"type": "text", "text": "List every service shown and the connections between them."}
            ]
        }
    ]
)

Si la resolución extra no es necesaria para una tarea determinada, reduce el tamaño de las imágenes antes de enviarlas: las imágenes de alta resolución producen más tokens, y para cargas de trabajo sensibles al costo, esto se acumula.

Para bucles de agentes con muchas herramientas, aumentar el esfuerzo incrementa la frecuencia y profundidad de las llamadas a herramientas. La relación es directa: menor esfuerzo → menos llamadas a herramientas y cadenas de razonamiento más superficiales; mayor esfuerzo → interacción con herramientas más completa. Esto también se puede controlar mediante prompts, pero el parámetro de esfuerzo es la palanca más limpia.

Controles de Costo y Latencia para Uso en Producción

Presupuestos de tarea son el nuevo mecanismo para controlar el gasto en bucles de agentes largos. Actívalos con el encabezado beta:

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"]
)

El modelo ve la cuenta regresiva y la usa para priorizar y finalizar de manera ordenada. Sin un presupuesto de tarea, el comportamiento predeterminado es "gastar según se necesite": en una tarea compleja de agente en xhigh, eso puede significar significativamente más tokens de salida de los que esperarías de una solicitud de un solo turno.

Para cargas de trabajo asíncronas —ejecuciones de evaluación, resúmenes nocturnos, análisis por lotes— la API Batch ofrece un 50% de descuento y elimina la presión de límite de velocidad del tráfico en tiempo real. La caché de prompts sigue estando disponible y puede reducir el costo de entradas repetidas hasta en un 90% para cargas de trabajo con prompts de sistema estables o prefijos estáticos grandes.

Errores de Migración a Evitar

Suponer que los Prompts de 4.6 se Transfieren Sin Cambios

Este es el que sigo viendo aparecer.

Opus 4.7 sigue las instrucciones más literalmente que Opus 4.6. Ya no lee entre líneas ni generaliza silenciosamente de un caso a otro. Las expresiones suaves — "intentar", "si es posible", "aproximadamente" — ahora llevan más peso real. Los prompts que dependían de la flexibilidad interpretativa de 4.6 a veces se comportarán de manera diferente, y no siempre de la forma que esperarías.

Los tres cambios importantes de la API requieren actualizaciones de código, no solo ediciones de prompts:

1. Reemplazar thinking: {type: "enabled", budget_tokens: N} con thinking: {type: "adaptive"}
2. Eliminar temperature, top_p, top_k de las solicitudes por completo
3. Auditar max_tokens — el nuevo tokenizador asigna el mismo texto a hasta 1,35× más tokens, por lo que los límites existentes pueden cortar respuestas que antes cabían

Sobre el tono: Opus 4.7 es más directo y con opiniones que 4.6 — menos emojis, menos frases orientadas a la validación. Si tu producto depende de una voz específica calibrada al estilo más cálido de 4.6, reevalúa tus prompts de estilo con respecto a la nueva línea base antes de pasar a producción.

El anuncio de lanzamiento de Opus 4.7 de Anthropic enlaza directamente con la lista completa de migración, y los usuarios de Claude Code pueden ejecutar /claude-api migrate para automatizar el cambio de ID del modelo y los cambios de parámetros importantes a lo largo de un código base.

Tratar el contexto largo como memoria persistente

Me detuve aquí cuando leí esto en la documentación, porque es fácil confundir ambos conceptos.

Una ventana de contexto de 1 millón de tokens no es memoria persistente. Significa que puedes colocar 1 millón de tokens en una sola solicitud. Cuando esa solicitud termina — cuando la sesión se cierra, cuando el agente falla, cuando comienza una nueva conversación — ese contexto desaparece. La siguiente solicitud comienza desde cero.

Opus 4.7 sí incluye memoria mejorada basada en el sistema de archivos: el modelo lee y escribe en archivos de notas a lo largo de trabajos de varias sesiones, con un comportamiento notablemente más confiable para agentes que usan este patrón. Pero eso es una herramienta que debes configurar. No ocurre automáticamente por una ventana de contexto larga.

La distinción es importante para cualquiera que construya agentes destinados a "recordar" cosas de una sesión a otra. La ventana de 1 millón de tokens ayuda dentro de una sesión. La memoria entre sesiones requiere arquitectura explícita.

Lo que la API aún no resuelve

Reutilización de capacidades y historial de reparación validado

Esta es la parte que me resulta más difícil de encajar de manera ordenada en una guía de API, pero creo que vale la pena mencionarlo.

Cuando Opus 4.7 detecta un fallo lógico durante la fase de planificación —que los materiales de la versión describen como una capacidad genuina— ese razonamiento ocurre dentro de la sesión. El hecho de que detectara el fallo y cómo lo corrigió no se guarda automáticamente como un patrón reutilizable para la siguiente ejecución. La próxima vez que aparezca la misma clase de problema, el modelo razona desde cero.

Según un artículo de investigación sobre la fiabilidad de agentes de IA publicado a principios de 2026, la mayoría de los modelos se evalúan según la precisión promedio y no según la consistencia entre ejecuciones —lo que significa que un modelo puede obtener buenos resultados en los benchmarks mientras aún falla de manera impredecible en la misma clase de tarea en diferentes momentos. Opus 4.7 mejora la base de Opus 4.6. Eso es real. Pero la corrección dentro de la sesión y la herencia de capacidades entre sesiones son problemas diferentes, y la API resuelve el primero, no el segundo.

Para los desarrolladores que ejecutan agentes en producción, esto significa que el trabajo de ingeniería para construir sistemas confiables —herramientas de evaluación, documentación de reparación, monitoreo— todavía se encuentra fuera del propio modelo. La API te proporciona un modelo más capaz. Lo que hagas con esa capacidad a lo largo del tiempo sigue dependiendo de tu arquitectura.

Preguntas frecuentes

P: ¿Cuál es el ID de modelo correcto para Opus 4.7?

R: claude-opus-4-7. Esta es la cadena de modelo estable para llamadas API a través de Claude API, Amazon Bedrock, Google Cloud Vertex AI y Microsoft Foundry.

P: ¿Está activado el pensamiento adaptativo por defecto?

R: No. El pensamiento adaptativo está desactivado por defecto en Opus 4.7. Debes establecer thinking: {"type": "adaptive"} explícitamente para activarlo. Las solicitudes sin el campo thinking se ejecutan sin pensar.

P: ¿Qué sucede si envío temperature o budget_tokens?

R: Ambos devuelven un error 400 en Opus 4.7. Elimina temperature, top_p y top_k de todas las solicitudes. Sustituye budget_tokens por output_config: {"effort": "..."} y thinking: {"type": "adaptive"}.

P: ¿Cuándo debo usar xhigh vs high effort?

R: Usa xhigh como punto de partida para tareas de programación y agentes —ahora es el predeterminado en Claude Code en todos los planes. Usa high para la mayoría de las tareas que requieren inteligencia. Reduce a medium o low cuando la latencia o el costo sean más importantes que la profundidad del razonamiento. Si observas resultados superficiales en una tarea compleja con un nivel inferior, aumenta el esfuerzo en lugar de añadir estructuras al prompt.

P: ¿Significa la ventana de contexto de 1M que el agente recuerda cosas entre sesiones?

A: No. La ventana de contexto se aplica dentro de una sola solicitud. Cuando una sesión termina, ese contexto se pierde. La memoria de múltiples sesiones requiere herramientas explícitas: memoria basada en archivos, almacenes externos o arquitectura similar.

Publicaciones Anteriores

• 👉 Si quieres entender por qué las actualizaciones del modelo no reducen realmente el costo del sistema: Claude Opus 4.7 vs Fiabilidad: Por qué los mejores modelos no solucionan los sistemas de agentes
• 👉 Si estás tratando de entender dónde se oculta el costo real más allá del precio por token: Ingeniería de Harness: La capa oculta detrás del costo y la fiabilidad de los agentes
• 👉 Si estás evaluando cuándo Opus realmente vale la prima sobre Sonnet: Agentes gestionados por Claude: Cuándo deberías usar Opus en lugar de Sonnet
• 👉 Si estás construyendo sistemas de agentes y necesitas controlar el comportamiento + el gasto juntos: Superpoderes de agente: Restricciones de comportamiento como capa de control de costos
• 👉 Si estás pensando en escalar el uso de agentes más allá de flujos de trabajo individuales: Mejores servidores MCP para Claude Code: Casos de uso en producción reales