Cómo usar la API de Claude Sonnet 5 (Paso a paso con Apidog)

Claude Sonnet 5 se lanzó el 30 de junio de 2026, y es el modelo Sonnet más agéntico que Anthropic ha lanzado. Rinde de manera similar a Opus 4.8 en tareas de uso de herramientas y codificación a un precio mucho más bajo, lo que lo convierte en una opción predeterminada sólida para cualquier cosa que requiera herramientas en un bucle. Esta guía te muestra cómo llamar a la API de Claude Sonnet 5 de principio a fin: obtener una clave, enviar tu primera solicitud en curl y Python, leer la respuesta, manejar el nuevo valor predeterminado de pensamiento adaptativo, evitar los tres cambios de solicitud que devuelven errores 400, transmitir salidas largas y contar tokens con el nuevo tokenizador.

También configurarás todo esto en Apidog para que tus solicitudes vivan en una colección reutilizable con entornos guardados y pruebas automatizadas, en lugar de estar dispersas en el historial de tu shell. Si ya has llamado a la API de Mensajes antes, la mayor parte de esto te resultará familiar. El ID del modelo es claude-sonnet-5, y la forma de la solicitud coincide con lo que ya utilizas.

Lo que necesitas antes de empezar

Necesitas tres cosas para llamar a la API.

• Una cuenta de Anthropic y una clave de API desde la consola de la plataforma Claude.
• El ID del modelo: claude-sonnet-5. Es la cadena exacta, sin sufijo de fecha.
• Una forma de enviar solicitudes HTTP. curl funciona para una prueba rápida. Apidog funciona mejor una vez que estás iterando.

Sonnet 5 está disponible para todos los clientes de API, además de Amazon Bedrock (a través de la Plataforma Claude en AWS), Google Cloud a través de Vertex AI, y Microsoft Foundry en vista previa. Esta guía utiliza la API directa de Anthropic. El cuerpo de la solicitud es el mismo en todas las plataformas; solo cambian la autenticación y el host del endpoint.

Obtén tu clave de API

Inicia sesión en la consola de la plataforma Claude, abre la sección de claves de API y crea una nueva clave. Cópiala una vez y guárdala en un lugar seguro, porque la consola no la mostrará de nuevo. Nunca codifiques la clave directamente en tu código fuente ni la subas a git. En su lugar, configúrala como una variable de entorno:

export ANTHROPIC_API_KEY="sk-ant-..."

Si tienes un acuerdo ZDR, Sonnet 5 admite retención de datos cero, por lo que la superficie de la API no cambia para ti aquí.

Tu primera solicitud

La API de Sonnet 5 utiliza el endpoint de Mensajes de Anthropic. Aquí tienes una solicitud mínima con curl.

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",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Write a haiku about API testing."}
    ]
  }'

La misma solicitud con el SDK de Python:

import os
from anthropic import Anthropic

client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Write a haiku about API testing."}
    ],
)

print(message.content[0].text)

Dos campos realizan el trabajo pesado. model selecciona Sonnet 5. max_tokens limita la salida total. Sigue leyendo, porque max_tokens se comporta de manera diferente en Sonnet 5 que en Sonnet 4.6, y es lo más fácil de confundir.

Leyendo la respuesta

Una llamada exitosa devuelve HTTP 200 con un cuerpo JSON como este (recortado):

{
  "id": "msg_01ABC...",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-5",
  "content": [
    {"type": "text", "text": "Assertions green,\nendpoints answer on the first try,\nship the merge tonight."}
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 27
  }
}

Algunos campos son importantes para el trabajo real.

• content es un array. El texto vive en bloques donde type es "text". Con el uso de herramientas o el pensamiento habilitado, verás otros tipos de bloques en el mismo array, así que itera; no asumas que content[0] es siempre tu respuesta.
• stop_reason te indica por qué terminó la generación. end_turn es normal. max_tokens significa que alcanzaste el límite y la salida fue truncada. refusal es nuevo y vale la pena entenderlo (más abajo).
• usage reporta input_tokens y output_tokens. Esto es lo que se te factura, y los números son más altos en Sonnet 5 para el mismo texto debido al nuevo tokenizador.

El motivo de parada por rechazo

Sonnet 5 es el primer modelo de nivel Sonnet con salvaguardias de ciberseguridad en tiempo real. Si una solicitud toca un tema cibernético prohibido o de alto riesgo, el modelo puede negarse a responder. Un rechazo se devuelve como un HTTP 200 normal con stop_reason: "refusal", no como un error. Manéjalo en tu código de análisis de respuesta de la misma manera que manejarías cualquier motivo de parada que no sea end_turn, en lugar de tratarlo como una llamada HTTP fallida.

El pensamiento adaptativo está activado por defecto

Este es el mayor cambio de comportamiento con respecto a Sonnet 4.6, y confunde a la gente. En Sonnet 4.6, la ausencia del campo thinking significaba que no había pensamiento. En Sonnet 5, el pensamiento adaptativo está activado por defecto. Una solicitud sin el campo thinking ahora se ejecuta con pensamiento adaptativo, y los tokens de pensamiento cuentan para tu salida total.

Dado que max_tokens es un límite estricto para la salida total (tokens de pensamiento más texto de respuesta), un valor de max_tokens que era cómodo en 4.6 ahora puede truncar tu respuesta visible antes de que termine. Si migraste una carga de trabajo que nunca usó el pensamiento y estableciste un max_tokens ajustado, auméntalo o espera truncamientos.

Para desactivar el pensamiento por completo:

message = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    thinking={"type": "disabled"},
    messages=[
        {"role": "user", "content": "Return only the JSON, no reasoning."}
    ],
)

Para mantener el pensamiento adaptativo activado y controlar cuánto trabaja el modelo, utiliza el parámetro `effort` en lugar de intentar establecer un presupuesto de tokens manual. `effort` admite low, medium, high y xhigh. Un `effort` más alto significa un pensamiento más profundo y un mayor gasto de tokens. Anthropic documenta el comportamiento en la página de pensamiento adaptativo. Ten en cuenta que el valor del campo es {"type": "adaptive"}, no un número budget_tokens.

Tres cambios en la solicitud que devuelven 400

Si estás portando código de Sonnet 4.6 o de un modelo Claude más antiguo, tres cosas que antes funcionaban ahora devuelven un error 400. Corrígelas antes de migrar.

1. El pensamiento extendido manual ha sido eliminado. thinking: {type: "enabled", budget_tokens: N} devuelve 400. Ya estaba obsoleto en 4.6. Usa el pensamiento adaptativo más el parámetro `effort` en su lugar.
2. Los parámetros de muestreo son rechazados. Establecer temperature, top_p o top_k a un valor no predeterminado devuelve 400. Elimínalos. Omitirlos, o dejarlos en su valor predeterminado, está bien. Dirige el comportamiento con instrucciones de `system-prompt` en su lugar. Esta restricción ya existía en Opus 4.7 y superiores; es nueva para la clase Sonnet.
3. El prefijo de mensajes del asistente no es compatible. Poner un prefijo al inicio del turno del asistente devuelve 400. Usa salidas estructuradas o output_config.format o instrucciones de `system-prompt` para dar forma a la salida en su lugar.

Todo lo demás que funciona en Sonnet 4.6 funciona en Sonnet 5 sin otros cambios de código. Las formas de solicitud, respuesta y transmisión son idénticas. Para un tutorial de migración más completo, consulta nuestra guía sobre la API de Claude Sonnet 4.6, que cubre la misma superficie de solicitud que Sonnet 5 hereda.

Transmisión para salidas grandes

Sonnet 5 admite hasta 128.000 tokens de salida. Para respuestas largas, o cualquier solicitud donde el pensamiento adaptativo eleva la salida total, transmite el resultado para obtener los tokens a medida que se generan en lugar de esperar la respuesta completa. La transmisión también evita los tiempos de espera del cliente en generaciones grandes.

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8000,
    messages=[
        {"role": "user", "content": "Draft an OpenAPI 3.1 spec for a bookstore checkout API."}
    ],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

La forma del evento de transmisión es la misma que en Sonnet 4.6, por lo que los manejadores de transmisión existentes funcionan sin cambios.

Conteo de tokens con el nuevo tokenizador

Sonnet 5 utiliza un nuevo tokenizador. El mismo texto de entrada produce aproximadamente un 30% más de tokens que en Sonnet 4.6, alrededor de 1.3 veces más. Esto no es un cambio de API. Las formas de solicitud, respuesta y transmisión son idénticas, y no necesitas cambiar ningún código por ello. Pero afecta a todo lo que mides o presupuestas en tokens.

• Tus números de usage y los resultados del conteo de tokens son más altos para el mismo texto. Vuelve a contar con Sonnet 5; no reutilices tus conteos de 4.6.
• La ventana de contexto de 1.000.000 de tokens contiene menos texto en promedio, porque cada token ahora cubre menos texto.
• Un valor de max_tokens dimensionado cerca de tu salida esperada ahora puede truncar. Revísalo.
• El costo por solicitud para texto equivalente puede ser más alto aunque el precio por token no haya cambiado.

Usa el endpoint `count-tokens` antes de enviar, para que presupuestes con los números reales de Sonnet 5:

count = client.messages.count_tokens(
    model="claude-sonnet-5",
    messages=[
        {"role": "user", "content": "Estimate the tokens for this prompt on Sonnet 5."}
    ],
)
print(count.input_tokens)

Anthropic documenta esto en la página de conteo de tokens.

Errores, límites de velocidad y conceptos básicos de costos

Se aplican las semánticas HTTP estándar. Un 400 significa una solicitud mal formada (los tres cambios anteriores son los sospechosos habituales en Sonnet 5). Un 401 significa una clave de API incorrecta o faltante. Un 429 significa que alcanzaste un límite de velocidad. Lee el encabezado retry-after y espera antes de reintentar. Recuerda que un rechazo es un 200, no un error, así que no lo envíes a través de tu lógica de reintento.

En cuanto a precios, la tarifa de introducción es de $2 por millón de tokens de entrada y $10 por millón de tokens de salida, en efecto hasta el 31 de agosto de 2026. Después de eso, pasará a la tarifa estándar de $3 por millón de entrada y $15 por millón de salida, la misma tarifa por token que Sonnet 4.6. Debido al cambio del tokenizador, el costo de una solicitud de texto equivalente aún puede ser más alto que en 4.6, aunque la tarifa por token coincida, así que modela tus cargas de trabajo reales con el conteo de tokens en lugar de asumir una paridad plana. Para una explicación más profunda de los costos, consulta nuestro desglose de costos de la API de Claude y la guía de límites de velocidad de la API de Claude. Priority Tier no está disponible en Sonnet 5.

Prueba y organiza tus llamadas a Sonnet 5 en Apidog

Una vez que hayas superado el primer comando curl, querrás tener tus solicitudes guardadas, tu clave almacenada una vez y tus respuestas verificadas automáticamente. Ahí es donde entra Apidog. Es una plataforma API todo en uno, por lo que la misma solicitud que envías manualmente se convierte en un activo reutilizable y testeable. Descarga Apidog para seguir los pasos.

Aquí tienes una configuración práctica para la API de Sonnet 5.

1. Crea la solicitud. Añade una nueva solicitud HTTP en Apidog. Establece el método en POST y la URL en https://api.anthropic.com/v1/messages. Añade los encabezados anthropic-version: 2023-06-01 y content-type: application/json. Pega el cuerpo JSON con "model": "claude-sonnet-5".

2. Almacena la clave de API como una variable de entorno. Crea un entorno (por ejemplo, "Anthropic Production") y añade una variable llamada ANTHROPIC_API_KEY. Haz referencia a ella en el encabezado x-api-key como {{ANTHROPIC_API_KEY}}. Ahora tu clave reside en un solo lugar, fuera del cuerpo de tu solicitud, y puedes cambiar de entornos sin editar las solicitudes.

3. Guárdalo en una colección. Agrupa tus solicitudes de Sonnet 5, una llamada de mensaje simple, una llamada de transmisión, una llamada de herramientas, en una sola colección. Todo tu equipo obtiene las mismas solicitudes validadas en lugar de copiar fragmentos de curl.

4. Añade una prueba automatizada. Adjunta aserciones a la solicitud para que una ejecución falle ruidosamente cuando algo se desvíe. Por ejemplo:

• Asegúrate de que el estado de la respuesta sea 200.
• Asegúrate de que model sea igual a claude-sonnet-5.
• Asegúrate de que stop_reason esté presente y no sea max_tokens (una forma rápida de detectar truncamientos después del cambio del tokenizador).
• Asegúrate de que usage.output_tokens sea mayor que 0.

Encadena esto en un escenario de prueba y ejecútalo en CI cada vez que cambies los prompts o migres las versiones del modelo. Esa última aserción es la forma más económica de detectar una regresión de max_tokens causada por el pensamiento adaptativo que ahora está activado por defecto.

5. Simula el endpoint. El `smart mock` de Apidog devuelve una respuesta realista para la forma de los Mensajes, para que el código cliente de tu aplicación, el manejo de errores y el analizador de transmisión puedan construirse y probarse sin gastar un solo token. Esto es útil para el trabajo de frontend y para probar la carga de tu propia capa de integración.

Si te estás cambiando de Postman para esto, nuestro punto de vista sobre las pruebas de API sin Postman en 2026 explica por qué un flujo de trabajo de diseño más prueba más simulación en una sola herramienta ahorra viajes de ida y vuelta. ¿Prefieres la terminal? La guía completa de Apidog CLI muestra cómo ejecutar estas mismas pruebas guardadas en una pipeline.

Preguntas Frecuentes

¿Cuál es el ID del modelo Claude Sonnet 5?

Es claude-sonnet-5, la cadena exacta sin sufijo de fecha. Úsalo en el campo model de tu solicitud de Mensajes. Es un reemplazo directo para claude-sonnet-4-6, así que en la mayoría de los casos solo tienes que cambiar el ID del modelo y revisar tres cosas: el pensamiento adaptativo que ahora está activado por defecto, los parámetros de muestreo eliminados y el presupuesto de pensamiento manual eliminado. Para una imagen completa del modelo, lee qué es Claude Sonnet 5.

¿Por qué se recorta mi salida de max_tokens en Sonnet 5?

El pensamiento adaptativo está activado por defecto, y los tokens de pensamiento cuentan contra max_tokens junto con el texto de tu respuesta. Si tu límite estaba ajustado para una carga de trabajo sin pensamiento en Sonnet 4.6, auméntalo, o establece thinking: {"type": "disabled"} si no quieres pensamiento en absoluto. El nuevo tokenizador produce aproximadamente un 30% más de tokens para el mismo texto, lo que agrava el efecto.

¿Necesito cambiar mi código para migrar de Sonnet 4.6?

Solo en tres lugares. Elimina los valores no predeterminados de temperature, top_p y top_k. Elimina cualquier thinking: {type: "enabled", budget_tokens: N}. Elimina el prefijo de mensajes del asistente. Cada uno de estos devuelve un 400 en Sonnet 5. Todo lo demás, incluidas las formas de transmisión y respuesta, permanece sin cambios. Si también ejecutas Opus, nuestra guía de la API de Opus 4.8 utiliza la misma superficie de Mensajes.

¿Es un rechazo un error que debo capturar?

No. Un rechazo por ciberseguridad devuelve HTTP 200 con stop_reason: "refusal". Trátalo como una respuesta normal con un motivo de parada que no sea end_turn, no como una solicitud fallida. No lo envíes a través de tu ruta de reintento en caso de error.

¿Cuánto cuesta la API de Sonnet 5?

El precio de introducción es de $2 por millón de tokens de entrada y $10 por millón de tokens de salida hasta el 31 de agosto de 2026, y después $3 y $15. La tarifa por token coincide con la de Sonnet 4.6, pero el nuevo tokenizador significa que el texto equivalente puede costar más, así que mide con el conteo de tokens en lugar de asumir la paridad.