Cómo usar la API de Claude Sonnet 5.5: Primera llamada, Esfuerzo, Pensamiento, Herramientas y Streaming

Para usar la API de Claude Sonnet 5.5, envía una solicitud POST a https://api.anthropic.com/v1/messages con "model": "claude-sonnet-5-5", tu clave en el encabezado x-api-key, y anthropic-version: 2023-06-01. Cuesta $2 por millón de tokens de entrada y $10 por millón de tokens de salida, lee hasta 1M de tokens de contexto, escribe hasta 128K, ejecuta el pensamiento adaptativo por defecto y utiliza high (alto) como nivel de esfuerzo predeterminado.

Anthropic lanzó Sonnet 5.5 el 28 de septiembre de 2026 (la guía qué es Claude Sonnet 5.5 cubre especificaciones y benchmarks). Esta guía explica una primera llamada en curl, Python y TypeScript, luego el esfuerzo, el pensamiento, las herramientas, el streaming, las negativas y los límites de tasa. ¿Estás migrando código de Sonnet 5? La guía Sonnet 5.5 vs Sonnet 5 tiene cada cambio importante con JSON de antes/después. Puedes enviar cada solicitud a continuación desde Apidog y guardarla como una prueba con aserciones.

API de Claude Sonnet 5.5 de un vistazo

Fuentes: la página del modelo Sonnet 5.5 y la guía de migración.

Ejemplo de API de Claude Sonnet 5.5: tu primera llamada

Crea una clave (la guía de claves API de Anthropic lo explica) y expórtala como ANTHROPIC_API_KEY en lugar de codificarla. Luego envía esto:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 4096,
    "output_config": {"effort": "medium"},
    "messages": [{"role": "user", "content": "Explain idempotency keys in two sentences."}]
  }'

El SDK de Python lee ANTHROPIC_API_KEY del entorno:

import anthropic

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
)
print(response.stop_reason)
for block in response.content:
    if block.type == "text":
        print(block.text)

TypeScript funciona de la misma manera:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const response = await client.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 4096,
  output_config: { effort: "medium" },
  messages: [{ role: "user", content: "Explain idempotency keys in two sentences." }],
});
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Lee los bloques de contenido por type. El pensamiento está activado por defecto, por lo que una respuesta puede comenzar con un bloque thinking, y el código que lee content[0].text se romperá. Los tokens de pensamiento se facturan como salida y cuentan para max_tokens incluso cuando su texto está oculto, así que deja un margen por encima de la respuesta que esperas.

Elige un nivel de esfuerzo

El esfuerzo, configurado en output_config.effort, es tu principal control de coste y calidad. Anthropic recalibró los niveles para Sonnet 5.5, por lo que una configuración de Sonnet 5 no se traslada; realiza una nueva evaluación en tus propios `evals`. La guía de prompting sugiere estos puntos de partida:

La horquilla es amplia. En las propias ejecuciones de Terminal-Bench 4.0 de Anthropic, Sonnet 5.5 obtuvo un 43.0% en high por $1.94 por intento y un 70.6% en max por $12.54. El desglose de precios de Sonnet 5.5 detalla el coste por solicitud.

Planifica tres comportamientos. Desde medium (medio) hacia arriba, el modelo piensa antes de casi cada respuesta, incluso un saludo, y pedirle que piense menos no es fiable: en su lugar, baja el esfuerzo. En low (bajo) y medium (medio), tiende a intervenir temprano en tareas agénticas largas. Y cambiar el esfuerzo de nivel superior entre solicitudes invalida la caché de prompts. Para cambiar de nivel a mitad de conversación y mantener la caché, usa el esfuerzo por mensaje (beta, encabezado anthropic-beta: mid-conversation-output-config-2026-07-01): añade un mensaje role: "system" con content vacío y el nuevo output_config.effort.

Controla el pensamiento: adaptativo o entre_herramientas

Omite el campo thinking y Sonnet 5.5 ejecutará el pensamiento adaptativo. Rechaza {"type": "disabled"} con un error 400. Para desactivar el pensamiento inicial, envía between_tools, la configuración más baja:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 16000,
  "thinking": {"type": "between_tools"},
  "output_config": {"effort": "high"},
  "messages": [{"role": "user", "content": "..."}]
}

Reglas para between_tools de Sonnet 5.5:

• Funciona solo en low (bajo), medium (medio) o high (alto). En xhigh (muy alto) o max (máximo) devuelve 400.
• No acepta ningún otro campo. Añadir display, budget_tokens o block_binding devuelve 400.
• No necesita encabezado beta y funciona en todas las plataformas.
• El esfuerzo no puede cambiar a mitad de conversación mientras está configurado.
• Las versiones del SDK que no lo definen fallan en la comprobación de tipos, así que actualiza tu SDK.

Bajo el pensamiento adaptativo, display decide qué contienen los bloques de pensamiento. El valor predeterminado, omitted (omitido), devuelve cada bloque thinking con un campo thinking vacío más una signature. summarized (resumido) devuelve resúmenes legibles. updates (actualizaciones) (beta, encabezado thinking-display-updates-2026-08-18) devuelve solo las actualizaciones de progreso como texto.

Las actualizaciones de progreso son el cambio con más probabilidades de confundir a una interfaz de usuario. Sonnet 5.5 coloca notas de más de una o dos frases, escritas entre llamadas a herramientas, en sus propios bloques thinking en lugar de en text. Bajo el valor predeterminado omitted (omitido), esos bloques están vacíos, por lo que una interfaz de agente que solía narrar sus pasos se queda en silencio. Configura display: "updates" o "summarized", o ejecuta between_tools, que devuelve las notas con texto. Renderiza cada bloque thinking no vacío antes del bloque tool_use que le sigue. Pedir razonamiento en el texto de respuesta provoca una negativa reasoning_extraction, así que lee estos bloques en su lugar.

Usa herramientas sin tool_choice forzado

El uso forzado de herramientas ha desaparecido. Un tool_choice de {"type": "any"} o {"type": "tool", ...} devuelve un error 400 con este mensaje, también en el endpoint de conteo de tokens:

tool_choice: type "tool" and "any" are not supported for this model.

Envía auto, marca la herramienta strict: true para que su entrada coincida con el esquema, e indica al modelo en el prompt cuándo debe llamarla:

{
  "model": "claude-sonnet-5-5",
  "max_tokens": 1024,
  "tools": [{
    "name": "get_weather",
    "description": "Get the current weather for a city",
    "input_schema": {
      "type": "object",
      "properties": {"location": {"type": "string"}},
      "required": ["location"],
      "additionalProperties": false
    },
    "strict": true
  }],
  "tool_choice": {"type": "auto"},
  "messages": [{"role": "user", "content": "What's the weather in Paris? Use the get_weather tool."}]
}

Una solicitud puede llevar como máximo 20 herramientas estrictas, y los esquemas estrictos necesitan additionalProperties: false en cada objeto. En Amazon Bedrock, las herramientas estrictas no están disponibles para Sonnet 5.5: envía auto sin strict y valida la entrada en tu código.

Dos detalles del bucle son importantes. Pasa cada bloque thinking sin cambios junto con su bloque tool_use, incluyendo los vacíos. Y espera algún desliz ocasional en el uso de mayúsculas/minúsculas, como bash para una herramienta declarada como Bash. La guía de prompting sugiere aceptar coincidencias inequívocas o devolver un tool_result con is_error: true que indique el nombre exacto.

Transmite respuestas

Añade "stream": true al cuerpo, o usa el asistente de stream del SDK. Para la codificación agéntica, la guía de prompting recomienda max_tokens de 128.000 con streaming:

with client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=128000,
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Review this diff for bugs: ..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta" and event.delta.type == "text_delta":
            print(event.delta.text, end="", flush=True)
    final = stream.get_final_message()

Los eventos enviados por el servidor llegan como message_start, luego content_block_start, content_block_delta y content_block_stop para cada bloque, luego message_delta (llevando stop_reason) y message_stop. Bajo omitted (omitido), un bloque de pensamiento transmite un thinking_delta vacío y un signature_delta, luego comienza el texto. Espera una pausa de varios segundos antes de que se abra un bloque de actualización de progreso.

stream.get_final_message() (TypeScript: stream.finalMessage()) reconstruye bloques completos con sus firmas. Añade ese contenido al historial como el turno del asistente, sin cambios, y mantén el historial solo de adición. Sonnet 5.5 firma cada bloque de pensamiento a lo largo de la conversación anterior, por lo que en cuentas creadas a partir del 31 de agosto de 2026 (00:00 UTC), reproducir un bloque después de editar el historial anterior devuelve 400. Los bloques también están vinculados a la cuenta que los produjo.

Gestionar negativas y mecanismos de recuperación

Una negativa no es un error. Obtienes un HTTP 200 con stop_reason: "refusal" y un objeto stop_details cuya category es cyber, bio, frontier_llm, reasoning_extraction o general_harms, además de una explanation. Muestra la explicación en lugar de analizarla; su redacción no es estable. Ramifica en stop_reason antes de leer content.

El mecanismo de recuperación del lado del servidor es opcional. Añade "fallbacks": "default" y el encabezado anthropic-beta: server-side-fallback-2026-07-01 (beta, solo API de Claude), y la API reintenta las negativas de cyber y frontier_llm en Sonnet 5. Las otras tres categorías no se reintentan. El campo model de la respuesta nombra el modelo que la sirvió, y un bloque de contenido fallback marca la transferencia.

Límites de tasa

Sonnet 5.5 tiene su propio límite de tasa, separado del de Sonnet 5. La página de límites de tasa enumera cuatro niveles:

Para la gestión de errores 429 y retroceso exponencial, consulta la guía de límite de tasa excedido.

Prueba la API de Claude Sonnet 5.5 en Apidog

Las solicitudes guardadas hacen que las comparaciones de esfuerzo y la depuración de streams sean repetibles. Aquí está la configuración en Apidog:

1. Crea un entorno y añade ANTHROPIC_API_KEY como variable. Haz referencia a ella como {{ANTHROPIC_API_KEY}} en el encabezado x-api-key, junto a anthropic-version y content-type.
2. Crea una solicitud POST a https://api.anthropic.com/v1/messages, pega el cuerpo de la primera llamada y guárdala.
3. Añade aserciones: el estado es 200, $.stop_reason es igual a end_turn, $.usage.output_tokens es mayor que 0, y $.content[*].type contiene text. Una negativa ahora fallará la prueba en lugar de pasar silenciosamente.
4. Duplica la solicitud con "stream": true. Apidog muestra la respuesta text/event-stream evento por evento, para que puedas ver llegar en orden el thinking_delta vacío, el signature_delta y el texto.
5. Clónala de nuevo con "model": "claude-sonnet-5" y guarda el par en una carpeta: mismo prompt, dos modelos, usage uno al lado del otro.

Para patrones más amplios, consulta pruebas de aplicaciones LLM y pruebas de APIs de agentes de IA.

Preguntas Frecuentes

¿Cuál es el ID del modelo Claude Sonnet 5.5? claude-sonnet-5-5, sin sufijo de fecha, en la API de Claude, Google Cloud, Microsoft Foundry y Claude Platform en AWS. En Amazon Bedrock es anthropic.claude-sonnet-5-5.

¿Puedo desactivar el pensamiento por completo? No. disabled devuelve 400. between_tools es la configuración más baja: sin pensamiento inicial, con esfuerzo low (bajo), medium (medio) o high (alto).

¿Por qué mi solicitud de Sonnet 5 devuelve 400 en Sonnet 5.5? Primero, verifica thinking.type: "disabled" y un tool_choice forzado. La guía Sonnet 5.5 vs Sonnet 5 cubre los cinco cambios importantes y sus soluciones.

¿Existe una API gratuita de Claude Sonnet 5.5? La API de Anthropic es de prepago, y ninguna página oficial enumera un crédito de registro gratuito. Un plan de chat de Claude tampoco incluye acceso a la API. La guía de API gratuita cubre programas de crédito y la ruta de pago más económica.

Siguiente paso

Envía la solicitud de la primera llamada en medium (medio), luego vuelve a ejecutarla en high (alto) y compara usage.output_tokens y la calidad de la respuesta en un prompt de tu propia carga de trabajo. Descarga Apidog para guardar ambas ejecuciones con aserciones. Si prefieres trabajar desde la terminal, consulta Claude Sonnet 5.5 en Claude Code.