Cómo Obtener una Clave API de Anthropic y Realizar tu Primera Solicitud a Claude

Una clave API de Anthropic es la credencial que envías con cada solicitud a la API de Claude. Comienza con sk-ant-, la creas en la Consola de Claude y factura el uso contra los créditos prepagados de tu organización. Si nunca has usado una, nuestra guía introductoria sobre qué es una clave API cubre la idea general. Esta guía cubre la específica: crear una cuenta de Consola, cargar créditos, generar una clave con el alcance correcto, enviar la primera solicitud de Mensajes con curl y el SDK de Python, y mantener la clave fuera de problemas después.

La página oficial de Anthropic obtén tu clave API te dice dónde está el botón. No te dice por qué la primera solicitud devuelve un 401, qué ID de modelo está vigente o cómo probar la clave sin pegarla en el historial de tu shell. Eso es lo que cubre el resto de este documento.

Lo que necesitas antes de empezar

• Un correo electrónico para la Consola de Claude en platform.claude.com (console.anthropic.com ahora redirige allí).

• Una tarjeta de pago. La API es de prepago, y solo un rol de Administrador o Facturación puede comprar créditos.
• curl, o Python 3.10+ para el ejemplo del SDK.
• Apidog para almacenar la clave como una variable local y guardar la solicitud como una prueba repetible. El plan gratuito cubre equipos de hasta cuatro personas.

Paso 1: crear una cuenta de Consola de Claude

Regístrate en platform.claude.com. Eso crea una organización con un Espacio de Trabajo Predeterminado, y tus claves, créditos y límites de tarifa dependen de ella. Si un compañero de equipo ya creó una, pide una invitación en lugar de crear una segunda organización: los créditos y los niveles de uso no se transfieren.

Paso 2: añadir créditos antes de tu primera llamada

Sí, los créditos van primero. Los documentos de facturación de Anthropic son claros: compra créditos antes de usar la API, y con un saldo cero ni la API ni el playground funcionan. Los nuevos usuarios obtienen una pequeña cantidad de créditos gratuitos para probar, así que verifica tu saldo antes de comprar, pero trátalo como un bono en lugar de un plan.

Abre Configuración > Facturación y haz clic en Comprar créditos. Activa la recarga automática si estás ejecutando algo sin supervisión. Consulta cómo comprar créditos para los pasos actuales. Tu organización también se ubica en un nivel de uso con un límite de gasto mensual, cubierto en la sección de límites de tarifa.

Paso 3: crear la clave API

Ve a Configuración > Claves API y haz clic en Crear clave. Cuatro opciones importan:

• Nombre: nómbrala según la aplicación, no la persona. orders-service-staging es mejor que mi clave.
• Expiración: de 3 horas a 30 días, personalizada o Nunca. Elige una vida útil corta para las pruebas; no se puede cambiar después.
• Cuenta vinculada: tú mismo para una clave personal, una cuenta de servicio para cualquier cosa compartida. Una clave personal muere cuando abandonas la organización.
• Espacio de trabajo: limítala a un espacio de trabajo y podrás omitir el encabezado anthropic-workspace-id. Una clave multi-espacio de trabajo debe enviarlo en cada solicitud o recibirás un 400.

La Consola muestra la clave completa exactamente una vez, así que cópiala directamente en tu gestor de secretos. No hay botón para revelar. Si Crear clave está deshabilitado, tu rol no puede crear claves; pregunta a un administrador.

Paso 4: los tres encabezados que necesita cada solicitud

Cada llamada a POST https://api.anthropic.com/v1/messages lleva tres encabezados.

Los SDKs oficiales envían los tres por ti. Los clientes HTTP y API puros necesitan que se especifiquen, que es de donde provienen la mayoría de los fallos de la primera solicitud. Referencia completa: Visión general de la API de Claude.

Paso 5: envía tu primera solicitud de Mensajes

El cuerpo necesita model, max_tokens y messages. Usa un ID de modelo actual: a partir de septiembre de 2026, esos son claude-opus-5 (el predeterminado recomendado), claude-fable-5-1 (el más capaz), claude-sonnet-5 y claude-haiku-4-5. Los IDs antiguos 3.x y 4.x devuelven 404 o apuntan a modelos retirados, y los IDs actuales no llevan sufijo de fecha. El tutorial de la API de Claude Opus 5 profundiza en el pensamiento, el esfuerzo y el streaming.

curl

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

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-opus-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Escribe una descripción OpenAPI de una sola frase para POST /orders, que crea un pedido y devuelve 201."}
    ]
  }'

Una respuesta exitosa, recortada:

{
  "id": "msg_01...",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [{"type": "text", "text": "Crea un nuevo pedido y lo devuelve con un estado 201."}],
  "stop_reason": "end_turn",
  "usage": {"input_tokens": 31, "output_tokens": 24}
}

Lee el texto de content[].text, verifica que stop_reason sea end_turn y conserva usage para el seguimiento de costos. El encabezado de respuesta request-id es lo que el soporte técnico solicita cuando algo falla.

Python SDK

pip install anthropic

import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY del entorno

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": "Escribe una descripción OpenAPI de una sola frase para POST /orders, que crea un pedido y devuelve 201.",
    }],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

El SDK lee ANTHROPIC_API_KEY, añade los encabezados de versión y tipo de contenido, y reintenta los códigos 429 y 5xx dos veces con retroceso exponencial. Nunca pases la clave como una cadena literal; la variable de entorno es el objetivo principal.

Paso 6: almacena y prueba la clave en Apidog

Una clave pegada en una shell permanece en tu archivo de historial. Una clave almacenada en una solicitud compartida se sincroniza con los compañeros de equipo. Apidog separa los dos: la estructura de la solicitud es compartida, el secreto permanece en tu máquina.

Almacena la clave como una variable local. Abre Gestión de Entornos, crea un entorno llamado Anthropic y añade una variable ANTHROPIC_API_KEY. Deja el valor compartido como SET_LOCALLY y pega la clave real en el valor local, que permanece en la caché de tu cliente y nunca se sincroniza. Nuestra guía sobre entornos y variables secretas de Apidog cubre las reglas de alcance.

Establece los encabezados una vez. En el mismo panel, añade dos parámetros globales bajo Encabezados: x-api-key configurado como {{ANTHROPIC_API_KEY}}, y anthropic-version configurado como 2023-06-01. Se aplican a cada solicitud en el proyecto, y Apidog añade content-type automáticamente para un cuerpo JSON.

Envía la primera solicitud. Nueva solicitud, POST a https://api.anthropic.com/v1/messages, pega el cuerpo JSON del ejemplo de curl, envía. Abre la pestaña Solicitud Real para confirmar que ambos encabezados se enviaron con la variable resuelta. Esa pestaña es la forma más rápida de demostrar que un 401 es un problema de encabezado, no un problema de clave.

Guárdalo como una prueba. Guarda la solicitud como un caso de endpoint, luego añade tres aserciones: estado igual a 200, stop_reason igual a end_turn y usage.output_tokens mayor que 0. Ejecútalo desde la CLI de Apidog e inyecta la clave desde tu almacén de secretos de CI en tiempo de ejecución. Esa es una prueba rápida de un clic para la clave, los encabezados y el ID del modelo. Descarga Apidog para seguir los pasos; el plan gratuito incluye cuatro puestos.

Límites de tarifa y lo que cuesta una solicitud

Los límites son por organización y por modelo: solicitudes por minuto (RPM), tokens de entrada por minuto (ITPM) y tokens de salida por minuto (OTPM). Solo la entrada no almacenada en caché cuenta para ITPM, por lo que el almacenamiento en caché de las indicaciones aumenta el rendimiento sin cambiar de nivel. De la documentación de límites de tarifa:

Sonnet 5 y Haiku 4.5 comparten los números de Opus 5 en cada nivel. Cada respuesta lleva los encabezados anthropic-ratelimit-*-remaining y -reset, para que puedas monitorear el margen sin consultar la Consola.

Por millón de tokens, de la página de precios: Opus 5 cuesta $5 de entrada / $25 de salida, Sonnet 5 $2 / $10, Fable 5.1 $10 / $50, Haiku 4.5 $1 / $5. Las lecturas de caché cuestan el 10% de la entrada (2.5% en Fable 5.1) y la API de Batch reduce a la mitad ambos lados. Esa primera solicitud curl cuesta una fracción de centavo.

Errores comunes y cómo solucionarlos

Los errores se devuelven como JSON con un error.type y un request_id. La referencia de errores enumera todos los códigos; estos son los que encontrarás primero.

Higiene de la clave: rotación, alcance y nunca en el código del cliente

Nunca envíes la clave a un navegador o aplicación móvil. Cualquier cosa en un paquete JavaScript o un APK es pública en cuestión de minutos. Pon la llamada detrás de tu propio backend. Para las aplicaciones de Apple que deben llamar a Claude directamente, App Attest emite tokens de corta duración a las compilaciones verificadas en lugar de una clave estática.

Una clave por aplicación y entorno. Separar las claves de staging y producción en espacios de trabajo distintos te permite limitar el gasto de staging y revocar una sin afectar la otra.

Rota la clave según un cronograma. Crea la nueva clave, despliégala, confirma que funciona y luego elimina la antigua. Deshabilitar es reversible; Eliminar es permanente. Si sospechas una fuga, deshabilita primero e investiga después. Un escáner de secretos en tu repositorio detecta claves que se hayan subido antes de que alguien se diera cuenta.

Prefiere credenciales de corta duración en producción. La Federación de Identidades de Carga de Trabajo intercambia el token de identidad de tu proveedor de la nube por un token de Claude de corta duración, por lo que no hay ninguna cadena sk-ant- que pueda filtrarse.

Preguntas frecuentes

¿Es una clave API de Anthropic lo mismo que una clave API de Claude?

Sí. La Consola, los SDKs y la documentación ahora dicen “API de Claude”, y el formato y los encabezados de la clave son idénticos. Tutoriales antiguos que dicen “clave API de Anthropic” se refieren a la misma credencial.

¿Puedo obtener una clave API de Anthropic gratis?

Crear la clave es gratis. Usarla consume créditos prepagados, y la página de precios de Anthropic dice que los nuevos usuarios obtienen una pequeña cantidad de créditos gratuitos para probar. Si intentas ejecutar cargas de trabajo reales sin pagar, lee nuestro análisis honesto sobre el acceso gratuito a la API de Claude antes de construir cualquier cosa a su alrededor.

¿Una suscripción a Claude Pro o Max incluye acceso a la API?

No. Las suscripciones de Claude.ai y los créditos de la API de la Consola se facturan por separado. Necesitas una organización en la Consola con créditos, incluso si ya pagas por Claude.ai.

¿Qué sucede cuando mi clave expira?

Las solicitudes devuelven 401 authentication_error. Las claves expiradas no se pueden reactivar, así que crea una nueva y actualiza la variable de entorno. Anthropic envía correos electrónicos al creador de la clave siete días y un día antes del vencimiento en claves con una vida útil suficientemente larga.

Siguiente paso

Crea la clave con una expiración de 7 días, colócala en una variable local de Apidog, ejecuta la prueba de humo, y solo entonces intégrala en el código. Si eso pasa, la credencial, los encabezados y el ID del modelo son correctos, y cada 401 posterior es un problema real en lugar de un error tipográfico.