Claude Sonnet 5 es el modelo Sonnet que Anthropic lanzó el 30 de junio de 2026, con tres argumentos principales: contexto de 1 millón de tokens, pensamiento adaptativo y estabilidad orientada a agentes. Conviene aclarar primero un estado: a octubre de 2026, Sonnet 5.5 ya es el modelo Sonnet actual, Sonnet 5 ha pasado a estado legacy, pero sigue disponible y la compañía indica que no lo retirará antes del 30 de junio de 2027. Los proyectos nuevos deberían evaluar primero Sonnet 5.5; los equipos que ya usan claude-sonnet-5 deben entender bien la clave, el contexto y los detalles de llamada para evitar problemas antes de migrar.

Este artículo cubre el estado del modelo, la obtención de la clave, las llamadas a Messages API, los límites de uso del contexto de 1M, la caché y el control de costes, y termina con los errores habituales y las preguntas frecuentes.

Nota: Anthropic y Claude son marcas de sus titulares; este artículo solo describe la conexión técnica. Las especificaciones, el contexto y la facturación figuran en la documentación oficial de Anthropic y en la página de precios de modelos; aquí no se fija un precio unitario.

1. Confirma primero el estado y las especificaciones del modelo

Elemento Información oficial
ID del modelo claude-sonnet-5
Estado Legacy, todavía disponible
Fecha de lanzamiento 30 de junio de 2026
Compromiso de retirada No antes del 30 de junio de 2027
Ventana de contexto 1.000.000 de tokens
Salida máxima 128.000 tokens (Messages API síncrona)
Salida por lotes 300.000 tokens (Batch API beta)
Entrada/salida Texto, imágenes → texto
Modo de pensamiento Pensamiento adaptativo; effort por defecto, high
Corte de conocimiento Enero de 2026

Puntos que suelen malinterpretarse:

  • «Legacy» no significa «fuera de servicio». Indica que ya existe un modelo más reciente, pero el antiguo sigue dentro de su periodo de soporte.
  • El contexto de 1M es capacidad, no un objetivo. Cuanto más largo es el contexto, más altos son el coste de entrada y la latencia.
  • El pensamiento adaptativo está activado por defecto; en tareas simples se puede reducir la profundidad de pensamiento con effort.
  • La interfaz síncrona admite hasta 128K de salida; solo cuando hace falta una salida más larga conviene considerar la capacidad beta de Batch API.

Si un proyecto empieza desde cero, conviene evaluar directamente Sonnet 5.5; si los prompts, los conjuntos de evaluación y el tráfico en producción ya están construidos alrededor de Sonnet 5, haz primero una comparación con poco tráfico y decide después cuándo migrar.

2. Obtener la API Key de Claude

Vía uno: Anthropic Console

  1. Regístrate e inicia sesión en Anthropic Console y completa la configuración de organización y facturación.
  2. Crea una clave en la página API Keys y nómbrala por proyecto o entorno.
  3. Confirma el saldo, los límites de tasa y los permisos de modelo.
  4. Guarda la clave en una variable de entorno del servidor; no la pongas en el frontend ni en Git.

La Base URL oficial es https://api.anthropic.com y la ruta de Messages es /v1/messages.

Vía dos: pasarela de IA de ZSQH

Regístrate en la pasarela de IA de ZSQH, crea una clave, recarga en yuanes y solicita factura, y consulta el consumo de varios modelos en un solo panel. La pasarela ofrece una entrada compatible con Anthropic; la Base URL es https://ai.zhongshangqihang.com y la ruta de llamada también es /v1/messages. Qué modelos Claude están habilitados y cómo se escribe cada nombre se consulta en precios de modelos.

Elemento Conexión directa a Anthropic Pasarela ZSQH
Base URL https://api.anthropic.com https://ai.zhongshangqihang.com
Cabecera de autenticación x-api-key x-api-key
Cabecera de versión anthropic-version: 2023-06-01 Igual
Nombre del modelo claude-sonnet-5 Según la página de precios del sitio
SDK SDK de Anthropic SDK de Anthropic

3. Llamada con curl

export ANTHROPIC_API_KEY="sk-tu-clave"

curl "https://ai.zhongshangqihang.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": 800,
    "system": "Eres un editor técnico. Responde de forma concreta.",
    "messages": [
      {"role": "user", "content": "Explica en tres puntos los límites de uso del contexto de 1M"}
    ]
  }'

Hay tres cosas que recordar: max_tokens es obligatorio en Claude Messages API; la autenticación usa x-api-key, no Authorization: Bearer; y la cabecera anthropic-version no se puede omitir. Si falta cualquiera de ellas, la respuesta será 401 o 400.

4. Llamada con Python

import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["ANTHROPIC_API_KEY"],
    base_url="https://ai.zhongshangqihang.com",
)

msg = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    system="Eres un asistente de control de calidad; devuelve solo JSON.",
    messages=[
        {"role": "user", "content": "Evalúa el sentimiento: la logística fue lenta, pero la atención fue buena."}
    ],
)

print(msg.content[0].text)

Hay un cambio de compatibilidad que conviene tener en cuenta: Sonnet 5 devuelve 400 si recibe valores no predeterminados de temperature, top_p o top_k. Es decir, si el código antiguo incluye habitualmente temperature=0.2, hay que eliminarlo al migrar a Sonnet 5 y controlar la estabilidad de la salida con prompts y effort.

5. Cómo aprovechar el contexto de 1M

1M de tokens equivalen aproximadamente a 550.000 palabras en inglés o 2,5 millones de caracteres Unicode (según la estimación del tokenizador oficial actual). Sirve para escenarios en los que «se mete todo el material de una vez», pero no para volcar todos los documentos sin criterio.

Escenario Práctica recomendada Motivo
Revisión de contratos largos Introducir el texto completo y pedir la salida en JSON por cláusula Evita que la recuperación omita cláusulas clave
Preguntas sobre un repositorio de código Recuperar primero los archivos relevantes y luego montar el contexto Todo el código es caro y dispersa la atención
Atención al cliente multirronda Conservar las últimas rondas más un resumen del historial Controla el crecimiento de la entrada
Análisis offline por lotes Usar Batch API La plataforma aplica un descuento específico por lotes
Generación de informes largos Generar por secciones y fusionar después Evita tocar el límite de salida en una sola llamada

La prioridad en la gestión del contexto es: primero recuperar, luego resumir y solo al final considerar el texto completo. Solo en tareas donde «omitir un fragmento puede provocar un error» merece la pena pagar la prima del contexto completo.

6. Caché y control de costes

La facturación de Claude se compone de entrada, salida, escritura en caché y lectura de caché. Según la página oficial de precios, la lectura de caché cuesta aproximadamente una décima parte del precio de entrada; la escritura de caché de 5 minutos, unas 1,25 veces el precio de entrada, y la de 1 hora es más cara; Batch API factura entrada y salida a la mitad. Los precios unitarios concretos figuran en precios de modelos.

Coste por llamada =
  tokens de entrada sin caché × precio de entrada
+ tokens de escritura en caché × precio de escritura en caché
+ tokens de lectura de caché × precio de lectura de caché
+ tokens de salida × precio de salida

El control de costes se aplica en este orden:

  1. Cachear el prefijo estable: coloca el system prompt, las definiciones de herramientas y la base de conocimiento fija al principio y añade cache_control.
  2. Cachear solo lo que se reutilizará: no escribas en caché documentos de un solo uso, porque pagarás la prima de escritura sin obtener retorno.
  3. Recuperar antes de volcar el texto completo: recuperar 5–10 fragmentos con RAG suele salir más barato que meter toda la base de conocimiento.
  4. Enviar las tareas offline a Batch: el etiquetado, el resumen y la clasificación que no necesitan respuesta en tiempo real deberían ir por lotes.
  5. Ajustar effort: reduce la profundidad de pensamiento en tareas simples y auméntala en las complejas.
  6. Limitar la salida: fija max_tokens, exige salida estructurada y reduce el texto largo inútil.
  7. Separar claves por proyecto: define límites de gasto y alertas, y revisa cada semana el ranking de consumo.

7. Errores habituales

Error Causa habitual Solución
401 Unauthorized Clave incorrecta o falta x-api-key Vuelve a copiar la clave y revisa las cabeceras
404 Not Found Base URL o ruta incorrecta Confirma /v1/messages
400 invalid_request_error Se envió un temperature no predeterminado u otro parámetro no admitido Elimina el parámetro y reintenta
429 rate_limit_error Concurrencia o frecuencia excedida Baja la concurrencia y usa retroceso exponencial
529 overloaded_error Carga excesiva en el servidor Reintenta más tarde y prepara una vía alternativa
invalid_request_error (prompt is too long) La entrada supera 1M Divide en lotes, recupera o resume
Error relacionado con max_tokens No se indicó o supera el límite Ajústalo a las especificaciones del modelo

Preguntas frecuentes

¿Es obligatorio migrar de Sonnet 5 a Sonnet 5.5?

No. Sonnet 5 sigue dentro de su periodo de servicio y la compañía indica que no lo retirará antes del 30 de junio de 2027. Pero los proyectos nuevos deberían evaluar primero Sonnet 5.5; en proyectos existentes conviene hacer una comparación con poco tráfico y migrar solo cuando los prompts, las llamadas a herramientas y el formato de salida sean compatibles.

¿Sirve la misma API Key para la suscripción de Claude?

No. La suscripción está orientada a los productos web y de cliente, mientras que la API Key es una credencial para desarrolladores; la facturación y los permisos se gestionan por separado.

¿El contexto de 1M sale más caro?

Sí. El contexto no tiene un «recargo de capacidad» adicional, pero cuantos más tokens de entrada, más alta es la factura y mayor la latencia. En tareas con documentos largos conviene priorizar la recuperación y el resumen, y usar el contexto completo solo cuando sea imprescindible evaluar el texto entero.

¿Sonnet 5 admite entrada de imágenes?

Sí; la especificación oficial es entrada de texto e imágenes y salida de texto. Las imágenes se convierten en tokens de entrada según reglas definidas, así que estima el coste antes de procesarlas por lotes.

¿Por qué da 400 al configurar temperature?

Sonnet 5 no acepta valores no predeterminados de temperature, top_p o top_k. Elimina esos parámetros y controla la salida con prompts y effort.

Siguiente paso

Crea primero una clave de prueba en la pasarela de IA de ZSQH, ejecuta una petición de Messages con curl y después intégrala en el SDK de Anthropic. La disponibilidad de modelos y los precios figuran en precios de modelos.

Lecturas relacionadas: