La dificultad de integrar la API de Claude no está en “saber enviar una petición HTTP”, sino en varios detalles que se pasan por alto con facilidad: en qué encabezado va la clave, si anthropic-version es obligatorio, por qué no se puede omitir max_tokens y por qué content es un arreglo en lugar de una cadena. Si estos puntos quedan bien, la llamada mínima funciona en diez minutos.
Este artículo sigue el orden: cuenta y clave, encabezados, curl, Python, streaming y parámetros, diagnóstico de errores y seguridad de las claves. Al final explica cómo usar un gateway compatible como punto de entrada alternativo. Los ID de modelo, el contexto y la facturación se rigen por la documentación oficial de Anthropic y por los precios de modelos del sitio.
Nota: Anthropic y Claude son marcas de sus respectivos titulares, y OpenAI es marca de su titular. Este artículo solo describe la integración técnica. Los modelos, los precios y las cuotas cambian; antes de integrar, verifica la documentación oficial.
1. Preparación previa: cuenta, espacio de trabajo y clave
La API de Claude usa Anthropic Console para gestionar la cuenta, los espacios de trabajo, las API Keys y la facturación. Antes de empezar, confirma tres cosas:
| Elemento | Qué confirmar | Explicación |
|---|---|---|
| Cuenta | Correo verificable y acceso a Console | Para equipos se recomienda un correo corporativo |
| Espacio de trabajo | A qué espacio pertenece la clave | El espacio determina miembros, claves y atribución de consumo |
| Facturación | Método de pago, datos de facturación y cuota disponible | Prevalece lo que muestre Console |
Si el equipo aún no ha decidido quién administra la facturación, no crees todavía una clave de producción. Una vez distribuida una clave, el consumo y los permisos quedan ligados al espacio de trabajo correspondiente, y separarlos después cuesta más.
2. Crear una API Key: seis pasos
- Abre Anthropic Console (console.anthropic.com), regístrate o inicia sesión y completa la verificación del correo.
- Crea o selecciona un espacio de trabajo. Conviene separar producción, pruebas y experimentos personales para no usar una sola clave en todas partes.
- Entra en la página de API Keys, crea una clave nueva y escribe un nombre que indique el uso, por ejemplo
prod-backend-2026-10. - Copia la clave y guárdala de inmediato en un gestor de secretos o en una variable de entorno. La mayoría de las consolas solo muestra el valor completo al crearla.
- En la página de facturación de Console, confirma el método de pago, los datos de facturación y la configuración de cuota. Si admite prepago, facturas y límites de cuota depende de las opciones reales de la consola.
- Define la variable de entorno en local y envía una petición mínima para validar que la clave funciona.
export ANTHROPIC_API_KEY="sk-ant-tu-clave"
No escribas la clave en el código, en un repositorio Git, en una página de frontend ni en un chat. Durante las pruebas también conviene crear una clave separada para poder revocarla en cualquier momento.
3. Encabezados y llamada mínima con curl
El punto de entrada de Messages API es POST https://api.anthropic.com/v1/messages, y hay tres encabezados clave:
| Encabezado | Valor | Función |
|---|---|---|
x-api-key |
Tu API Key | Autenticación de la API Key de Anthropic |
anthropic-version |
2023-06-01 |
Especifica la versión de la API; si falta, puede devolver error |
content-type |
application/json |
Declara que el cuerpo es JSON |
Atención: la API Key va en x-api-key, no en Authorization: Bearer. Mezclar estos dos métodos de autenticación es una causa muy frecuente de 401.
curl https://api.anthropic.com/v1/messages \
-H "content-type: application/json" \
-H "x-api-key: $ANTHROPIC_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-opus-5-5",
"max_tokens": 1024,
"system": "Eres un asistente técnico. Responde de forma concisa.",
"messages": [
{"role": "user", "content": "Explica en tres frases qué es un gateway de API."}
]
}'
El ID de modelo del ejemplo es solo uno de los disponibles en este momento; los modelos reales, el contexto y los precios se rigen por la Models API oficial y por los precios de modelos del sitio. En la respuesta, content es un arreglo de bloques y el texto suele estar en content[0].text, pero lo más robusto es recorrerlo y comprobar type == "text".
4. Llamada a Messages API desde Python
Instala el SDK oficial:
pip install anthropic
La llamada mínima es la siguiente:
import os
import anthropic
client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
resp = client.messages.create(
model="claude-opus-5-5",
max_tokens=1024,
system="Eres un asistente técnico. Responde de forma concisa.",
messages=[
{"role": "user", "content": "Explica en tres frases qué es un gateway de API."}
],
)
for block in resp.content:
if block.type == "text":
print(block.text)
print(resp.stop_reason)
print(resp.usage.input_tokens, resp.usage.output_tokens)
Algunos puntos importantes:
systemes un parámetro de nivel superior; no lo escribas como un mensaje{"role": "system"}. Los roles de Messages API son principalmenteuseryassistant.max_tokenses obligatorio e indica la longitud máxima de salida de esta respuesta. Si es demasiado bajo, la respuesta se corta ystop_reasonmuestramax_tokens; si es demasiado alto, hay que considerar el costo y el tiempo de espera.resp.contentes un arreglo de bloques que puede incluir bloques de texto, de razonamiento o de llamadas a herramientas. El código de negocio no debe asumir que solo hay texto.- Registra
usageystop_reason; son la base para conciliar el consumo y diagnosticar problemas.
5. system, max_tokens y salida en streaming
system se usa para el rol, el formato de salida y las condiciones límite. El contenido estable va delante y la entrada variable del usuario va en messages, lo que favorece los aciertos de caché.
max_tokens no es “cuanto más, mejor”. Limita la salida de una sola respuesta y no cambia el costo de entrada; para informes largos o código extenso hay que dejar espacio suficiente, mientras que en clasificación y extracción puede ser más bajo. En producción conviene configurarlo por tipo de interfaz, no con un valor global.
La salida en streaming es adecuada para respuestas largas e interfaces interactivas. Así se escribe con el SDK de Python:
with client.messages.stream(
model="claude-opus-5-5",
max_tokens=4096,
system="Eres un asistente técnico.",
messages=[{"role": "user", "content": "Escribe una descripción de producto de 200 palabras."}],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
Las peticiones en streaming también devuelven usage y stop_reason; no los omitas al guardar el resultado. Si usas HTTP nativo, añade "stream": true al cuerpo; la respuesta es un flujo de eventos SSE que se analiza con eventos como content_block_delta.
6. Nombres de modelo y elección de versión
Los modelos de Claude se dividen en familias como Opus, Sonnet y Haiku, con posicionamiento, contexto y precios distintos. Los ID de modelo suelen tener dos formas: alias estable y snapshot con fecha. En producción hay que decidir cuál se usa y no copiar directamente el nombre visible de la consola en el código.
Orden de elección recomendado:
- Usa primero un conjunto de evaluación del negocio para filtrar las familias que cumplen los requisitos de calidad.
- Compara después latencia, contexto y costo.
- Confirma por último que ese modelo esté disponible en la región objetivo y con la forma de acceso elegida.
Los modelos se lanzan y retiran, y los ID antiguos pueden pasar a estado legacy. Centraliza los nombres de modelo en configuración o en una tabla de mapeo para cambiar un solo lugar al migrar. Los modelos disponibles se rigen por la Models API oficial, la consola y los precios de modelos del sitio.
7. Cómo diagnosticar 401, 429 y 400
| Código | Causa habitual | Orden de tratamiento |
|---|---|---|
| 401 | Clave ausente, encabezado incorrecto, clave revocada, espacio de trabajo incompatible | Revisar x-api-key, espacios y saltos de línea, estado de la clave y base URL |
| 429 | Frecuencia de peticiones o velocidad de tokens excedida, aumento de concurrencia, problema de cuota | Leer retry-after, aplicar retroceso exponencial con jitter, separar claves y reducir concurrencia |
| 400 | JSON no válido, falta max_tokens, ID de modelo incorrecto, parámetro fuera de límite |
Conservar el cuerpo del error y el request id; revisar el cuerpo campo por campo |
| 404 | Ruta o nombre de modelo inexistente | Confirmar /v1/messages y el ID del modelo |
| 5xx | Fallo temporal del proveedor | Reintentar un número limitado de veces; si continúa, cambiar de entrada |
Al diagnosticar, conserva primero el encabezado request-id. Ante un 401, no sospeches primero del saldo: revisa el encabezado de autenticación y la clave. Un 429 no siempre significa “no hay dinero”, también puede ser un límite de velocidad. Un 400 suele ser un problema del cuerpo de la petición, y el mensaje de error normalmente señala el campo concreto.
8. Seguridad de las claves y gateway compatible como alternativa
La seguridad de las claves debe cumplir al menos cuatro puntos: guardarlas solo en variables de entorno o en un gestor de secretos; separarlas por proyecto; configurar alertas de consumo; y rotarlas y revocar las de los miembros que salgan. No debe haber claves permanentes en frontend, aplicaciones móviles ni repositorios públicos.
Si un equipo tiene problemas de red, pago o facturación, puede usar un gateway con punto de entrada compatible con Anthropic en lugar de la dirección oficial. Con el SDK oficial normalmente basta cambiar base_url y la clave:
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com",
)
resp = client.messages.create(
model="consulta la lista de modelos del sitio",
max_tokens=256,
messages=[{"role": "user", "content": "Responde solo OK"}],
)
print(resp.content)
Si el gateway solo ofrece una interfaz compatible con OpenAI, hay que cambiar la estructura de la petición o añadir una capa de adaptación; no basta con cambiar la base URL. Al elegir gateway, confirma tres cosas: si admite el protocolo nativo de Anthropic, cómo se asignan los nombres de modelo y si las políticas de límites y logs son transparentes.
9. Preguntas frecuentes
¿La API de Claude y la membresía web de Claude son lo mismo?
No. La web es una suscripción de producto orientada al usuario; la API se factura por uso y tiene un sistema de cuentas, cuotas y administración distinto. Las claves, la facturación y el consumo de la API se gestionan en Anthropic Console.
¿Se puede ver la clave completa después de crearla?
En la mayoría de los casos solo se muestra una vez al crearla. Después solo se ve el prefijo o el nombre, así que hay que guardarla de inmediato en un gestor de secretos; si se pierde, revoca la clave antigua y crea una nueva.
¿Por qué es obligatorio enviar max_tokens?
Messages API exige declarar explícitamente el límite de salida de cada respuesta, para controlar la longitud generada y los recursos. Si se omite, devuelve 400. Ajusta un valor razonable según la tarea; no lo pongas siempre al máximo.
¿Un 429 es cuota agotada o demasiada concurrencia?
Pueden ser ambas cosas. Revisa el cuerpo de la respuesta y retry-after: si aparece de forma concentrada en poco tiempo, suele ser un problema de velocidad o concurrencia; si es continuo y la cuota facturada es anómala, revisa el plan y el consumo. Las soluciones incluyen retroceso, reducción de concurrencia y separación de claves.
¿Un equipo necesita siempre un gateway?
No necesariamente. Si puede conectarse de forma estable, completar pagos y evaluar el cumplimiento, la conexión directa con el proveedor oficial es más simple. Evalúa un gateway cuando necesites facturación local, comprobantes, un punto de entrada multimodelo unificado u optimización de red, y confirma sus políticas de datos y de gestión de fallos.
Próximos pasos
Regístrate en ZSQH AI Gateway, valida la petición mínima a /v1/messages con una clave de prueba y después intégrala en tu negocio. Los modelos, el contexto y la facturación se rigen por precios de modelos.
Lecturas relacionadas:
