Políticas y documentación verificadas el 5 de noviembre de 2026. Todos los ejemplos de terminal usan Bash y sirven para macOS, Linux y entornos de desarrollo que utilicen Bash.
Después de contratar Max, Ultra o Team, debes vincular los créditos API concedidos a una organización de Claude Console para utilizarlos en tus propios programas o agentes.
Puedes completar el proceso en este orden:
Confirma la elegibilidad → vincula una organización Console → consulta los créditos concedidos → crea una API key → envía una petición pequeña → comprueba la organización y los registros de uso → configura claude -p.
Lo esencial es que coincidan la cuenta de suscripción, la organización Console, la API key y la ruta de facturación real de la petición. Recibir una respuesta del modelo solo demuestra que la petición funcionó; todavía debes comprobar qué organización y qué saldo se utilizaron.
1. Confirma cuánto puedes reclamar y quién debe hacerlo
El programa actual de créditos API mensuales concede estos importes:
| Plan o puesto | Créditos API mensuales | Destino de los créditos |
|---|---|---|
| Max | 100 USD | Una organización Console vinculada |
| Ultra | 200 USD | Una organización Console vinculada |
| Team Standard | 20 USD por puesto | Fondo común para todo el equipo |
| Team Premium | 100 USD por puesto | Fondo común para todo el equipo |
| Todo el equipo Team | Máximo de 500 USD | El mismo fondo de la organización |
Por ejemplo, con 3 puestos Standard y 2 Premium, la concesión mensual nominal es:
3 × 20 + 2 × 100 = 260 USDIncluso con 10 Premium se mantiene el máximo de 500 USD mensuales para todo el equipo.
Antes de reclamar los créditos debes cumplir dos condiciones: el plan está activo y en regla, y los nuevos suscriptores llevan al menos siete días en un plan elegible. Las suscripciones compradas en iOS o Android también pueden participar, pero los créditos se reclaman desde la web. No es necesario añadir antes una tarjeta de pago a Claude Platform.
Política oficial de créditos mensuales · Guía de la plataforma para reclamar y utilizar créditos
Comprueba también los permisos de ambos lados:
| Dónde | Identidad necesaria para reclamar |
|---|---|
| Suscripción Max / Ultra | El propio suscriptor |
| Suscripción Team | Primary Owner u Owner |
| Organización Console que recibe los créditos | Owner, Admin o Billing |
Estos siete días son el requisito para reclamar los créditos API; no permiten deducir cuándo termina la verificación automática de Ultra.
2. Vincula la organización Console y reclama los créditos desde la web
En Max y Ultra, entra por aquí:
En Team, un Owner o Primary Owner debe entrar en:
Sigue estos pasos:
- Busca el apartado API credits.
- Pulsa Link organization.
- Elige la organización Claude Console que recibirá los créditos. Si todavía no tienes una, puedes crearla siguiendo el proceso de la página.
- Comprueba el nombre de la organización y para qué se utilizará.
- Lee las condiciones y confirma la vinculación.
- Abre Billing en Console y comprueba que los créditos se han abonado.
Elige bien la organización antes de vincularla. Las reglas actuales permiten vincular un plan a una sola organización Console, y cada organización solo puede recibir estos créditos de un plan. Después no puedes cambiar la vinculación por tu cuenta: debes contactar con soporte.
Los miembros de Team no tienen que reclamarlos por separado. Una persona responsable con permisos vincula la organización; después, quienes utilicen sus API keys dentro de ella consumirán el mismo saldo.
Si no aparece la opción para reclamarlos, comprueba primero el plan, la antigüedad de la suscripción, la cuenta con la sesión iniciada y los roles de ambos lados; después consulta al soporte oficial.
3. Dónde consultar el saldo y qué campos revisar
Después de reclamar los créditos, abre:
Revisa primero Promotional credits y anota:
- El importe concedido en esta ocasión.
- El saldo disponible que muestra la página.
- La fecha de vencimiento.
- La organización Console seleccionada.
Después comprueba por separado el saldo comprado y la configuración de Auto-reload.
Los créditos mensuales se consumen antes que los comprados. El saldo no utilizado vence al terminar su ciclo y no se acumula; los planes anuales también reciben concesiones mensuales. Presta atención a la recarga automática: se activa según el saldo comprado, por lo que puede realizarse una recarga aunque todavía queden créditos concedidos.
Al conciliar el consumo, distingue estos tres tipos de cifras:
| Cifra | Qué permite comprobar |
|---|---|
| Saldo, concesiones y vencimientos de Billing | Cuántos créditos quedan, de dónde proceden y cuándo vencen |
| usage de la respuesta de una petición | Cuántos tokens ha utilizado esa petición |
| Informes Usage / Cost o estimación de costes de la CLI | Dónde se produjo el consumo y qué coste estimado o real generó |
usage no equivale directamente a un saldo en dólares. Tampoco total_cost_usd de la CLI demuestra que ese coste se haya descontado de los créditos concedidos. Los campos actuales de Cost Analytics expresan el coste antes de aplicar créditos, y los informes pueden actualizarse con retraso.
4. Crea una API key en el workspace correcto
Abre:
Para una práctica individual puedes seguir estos pasos:
- Confirma que la organización Console seleccionada es la que recibe los créditos.
- Pulsa Create key.
- Asigna un nombre reconocible, por ejemplo monthly-credit-demo.
- Establece la fecha de vencimiento que necesites.
- En Linked account, selecciona tu propia cuenta para crear una personal key.
- Elige un workspace normal de la API al que ya tengas acceso y limita la key a ese único workspace.
- Guarda la key que se muestra al crearla y anota la organización, el workspace y el nombre de la key.
La key solo se muestra completa una vez, al crearla. Una personal key basta para desarrollo individual; para servicios compartidos o sistemas de producción puedes adoptar después una service account según las normas de la organización.
Hay otros dos detalles de permisos:
- Poder reclamar créditos no implica poder crear una key. Billing se ocupa principalmente de facturación y uso; crear keys exige los permisos correspondientes en la organización y el workspace.
- Crear un workspace requiere un administrador de la organización. Un miembro normal debe elegir uno al que ya tenga acceso; si el botón no está disponible, pide al administrador que revise los roles y la pertenencia al workspace.
No elijas el workspace específico de Claude Code para crear manualmente la key de práctica: la documentación oficial indica que sus keys se gestionan mediante el inicio de sesión de Claude Code.
Todos los ejemplos siguientes utilizan una key para la que se seleccionó un único workspace al crearla. La API actual exige una cabecera de selección adicional a las keys sin esa limitación; no mezcles las dos formas de uso.
5. Prepara un entorno temporal de terminal
Te recomendamos practicar en un terminal independiente y mantener la key solo en la sesión actual.
Inicia primero Bash:
bash --noprofile --norcDespués ejecuta:
set +x
umask 077
unset ANTHROPIC_API_KEY
unset ANTHROPIC_AUTH_TOKEN CLAUDE_CODE_OAUTH_TOKEN ANTHROPIC_BASE_URL
unset CLAUDE_CODE_USE_BEDROCK CLAUDE_CODE_USE_VERTEX
unset CLAUDE_CODE_USE_FOUNDRY CLAUDE_CODE_USE_ANTHROPIC_AWS
unset CLAUDE_CODE_EFFORT_LEVEL
mkdir -p "$HOME/claude-api-credit-demo"
cd "$HOME/claude-api-credit-demo"Estos ajustes temporales dirigen explícitamente la práctica a la API directa. Una instalación de Claude Code administrada por una empresa puede seguir sujeta a políticas de gateway o proveedor de la organización. Si la ruta no coincide con la esperada, consúltalo con el administrador.
A continuación, ejecuta esta línea por separado, pega la key que acabas de crear y pulsa Intro. El contenido introducido no se mostrará:
read -r -s -p 'Pega la API key de la organización vinculada y pulsa Intro: ' ANTHROPIC_API_KEYUna vez introducida, ejecuta:
printf '\n'
export ANTHROPIC_API_KEYNo escribas la key real en los ejemplos del artículo, el código del script ni el historial de comandos. Tampoco necesitas imprimirla con echo para comprobarla.
6. Envía la primera petición pequeña con curl
Esta comprobación de conectividad utiliza claude-haiku-5-5, limita la salida y desactiva thinking. La combinación de parámetros es específica de ese modelo: si lo cambias, vuelve a comprobar qué parámetros admite.
Crea primero el archivo de la petición:
cat > request.json <<'JSON'
{
"model": "claude-haiku-5-5",
"max_tokens": 128,
"thinking": {
"type": "disabled"
},
"output_config": {
"effort": "low"
},
"messages": [
{
"role": "user",
"content": "Responde solo: conexión API correcta"
}
]
}
JSONDespués envía la petición:
curl --disable --silent --show-error \
--connect-timeout 10 --max-time 60 \
--dump-header response.headers \
--output response.json \
--write-out 'HTTP %{http_code}\n' \
--config - <<EOF
url = "https://api.anthropic.com/v1/messages"
request = "POST"
header = "Authorization: Bearer ${ANTHROPIC_API_KEY}"
header = "anthropic-version: 2026-10-21"
header = "content-type: application/json"
data-binary = "@request.json"
EOFEl comando genera dos archivos:
- response.json: cuerpo de la respuesta, con el contenido, el motivo de finalización y el uso de tokens.
- response.headers: cabeceras de respuesta para comprobar el identificador de la petición, la organización, el workspace y otros datos.
La key se transmite a curl por su entrada estándar y no se incluye directamente en los argumentos del comando. --disable aparece primero para impedir que una configuración .curlrc existente altere esta pequeña prueba.
La API oficial actual utiliza la versión 2026-10-21 y admite la API key en Authorization: Bearer. Una key limitada a un único workspace puede omitir la cabecera de selección de workspace.
Consulta el cuerpo de la respuesta:
python3 -m json.tool response.jsonComprueba especialmente:
- Si el estado HTTP es 200.
- Si content contiene texto.
- Si stop_reason indica una finalización normal o que se alcanzó max_tokens.
- Cuántos tokens de entrada, salida y caché declara realmente usage.
Extrae después las cabeceras que necesitas comprobar:
python3 - <<'PY'
from pathlib import Path
wanted = {
"request-id",
"anthropic-organization-id",
"anthropic-workspace-id",
}
for line in Path("response.headers").read_text(
errors="replace"
).splitlines():
name, sep, value = line.partition(":")
if sep and name.lower() in wanted:
print(name.lower() + ":", value.strip())
PYRelaciona los identificadores de organización y workspace devueltos con los registros de Console. La comprobación de la llamada queda completa cuando la petición funciona, la organización coincide y el uso aparece en el workspace previsto.
7. Utiliza los mismos créditos desde el SDK de Python
Si vas a integrar la API en tu programa, puedes utilizar el SDK oficial de Python. La documentación actual exige Python 3.10 o posterior.
Crea un entorno virtual en el directorio de práctica:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade anthropicCrea call_api.py:
import json
import os
import anthropic
with anthropic.Anthropic(
api_key=os.environ["ANTHROPIC_API_KEY"],
base_url="https://api.anthropic.com",
timeout=30.0,
max_retries=0,
) as client:
raw = client.messages.with_raw_response.create(
model="claude-haiku-5-5",
max_tokens=128,
thinking={"type": "disabled"},
output_config={"effort": "low"},
messages=[
{"role": "user", "content": "Responde solo: conexión API correcta"}
],
)
message = raw.parse()
for name in (
"request-id",
"anthropic-organization-id",
"anthropic-workspace-id",
):
print(name + ":", raw.headers.get(name, "(no devuelto)"))
print("model:", message.model)
print("stop_reason:", message.stop_reason)
for block in message.content:
if block.type == "text":
print(block.text)
print(json.dumps(message.usage.model_dump(), ensure_ascii=False))Ejecuta:
python call_api.pyraw.parse() analiza la respuesta que ya se ha recibido; no envía otra petición al modelo. El ejemplo desactiva los reintentos automáticos para facilitar la correspondencia entre una ejecución y una petición durante la primera comprobación. Más adelante, un sistema de producción puede definir los reintentos que necesite su negocio.
8. Configura claude -p para utilizar estos créditos
La documentación oficial especifica una condición importante de cobertura:
Puedes utilizar los créditos mensuales al ejecutar claude -p o Agent SDK por tu cuenta con una API key de la organización Console vinculada.
Si te autenticas con una suscripción de Claude, el consumo sigue correspondiendo al plan de suscripción. Las ejecuciones iniciadas desde Claude Code GitHub Action, una extensión de IDE o la aplicación de escritorio de Claude no cumplen esa condición de cobertura, aunque utilicen -p.
Por eso, realiza esta sección desde un terminal independiente del sistema operativo que hayas abierto tú y conserva la API key configurada en los pasos anteriores.
Comprueba primero la versión:
claude --versionEste artículo utiliza el ID completo del modelo Haiku 5.5, para el que la documentación oficial exige Claude Code v2.1.293 o posterior. Si no lo tienes instalado o tu versión es anterior, sigue las instrucciones oficiales de instalación y actualización correspondientes a tu método de instalación.
Instalación y actualización de Claude Code · Configuración de modelos de Claude Code
Puedes diagnosticar primero el origen de la autenticación:
claude auth statusEl campo authMethod del JSON actual ayuda a identificar el origen de la autenticación, por ejemplo api_key, claude.ai o third_party.
Sin embargo, api_key solo indica que se ha identificado ese tipo de autenticación. Por sí solo no demuestra que la key sea válida, pertenezca a la organización correcta o que los créditos concedidos ya se hayan abonado.
Ejecuta después una tarea mínima:
claude --bare -p 'Responde solo: conexión API correcta' \
--model claude-haiku-5-5 \
--effort low \
--tools '' \
--max-turns 1 \
--max-budget-usd 0.10 \
--output-format json \
--no-session-persistence > claude-result.jsonQué controla cada parámetro:
| Parámetro | Función en esta práctica |
|---|---|
| --bare | No lee OAuth ni el keychain del sistema; omite el descubrimiento automático de hooks, skills, plugins, MCP y otros componentes |
| -p | Ejecuta sin interacción y sale después de devolver el resultado |
| --model | Fija el modelo para no heredar la selección de la sesión habitual |
| --effort low | Solicita un esfuerzo de razonamiento bajo |
| --tools '' | Desactiva las herramientas integradas para comprobar primero solo la llamada de texto |
| --max-turns 1 | Limita el número de turnos del agente |
| --max-budget-usd 0.10 | Establece un umbral de coste estimado por el cliente |
| --output-format json | Conserva un resultado estructurado fácil de inspeccionar |
| --no-session-persistence | No guarda esta sesión para recuperarla posteriormente |
--bare sigue admitiendo configuraciones y credenciales de nube indicadas explícitamente, por lo que la comprobación previa del entorno sigue siendo importante. Aquí no se añaden MCP, plugins ni directorios adicionales.
Además, --max-budget-usd utiliza una estimación del cliente: no es un máximo absoluto que la factura no pueda superar. --max-turns tampoco equivale a un límite de tokens. Antes de ampliar las tareas, configura también los controles de gasto de Console.
Ejecución programática de Claude Code · Referencia de la CLI de Claude Code
Consulta el resultado:
python3 - <<'PY'
import json
from pathlib import Path
data = json.loads(Path("claude-result.json").read_text())
print("is_error:", data.get("is_error"))
print("result:", data.get("result"))
print("estimated_cost_usd:", data.get("total_cost_usd"))
print("usage:", data.get("usage"))
PYSi un campo no se devuelve, déjalo como desconocido en lugar de convertirlo automáticamente en cero. Si el comando falla al salir, revisa también la salida de error y el archivo de resultados. Que el paso de análisis no produzca salida no significa que no se haya enviado una petición.
9. Comprueba que la ruta de consumo sea la correcta
Después de la prueba pequeña, comprueba lo siguiente en este orden:
- Titularidad correcta de la key: se creó en la organización Console que recibe los créditos.
- Workspace correcto: seleccionaste el workspace previsto al crear la key y los identificadores de la respuesta API también coinciden.
- Entrada correcta: la API directa, o una ejecución propia de claude -p que cumple las condiciones oficiales.
- Registro de uso correcto: el workspace correspondiente de Console muestra ese consumo.
- Registros de saldo correctos: concilia Promotional credits, saldo comprado, abonos y vencimientos.
Si una organización tiene créditos concedidos y comprados, la plataforma consume primero los concedidos según sus reglas. No hace falta añadir un parámetro especial de «usar los créditos concedidos» a cada petición.
Los informes pueden actualizarse con retraso y el coste de una petición pequeña puede ser muy bajo. Si la interfaz no muestra un cambio visible inmediatamente, no repitas continuamente la ejecución para forzarlo.
10. Cómo resolver los problemas más comunes
| Síntoma | Qué comprobar primero |
|---|---|
| No aparece API credits | Plan, requisito de siete días, sesión iniciada y roles de ambos lados |
| Puedes reclamar créditos, pero Create key no está disponible | Roles de Console, pertenencia al workspace y permisos de creación |
| HTTP 401 | Que la key sea correcta y válida y esté exportada en el shell actual |
| HTTP 403 | Permisos de la key, del workspace y de acceso al modelo o recurso |
| HTTP 400 | Lee el tipo de error concreto y revisa parámetros, versión, workspace y límites de gasto aplicables |
| HTTP 402 / billing_error | Facturación, saldo y estado de los pagos de la organización |
| HTTP 404 | ID del modelo, endpoint y disponibilidad del recurso |
| HTTP 429 | Distingue las tasas de peticiones o tokens de los límites de gasto aplicables; consulta el error y la respuesta concretos |
| stop_reason es max_tokens | La salida alcanzó el límite; la petición puede haber funcionado, pero el contenido está incompleto |
| curl funciona, pero la CLI no | Versión de la CLI, entorno de la API key, ruta del proveedor o gateway y políticas de la organización |
| La CLI funciona, pero los créditos no parecen disminuir | Condiciones de cobertura, organización correcta y posible retraso o precisión de los informes |
No atribuyas todos los errores a falta de saldo. Del mismo modo, que quede saldo no elimina los límites de gasto de la organización, los presupuestos del workspace ni los límites de tasa.
La persona responsable de Team también debe asignar workspaces y permisos adecuados a cada proyecto y configurar alertas de gasto. Default Workspace no permite actualmente un límite de gasto independiente del workspace. Si necesitas un presupuesto por proyecto, un administrador debe crear un workspace normal de la API adecuado.
Al terminar la práctica, elimina la key de la sesión actual y sal de este Bash temporal:
unset ANTHROPIC_API_KEY
exitAsí terminan los ajustes temporales de este subshell y se conserva el entorno original del terminal padre.
Puedes descargar los ejemplos completos a continuación para revisarlos y utilizarlos en tu propio directorio de práctica. El código ha pasado comprobaciones de sintaxis y flujos sin conexión; no se han utilizado cuentas de lectores para realizar peticiones reales a modelos.