Cómo utilizar la API de Claude Sonnet 5.5

TL;DR

Claude Sonnet 5.5 es un modelo rápido para flujos de trabajo bien delimitados de programación, documentos y uso de herramientas. Anthropic informa una generación más de un 30% más veloz que Sonnet 5 con las mismas tarifas estándar por token. Empieza con una clave de CometAPI, el ID de modelo claude-sonnet-5-5 y una solicitud pequeña en Messages o Chat Completions. Los agentes existentes deben volver a probar el pensamiento, la selección de herramientas y la reproducción del historial antes del despliegue.

Puntos clave

• Usa Claude Sonnet 5.5 y ajusta el formato de la solicitud al endpoint.
• Empieza con una única solicitud corta antes de añadir imágenes, herramientas o contexto extenso.
• Usa Messages para controles específicos de Claude; usa Chat Completions para una aplicación que ya emplee un SDK de OpenAI.
• Revisa los cambios en el pensamiento y la selección de herramientas antes de migrar bucles de agentes existentes.
• Compara calidad de tareas aceptadas, latencia, uso de tokens y aciertos de caché antes de aumentar el tráfico.

¿Qué es Claude Sonnet 5.5?

Claude Sonnet 5.5 API es la interfaz programática del modelo Sonnet 5.5 de Anthropic. Está diseñado para tareas como desarrollo de software, análisis de repositorios, automatización de soporte al cliente, procesamiento de documentos, comprensión de imágenes, agentes que usan herramientas y flujos de trabajo profesionales estructurados.

Anthropic posiciona Sonnet 5.5 como un complemento más rápido y de menor costo de Opus 5.5, el segundo modelo de la familia Claude 5.5, optimizado para programación bien delimitada, corrección de errores, creación de documentos y diapositivas, y tareas profesionales cotidianas. Los desarrolladores pueden acceder a la API de Claude Sonnet 5.5 en CometAPI usando claude-sonnet-5-5.

Anthropic confirma una ventana de contexto de 1M tokens y un límite de salida sincrónica de 128K. La salida por lotes puede alcanzar 300K tokens solo mediante Message Batches con la cabecera beta output-300k-2026-03-24. Debe verificarse por separado la compatibilidad de funciones del gateway respecto a la compatibilidad a nivel de modelo.

¿Cómo rinde Claude Sonnet 5.5 en benchmarks oficiales?

La comparación compacta a continuación ayuda a identificar cargas de trabajo que conviene evaluar antes de adoptar la API. Los resultados de benchmarks no sustituyen las pruebas con tus propios prompts y bucles de herramientas.

Los resultados de benchmarks y notas de evaluación de Anthropic sustentan esta comparación. El resultado de Terminal-Bench de Opus 5.5 usa esfuerzo Xhigh; FrontierCode reporta resultados separados Max y Xhigh para Sonnet 5.5; OSWorld es una evaluación parcial. GDPval-AA y AA-Briefcase fueron ejecutados por Artificial Analysis en un despliegue previo al lanzamiento de Claude Platform con un error de salida estructurada que probablemente subestimó la puntuación de Sonnet 5.5; Anthropic indica que el error ya se corrigió. Estos resultados deben guiar las pruebas de cargas de trabajo, no garantizar resultados de producción. Humanity’s Last Exam usa herramientas; Chartography no. Las filas nuevas usan las puntuaciones publicadas por Anthropic. Se mantiene la imagen original a continuación; la tabla ampliada incluye tres evaluaciones adicionales.

Comparativa oficial de benchmarks de Claude Sonnet 5.5

¿Qué cambió en la API de Claude Sonnet 5.5 respecto a Sonnet 5?

Los cambios de migración en pensamiento, elección de herramientas y reproducción del historial afectan los bucles de agentes existentes. La tabla resume estos cambios operativos; no es un inventario completo de funciones.

Cambios disruptivos a revisar

Verifica los cinco cambios disruptivos: reemplaza el pensamiento disabled por between_tools; elimina la elección forzada de herramienta; conserva bloques de pensamiento compatibles y un historial de conversación sin cambios; migra de computer_20251124 a computer_toolset_20260801 en la Claude API y Google Cloud; y reemplaza asociaciones de asesores no compatibles. Amazon Bedrock aún acepta computer_20251124. Los asesores no compatibles incluyen Opus 4.8, 4.7, 4.6, Sonnet 5, Sonnet 4.6 y Haiku 5.5. Opus 5.5 es un reemplazo compatible. Lee los bloques de respuesta por tipo. Verifica la compatibilidad de la plataforma y del gateway antes del despliegue. Guía de migración oficial.

Capacidades adicionales y cambios de flujo de trabajo

Usa la guía oficial de funciones para revisar avances, esfuerzo por mensaje y controles a mitad de conversación. Confirma el soporte del gateway antes de habilitar funciones beta.

¿Qué necesitas antes de usar la API de Claude Sonnet 5.5?

• Una cuenta de CometAPI, clave de API, acceso al modelo y saldo de facturación disponible.
• Una terminal con cURL; Python y pip o Node.js y npm para ejemplos de SDK.
• Un endpoint seleccionado: /v1/messages o /v1/chat/completions.
• COMETAPI_KEY almacenada en el entorno del servidor, además de acceso de red a https://api.cometapi.com.
• Un prompt de prueba corto y una verificación clara de salida utilizable, estado de finalización y uso de tokens.

¿Cómo accedes a la API de Claude Sonnet 5.5 a través de CometAPI?

Elige la API de Messages cuando el comportamiento de Claude sea importante. Elige la API compatible con OpenAI cuando tu aplicación ya alterne entre Claude, GPT, Gemini, DeepSeek u otros modelos a través de la misma capa de abstracción.

Paso 1: Almacena la clave de API

Crea una clave en la consola de claves de API de CometAPI, luego configúrala en tu entorno de ejecución.

Configurar la clave de CometAPI en un shell POSIX

export COMETAPI_KEY="YOUR_COMETAPI_KEY"

Configurar la clave de CometAPI en PowerShell

$env:COMETAPI_KEY="YOUR_COMETAPI_KEY"

Paso 2: Realiza la primera solicitud a Messages

Enviar la primera solicitud Messages compatible con Anthropic

curl https://api.cometapi.com/v1/messages \
  -H "Authorization: Bearer $COMETAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 2048,
    "messages": [{"role": "user", "content": "Explain exponential backoff in three bullet points."}]
  }'

Inspecciona los bloques de contenido, stop_reason y usage antes de añadir más controles. La sintaxis de cURL anterior usa un shell POSIX.

Paso 3: Usa el SDK de Python de Anthropic

Instalar el SDK de Python de Anthropic

pip install anthropic

Leer bloques de texto y usage con el SDK de Anthropic

import os
import anthropic

anthropic_client = anthropic.Anthropic(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com",
)

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Review this migration plan and list the three biggest risks."}],
)

for block in response.content:
    if block.type == "text":
        print(block.text)
print("Completion:", response.stop_reason)
print("Usage:", response.usage)

Paso 4: Usa el SDK de Python de OpenAI

Instalar el SDK de OpenAI para Python

pip install openai

Llamar a Sonnet 5.5 mediante Chat Completions compatible con OpenAI

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

response = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "system",
            "content": "You are a concise software engineering assistant."
        },
        {
            "role": "user",
            "content": "Review this function and identify the highest-risk bug."
        }
    ],
)

print(response.choices[0].message.content)

Este enfoque es útil cuando una aplicación ya usa la interfaz del SDK de OpenAI. Una integración básica de texto puede requerir solo una nueva URL base, clave de API e ID de modelo, pero las migraciones de producción deben verificar parámetros admitidos, formatos de respuesta, llamadas a herramientas, eventos de streaming, timeouts y contabilización de tokens.

Paso 5: Usa JavaScript en Node.js

Instalar el SDK de OpenAI para Node.js

npm install openai

Llamar a Sonnet 5.5 desde un módulo ES de Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.COMETAPI_KEY,
  baseURL: "https://api.cometapi.com/v1",
});

const response = await client.chat.completions.create({
  model: "claude-sonnet-5-5",
  messages: [
    {
      role: "user",
      content: "Create a TypeScript function that validates an email address.",
    },
  ],
});

console.log(response.choices[0].message.content);

Para aplicaciones backend en Node.js, conserva COMETAPI_KEY en el entorno del servidor en lugar de enviarla a un cliente en el navegador.

Niveles de pensamiento y esfuerzo de Claude Sonnet 5.5

La API usa por defecto un esfuerzo alto; las aplicaciones de Claude y Claude Code usan medio. Selecciona el esfuerzo según la calidad de tareas aceptadas, latencia y costo por token. La tabla siguiente es un punto de partida editorial, no una clasificación oficial de cargas de trabajo.

Evita asignar automáticamente el nivel de esfuerzo más alto a cada solicitud. Los flujos de agentes pueden encarecerse de forma notable cuando un razonamiento adicional también provoca más llamadas a herramientas y salidas más largas. Selecciona el ajuste con evaluación a nivel de tarea. Usa pensamiento adaptativo para Xhigh y Max, luego compara la calidad de tareas aceptadas y el costo total con niveles inferiores. Guía oficial de esfuerzo.

Configurar el esfuerzo mediante Messages

Este ejemplo usa el cliente de Anthropic inicializado arriba. Prueba los mismos controles en tu ruta de CometAPI antes del despliegue.

Configurar pensamiento adaptativo y esfuerzo alto

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=8192,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{"role": "user", "content": "Audit this service migration plan."}],
)

Desactivar el pensamiento inicial

Usa thinking={"type": "between_tools"} en esfuerzo bajo, medio o alto. Usa pensamiento adaptativo para xhigh o max. between_tools no acepta los campos display ni budget_tokens y no permite cambiar el esfuerzo a mitad de conversación.

Conservar el pensamiento en bucles de herramientas

Devuelve los bloques de contenido originales del asistente antes de anexar los resultados de la herramienta. El pensamiento conservado depende del modelo, el prefijo de la conversación y la cuenta emisora. La vinculación de prefijo se aplica por defecto en la Claude API, Amazon Bedrock y Google Cloud para cuentas creadas a partir del 31 de agosto de 2026, 00:00 UTC. No asumas que todos los gateways exponen los mismos controles de vinculación.

Cómo transmitir respuestas de Claude Sonnet 5.5

Transmitir respuestas largas

El streaming es útil para interfaces de chat, asistentes de programación y respuestas largas porque los usuarios pueden ver la salida antes de que finalice la generación.

Transmitir texto mediante Chat Completions compatible con OpenAI

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["COMETAPI_KEY"],
    base_url="https://api.cometapi.com/v1",
)

stream = client.chat.completions.create(
    model="claude-sonnet-5-5",
    messages=[
        {
            "role": "user",
            "content": "Explain how a retrieval-augmented generation pipeline works."
        }
    ],
    stream=True,
)

for chunk in stream:
    if not chunk.choices:
        continue
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

La transmisión normalmente no reduce el número total de tokens generados. Su principal beneficio es la latencia percibida. Las aplicaciones también deben gestionar streams interrumpidos, salidas parciales, reintentos de red y cancelaciones de forma explícita.

Usar herramientas con selección automática

Usa tool_choice={"type": "auto"}. Valida cada nombre de herramienta y argumento, aplica autorización y timeouts, devuelve resultados estructurados y limita las iteraciones. La ejecución de herramientas obligatorias corresponde a la orquestación de la aplicación.

Definir una herramienta de consulta de tickets y solicitar selección automática

tools = [{
    "name": "lookup_ticket",
    "description": "Retrieve a support ticket by ID",
    "input_schema": {
        "type": "object",
        "properties": {"ticket_id": {"type": "string"}},
        "required": ["ticket_id"],
        "additionalProperties": False,
    },
}]

response = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=4096,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=[{"role": "user", "content": "Look up ticket T-123 and summarize its status."}],
)

Un bloque tool_use solicita una acción; esta primera llamada no la ejecuta. Valida la solicitud en tu servidor, ejecuta la operación, anexa el contenido del asistente sin cambios y envía un tool_result correspondiente. El esquema de este ejemplo sigue requiriendo validación en la aplicación; el soporte estricto de herramientas debe verificarse en la ruta seleccionada.

Usar caché de prompts para contexto repetido

El caché de prompts es útil cuando las solicitudes contienen repetidamente el mismo prefijo grande, como políticas del sistema, esquemas de herramientas, mapas de repositorios, documentación de producto, instrucciones reutilizables o manuales de referencia.

Sonnet 5.5 requiere un prefijo de prompt almacenable en caché de al menos 512 tokens. Los prefijos más cortos se procesan sin caché, incluso con cache_control. Revisa cache_creation_input_tokens y cache_read_input_tokens; si ambos son cero, no se usó caché. Confirma el soporte en tu ruta de gateway. Referencia de caché de prompts.

Organiza el contexto estable antes del contenido dinámico de la solicitud

Stable system instructions
Stable tools
Stable repository or knowledge context
---------------- cache boundary ----------------
Current user request
Current retrieved context

La tarifa de lectura de caché actual de CometAPI es $0.16 por millón de tokens, comparado con $1.60 para entrada nueva. Las escrituras de caché se facturan por separado. Verifica los aciertos de caché en los metadatos de uso antes de estimar ahorros.

El caching es especialmente útil para agentes de programación y asistentes empresariales que reutilizan grandes prefijos de contexto a través de turnos. La economía depende de los aciertos reales de caché; reescribir con frecuencia el prefijo estable puede eliminar la mayor parte del beneficio esperado.

Enviar imágenes usando el esquema del endpoint seleccionado

Sonnet 5.5 acepta entrada de texto e imágenes. El JSON siguiente es una carga útil de Chat Completions compatible con OpenAI; sustituye la URL de imagen de ejemplo por una imagen pública bajo tu control. Messages usa un esquema de bloques de imagen diferente.

Enviar una imagen en una carga de Chat Completions

{
  "model": "claude-sonnet-5-5",
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Find the three most important UI problems in this screenshot."
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/interface.png"
          }
        }
      ]
    }
  ]
}

La forma exacta de la solicitud multimodal puede diferir entre la interfaz nativa de Claude y la compatible con OpenAI, así que usa el esquema del endpoint que realmente implementes en lugar de asumir que ambos formatos son intercambiables.

Gestionar salvaguardas y datos retenidos

Registra negativas y comportamientos de fallback como estados explícitos de la aplicación. Anthropic describe salvaguardas y disponibilidad de retención cero de datos para su servicio. Verifica por separado los acuerdos de retención y enrutamiento aplicables de tu gateway antes de enviar material de producción.

Claude Sonnet 5.5 vs Sonnet 5 vs Opus 5.5

Las etiquetas cualitativas siguientes son una guía editorial de enrutamiento basada en el alcance de la tarea, no calificaciones oficiales de rendimiento. Valida estos roles en cargas de trabajo representativas. No se infiere arquitectura detallada a partir de puntuaciones de benchmarks.

Encaminar tareas difíciles a un modelo de escalación

Routine task
    ↓
Claude Sonnet 5.5
    ↓
Confidence / validation failure?
    ├── No → Return result
    └── Yes → Escalate difficult case
                 ↓
              Opus-class model

Este patrón de enrutamiento puede reducir costos a la vez que preserva el acceso a un nivel de razonamiento más fuerte para casos difíciles.

Precios de Claude Sonnet 5.5 a través de CometAPI

Verificado el 10 de octubre de 2026: la entrada/salida en CometAPI siguen en $1.60/$8 por millón de tokens, un 20% por debajo de los $2/$10 de Anthropic. La lectura/escritura de caché de CometAPI sigue en $0.16/$2; la lectura/escritura de caché actual de Anthropic es $0.10/$2.50 para una escritura con TTL de cinco minutos. La página de lanzamiento aún muestra lecturas de caché a $0.20; esta revisión usa la referencia actual de caching. Los precios del gateway pueden cambiar de forma independiente.

La diferencia entre precio por token y costo por tarea importa para aplicaciones de agentes. Un agente de programación puede generar menos tokens pero aun así realizar múltiples rondas de llamadas a herramientas, lecturas de caché, inspección de código, reintentos y validación. El costo por tarea completada con éxito suele ser más informativo que el precio por token de entrada.

Estimar cargos por entrada nueva y tokens de salida

Input:
100,000 / 1,000,000 × $1.60 = $0.16

Output:
5,000 / 1,000,000 × $8.00 = $0.04

Estimated model-token cost:
$0.20

Los cargos por herramientas, operaciones de caché, pasos repetidos del agente u otras funciones facturables pueden cambiar el costo final.

Tarifas re-verificadas el 10 de octubre de 2026 en la página actual del modelo de CometAPI. Los precios de entrada/salida nuevas no han cambiado, por lo que el ejemplo sigue siendo $0.16 + $0.04 = $0.20 para 100,000 tokens de entrada nueva y 5,000 de salida. Excluye escrituras/lecturas de caché, tarifas de herramientas y reintentos. Revisa la facturación específica de la ruta antes de presupuestar.

Controlar el costo por tarea aceptada

Hay varias formas prácticas de reducir el gasto sin cambiar inmediatamente de modelo. Primero, define claramente los criterios de aceptación:

Definir un formato de aceptación de respuesta enfocado

Return only:
1. the root cause;
2. the affected file;
3. the smallest safe fix;
4. one regression test.

Segundo, recorta el contexto recuperado antes de enviarlo. Una ventana de contexto de 1M tokens es un límite de capacidad, no un objetivo. Tercero, reutiliza contexto estable mediante caché de prompts. Cuarto, selecciona el esfuerzo por tipo de carga de trabajo en lugar de fijar Alto para cada solicitud. Quinto, mide el costo por tarea aceptada:

Calcular el costo por tarea aceptada

Total API cost
÷
Number of outputs accepted without rework

Una solicitud más barata no es necesariamente un flujo de trabajo más barato si provoca reintentos, correcciones o llamadas a herramientas adicionales.

¿Cómo migrar de Sonnet 5 a la API de Claude Sonnet 5.5?

1. Mantén disponible la configuración previa de producción para rollback.
2. Cambia el ID de modelo de claude-sonnet-5 a claude-sonnet-5-5.
3. Aplica los cambios de pensamiento, selección de herramientas y de historial descritos arriba.
4. Reproduce solicitudes representativas, incluyendo herramientas, imágenes y streaming.
5. Compara salidas aceptadas, tasa de corrección humana, latencia p50/p95 y costo total por tarea.
6. Prueba reintentos, negativas, cancelaciones y streams interrumpidos.
7. Verifica aciertos de caché y comportamiento del presupuesto de salida a partir de los metadatos de uso.
8. Lanza un canario de tráfico pequeño y amplía solo después de superar los umbrales de aceptación.

Solución de problemas de errores de la API de Claude Sonnet 5.5

No reintentes solicitudes mal formadas o fallos de autenticación sin cambios. Evita acciones de herramientas duplicadas al reproducir ejecuciones de agentes interrumpidas.

Mejores prácticas de producción con Claude Sonnet 5.5

Elige una carga de trabajo, define un criterio de aceptación y evalúa la aplicación completa. Registra ID de modelo, endpoint, esfuerzo, latencia, uso de tokens y caché, fallos de herramientas, estado de finalización y resultado de tareas aceptadas. Mantén las claves del lado del servidor y configura timeouts, reintentos acotados y límites de iteración del agente.

Medir calidad y confiabilidad del flujo de trabajo

Para agentes de programación, también registra tests aprobados, archivos modificados innecesariamente, parches revertidos y finalizaciones exitosas sin intervención humana.

Ejemplo: Corregir un error bien delimitado en un repositorio

Proporciona el test que falla, los archivos fuente relevantes y el comportamiento esperado. Solicita un parche enfocado con una verificación de regresión. El criterio de aceptación es una corrección reproducible, tests relevantes aprobados y sin ediciones no relacionadas. Compara el costo total de API y herramientas frente a parches aceptados.

Ejemplo: Triaje de un ticket de soporte

Recupera el problema del cliente y los pasajes aprobados de la base de conocimiento. Pide al modelo que clasifique el problema, redacte una respuesta con evidencias y marque casos que requieran escalación. Acepta un resultado solo cuando sus afirmaciones coincidan con el material recuperado y la decisión de enrutamiento siga la política de soporte.

Ejemplo: Revisar un documento y una captura

Proporciona un procedimiento aprobado y una captura de la interfaz correspondiente. Pide discrepancias con referencias al pasaje relevante y al elemento visible de la interfaz. Requiere que un revisor confirme los hallazgos antes de cambiar el procedimiento.

Conclusión

Claude Sonnet 5.5 ofrece a los equipos un candidato práctico para flujos de trabajo rápidos de programación, soporte, documentos y uso de herramientas. Comienza con una solicitud funcional en CometAPI y luego añade los controles que necesite tu aplicación.

La migración requiere más que reemplazar el ID de modelo: revisa la configuración de pensamiento, la selección automática de herramientas, el parseo de respuestas y la reproducción del historial. Promueve el modelo cuando tus evaluaciones de carga de trabajo muestren un equilibrio aceptable entre calidad, latencia y costo; reserva un nivel más potente para tareas que no superen tu criterio de aceptación.

Preguntas frecuentes

¿Cómo deben rotar las claves de API de Claude Sonnet 5.5 los equipos sin tiempo de inactividad?

Almacena las claves en un gestor de secretos del lado del servidor y permite que los workers recarguen credenciales sin incrustarlas en el código de la aplicación. Si el proveedor admite claves activas superpuestas, introduce primero la de reemplazo, valida una solicitud pequeña, cambia gradualmente a los workers y luego revoca la clave anterior. Supervisa errores de autenticación durante el cambio y evita registrar cualquiera de las dos claves.

¿Cómo puede reanudarse un trabajo de Claude Sonnet 5.5 tras reiniciar un worker?

Persiste un identificador de trabajo, el último paso completado, la configuración de la solicitud y los registros de ejecución de herramientas. Reanuda desde un checkpoint verificado. Antes de repetir una acción de herramienta, comprueba si ya se completó y si es seguro repetirla. Un transcript guardado por sí solo no evita tickets duplicados, mensajes o escrituras en base de datos.

¿Cómo deben detectar los equipos cambios de comportamiento de Claude Sonnet 5.5 a lo largo del tiempo?

Mantén un conjunto de evaluación fechado con respuestas aceptadas o verificaciones de aceptación, junto con versiones de SDK y configuraciones de solicitud. Re-ejecuta periódicamente y tras cambios del proveedor, SDK, prompt o enrutamiento. Compara éxito de tareas, tasa de corrección, latencia y costo total. Si una cuenta ofrece fijación de versión, confirma sus garantías antes de depender de ella; conserva una ruta de rollback para flujos críticos.