DEV Community

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

Posted on • Originally published at apidog.com

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. Es el modelo Sonnet más agéntico de Anthropic y está pensado para flujos con herramientas, código y llamadas iterativas. En esta guía verás cómo llamar a la API de Claude Sonnet 5 desde cero: crear la clave, enviar solicitudes con curl y Python, leer la respuesta, manejar el pensamiento adaptativo, evitar errores 400 comunes, transmitir respuestas largas y contar tokens con el nuevo tokenizador.

Prueba Apidog hoy

También puedes configurar estas llamadas en Apidog para guardar solicitudes en una colección reutilizable, usar entornos, proteger la clave de API y automatizar pruebas. Si ya usas la API de Mensajes de Anthropic, la migración es directa: el ID del modelo es claude-sonnet-5 y la forma de la solicitud se mantiene.

Lo que necesitas antes de empezar

Para llamar a Claude Sonnet 5 necesitas:

  • Una cuenta de Anthropic y una clave de API desde la consola de Claude.
  • El ID del modelo: claude-sonnet-5.
  • Un cliente HTTP: curl para pruebas rápidas, Python para integración, o Apidog para trabajar con colecciones y entornos.

Sonnet 5 está disponible para clientes de API, Amazon Bedrock mediante la Plataforma Claude en AWS, Google Cloud vía Vertex AI y Microsoft Foundry en vista previa. Esta guía usa la API directa de Anthropic. En otras plataformas, cambian el host y la autenticación, pero el cuerpo de la solicitud es equivalente.

Obtén tu clave de API

Crea una clave desde la consola de la plataforma Claude. Cópiala una sola vez y guárdala de forma segura. No la escribas directamente en el código ni la subas a git.

Configúrala como variable de entorno:

export ANTHROPIC_API_KEY="sk-ant-..."
Enter fullscreen mode Exit fullscreen mode

Si tienes un acuerdo ZDR, Sonnet 5 admite retención de datos cero; no necesitas cambiar la superficie de la API.

Envía tu primera solicitud

Claude Sonnet 5 usa el endpoint de Mensajes de Anthropic.

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."}
    ]
  }'
Enter fullscreen mode Exit fullscreen mode

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)
Enter fullscreen mode Exit fullscreen mode

Campos clave:

  • model: selecciona claude-sonnet-5.
  • max_tokens: limita la salida total.
  • messages: contiene el historial conversacional.

Importante: en Sonnet 5, max_tokens incluye tokens de pensamiento y texto visible. Si vienes de Sonnet 4.6, revisa este valor.

Lee la respuesta correctamente

Una respuesta exitosa devuelve HTTP 200:

{
  "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
  }
}
Enter fullscreen mode Exit fullscreen mode

Al procesarla, no asumas que content[0] siempre contiene texto. content es un array y puede incluir otros tipos de bloques cuando usas herramientas o pensamiento.

Ejemplo seguro en Python:

for block in message.content:
    if block.type == "text":
        print(block.text)
Enter fullscreen mode Exit fullscreen mode

Campos que debes revisar:

  • content: bloques de salida.
  • stop_reason: motivo de finalización.
  • usage.input_tokens: tokens de entrada.
  • usage.output_tokens: tokens de salida.

Valores comunes de stop_reason:

  • end_turn: generación terminada normalmente.
  • max_tokens: la salida fue truncada.
  • refusal: el modelo rechazó la solicitud.

Maneja refusal como respuesta, no como error HTTP

Sonnet 5 puede rechazar solicitudes relacionadas con ciberseguridad prohibida o de alto riesgo. En ese caso, la API devuelve HTTP 200 con:

"stop_reason": "refusal"
Enter fullscreen mode Exit fullscreen mode

No lo envíes a tu lógica de reintentos. Trátalo como una respuesta válida con un motivo de parada distinto de end_turn.

Ejemplo:

if message.stop_reason == "refusal":
    print("La solicitud fue rechazada por políticas de seguridad.")
elif message.stop_reason == "max_tokens":
    print("La respuesta fue truncada. Aumenta max_tokens.")
else:
    print("Respuesta completada.")
Enter fullscreen mode Exit fullscreen mode

Entiende el pensamiento adaptativo

En Sonnet 4.6, si no enviabas el campo thinking, no había pensamiento extendido.

En Sonnet 5, el pensamiento adaptativo está activado por defecto. Eso significa que una solicitud sin thinking puede consumir tokens de pensamiento, y esos tokens cuentan dentro de max_tokens.

Si migras una carga de trabajo con max_tokens ajustado, puedes ver truncamientos.

Desactivar pensamiento

Si quieres una respuesta directa sin pensamiento:

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

Usar pensamiento adaptativo con esfuerzo controlado

Para mantener pensamiento adaptativo, usa effort en lugar de un presupuesto manual de tokens.

Valores admitidos:

  • low
  • medium
  • high
  • xhigh

Un valor más alto implica más razonamiento y mayor consumo de tokens.

Anthropic documenta este comportamiento en la página de pensamiento adaptativo.

El campo debe usar:

{
  "type": "adaptive"
}
Enter fullscreen mode Exit fullscreen mode

No uses budget_tokens.

Evita estos 3 errores 400 al migrar

Si vienes de Sonnet 4.6 o de modelos Claude anteriores, revisa estos puntos antes de desplegar.

1. No uses pensamiento extendido manual

Esto devuelve 400:

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 4096
  }
}
Enter fullscreen mode Exit fullscreen mode

Usa pensamiento adaptativo con effort, o desactívalo:

{
  "thinking": {
    "type": "disabled"
  }
}
Enter fullscreen mode Exit fullscreen mode

2. Elimina parámetros de muestreo no predeterminados

Sonnet 5 rechaza valores no predeterminados para:

  • temperature
  • top_p
  • top_k

En lugar de ajustar muestreo, controla el comportamiento con instrucciones de sistema.

Ejemplo:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "system": "Responde de forma concisa y devuelve solo JSON válido.",
  "messages": [
    {
      "role": "user",
      "content": "Genera un objeto con nombre y descripción."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

3. No uses prefijos en mensajes del asistente

El prefijo de mensajes del asistente no es compatible y devuelve 400.

Para dar forma a la salida, usa:

  • instrucciones de sistema,
  • salidas estructuradas,
  • output_config.format, cuando aplique.

La forma general de solicitud, respuesta y streaming se mantiene igual que en Sonnet 4.6. Para una referencia de migración relacionada, consulta la guía de la API de Claude Sonnet 4.6.

Transmite respuestas largas

Sonnet 5 admite hasta 128.000 tokens de salida. Para respuestas grandes, usa streaming para recibir tokens mientras se generan y reducir riesgos de timeout del cliente.

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)
Enter fullscreen mode Exit fullscreen mode

La forma de los eventos de streaming es la misma que en Sonnet 4.6, por lo que tus manejadores existentes deberían seguir funcionando.

Cuenta tokens con el nuevo tokenizador

Sonnet 5 usa un nuevo tokenizador. Para el mismo texto, puedes ver aproximadamente un 30% más de tokens que en Sonnet 4.6.

Esto afecta:

  • métricas de usage,
  • presupuestos de tokens,
  • límites de max_tokens,
  • estimación de costos,
  • uso efectivo de la ventana de contexto.

Antes de enviar prompts grandes, usa count_tokens:

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)
Enter fullscreen mode Exit fullscreen mode

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

Maneja errores, límites de velocidad y costos

Semántica HTTP habitual:

  • 400: solicitud mal formada.
  • 401: clave de API faltante o inválida.
  • 429: límite de velocidad alcanzado.
  • 200 con stop_reason: "refusal": rechazo del modelo, no error HTTP.

Para 429, lee el encabezado retry-after y espera antes de reintentar.

Ejemplo básico:

try:
    message = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=1024,
        messages=[
            {"role": "user", "content": "Summarize this API contract."}
        ],
    )

    if message.stop_reason == "max_tokens":
        raise RuntimeError("Respuesta truncada. Aumenta max_tokens.")

except Exception as error:
    print(f"Error al llamar a Claude: {error}")
Enter fullscreen mode Exit fullscreen mode

Sobre precios: la tarifa introductoria es de 2 USD por millón de tokens de entrada y 10 USD por millón de tokens de salida hasta el 31 de agosto de 2026. Después pasa a 3 USD por millón de tokens de entrada y 15 USD por millón de tokens de salida. Aunque la tarifa por token coincida con Sonnet 4.6, el nuevo tokenizador puede elevar el costo de texto equivalente.

Para más contexto, consulta el 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.

Configura Claude Sonnet 5 en Apidog

Después de validar la llamada con curl, conviene guardar la solicitud en una colección, parametrizar la clave y añadir pruebas. Puedes hacerlo en Apidog.

1. Crea una solicitud HTTP

Configura:

  • Método: POST
  • URL: https://api.anthropic.com/v1/messages

Headers:

anthropic-version: 2023-06-01
content-type: application/json
x-api-key: {{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Body:

{
  "model": "claude-sonnet-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Write a haiku about API testing."
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode

2. Guarda la clave como variable de entorno

Crea un entorno, por ejemplo:

Anthropic Production
Enter fullscreen mode Exit fullscreen mode

Añade la variable:

ANTHROPIC_API_KEY=sk-ant-...
Enter fullscreen mode Exit fullscreen mode

Luego referencia la variable en el header:

x-api-key: {{ANTHROPIC_API_KEY}}
Enter fullscreen mode Exit fullscreen mode

Así evitas copiar la clave en cada solicitud.

3. Agrupa llamadas en una colección

Crea una colección para Sonnet 5 con solicitudes como:

  • mensaje simple,
  • streaming,
  • llamada con herramientas,
  • conteo de tokens,
  • pruebas de errores esperados.

Esto permite que el equipo use las mismas solicitudes verificadas en lugar de compartir fragmentos sueltos de curl.

4. Añade pruebas automatizadas

Valida la respuesta después de cada ejecución.

Aserciones útiles:

  • estado HTTP igual a 200,
  • model igual a claude-sonnet-5,
  • stop_reason presente,
  • stop_reason distinto de max_tokens,
  • usage.output_tokens mayor que 0.

Estas pruebas ayudan a detectar truncamientos después de cambiar prompts, ajustar max_tokens o migrar desde Sonnet 4.6.

5. Simula el endpoint

El smart mock de Apidog puede devolver respuestas realistas con la forma de la API de Mensajes. Úsalo para probar tu frontend, tu cliente HTTP o tu capa de integración sin consumir tokens.

Si estás evaluando alternativas a Postman, lee la guía sobre pruebas de API sin Postman en 2026. Si prefieres ejecutar desde terminal o CI, consulta la guía completa de Apidog CLI.

Preguntas frecuentes

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

El ID es:

claude-sonnet-5
Enter fullscreen mode Exit fullscreen mode

Úsalo en el campo model de la solicitud de Mensajes. Es un reemplazo directo para claude-sonnet-4-6, pero revisa el pensamiento adaptativo, los parámetros de muestreo eliminados y el presupuesto de pensamiento manual eliminado.

Para una visión general del modelo, lee qué es Claude Sonnet 5.

¿Por qué se trunca mi salida con max_tokens?

Porque en Sonnet 5 el pensamiento adaptativo está activado por defecto y sus tokens cuentan dentro de max_tokens. Además, el nuevo tokenizador puede producir aproximadamente un 30% más de tokens para el mismo texto.

Soluciones:

  • aumenta max_tokens,
  • desactiva pensamiento con thinking: {"type": "disabled"},
  • usa count_tokens antes de enviar prompts grandes.

¿Necesito cambiar mi código al migrar desde Sonnet 4.6?

Solo revisa tres puntos:

  1. Elimina temperature, top_p y top_k si usan valores no predeterminados.
  2. Elimina thinking: {type: "enabled", budget_tokens: N}.
  3. Elimina prefijos de mensajes del asistente.

La forma de respuesta y streaming permanece igual. Si también usas Opus, la guía de la API de Opus 4.8 usa la misma superficie de Mensajes.

¿Un rechazo es un error que debo capturar?

No. Un rechazo devuelve HTTP 200 con:

"stop_reason": "refusal"
Enter fullscreen mode Exit fullscreen mode

Trátalo como una respuesta normal con un motivo de parada especial. No lo proceses como error HTTP ni lo reintentes automáticamente.

¿Cuánto cuesta la API de Sonnet 5?

El precio introductorio es:

  • 2 USD por millón de tokens de entrada,
  • 10 USD por millón de tokens de salida,

hasta el 31 de agosto de 2026.

Después pasa a:

  • 3 USD por millón de tokens de entrada,
  • 15 USD por millón de tokens de salida.

El nuevo tokenizador puede hacer que texto equivalente consuma más tokens que en Sonnet 4.6, así que mide con count_tokens antes de estimar costos.

Top comments (0)