Autenticación
Cómo funcionan las claves de API de Half Off Dev: los cuatro sitios donde puede ir la clave, cómo probarla gratis, los errores 401 y buenas prácticas.
En Half Off Dev solo existe un tipo de credencial: una clave de API ligada a tu saldo prepago. La misma clave llama a Claude, GPT y Gemini, y la envías en la cabecera que tu SDK o tu CLI ya usan, así que no tienes que escribir código de autenticación.
Crear una clave#
Las claves se crean en la página API keys. Cada una es ho- seguido de 40 letras y números, y solo se muestra una vez. Half Off Dev guarda únicamente un hash, de modo que una clave perdida no se puede recuperar: revócala y genera otra.
Todos los ejemplos de esta documentación leen la clave de $HALFOFF_API_KEY:
export HALFOFF_API_KEY="ho-..."Los topes de gasto, las listas de modelos permitidos y las fechas de caducidad se explican en Claves de API.
Dónde puede ir la clave#
No tienes que elegir una cabecera especial para Half Off Dev: las cuatro formas siguientes se aceptan en todos los endpoints, así que deja lo que tu cliente envíe por defecto.
| Forma | Ejemplo | Quién la suele enviar |
|---|---|---|
| Token Bearer | Authorization: Bearer ho-... | SDK de OpenAI, Codex CLI, Claude Code con ANTHROPIC_AUTH_TOKEN, apps compatibles con OpenAI |
Cabecera x-api-key | x-api-key: ho-... | SDK de Anthropic |
Cabecera x-goog-api-key | x-goog-api-key: ho-... | SDK Google Gen AI, Gemini CLI |
Parámetro de consulta key | ?key=ho-... | Ejemplos REST de Gemini |
Si una petición lleva varias, Half Off Dev usa la primera que encuentre en este orden: Authorization: Bearer, x-api-key, x-goog-api-key y, por último, ?key=.
Mejor en cabeceras
Una URL con la clave dentro acaba copiada en logs de proxies y en el historial de la terminal. Usa ?key= solo si el cliente no permite enviar cabeceras.
Prueba una clave gratis#
Contar tokens valida la clave y el modelo igual que una petición real, pero no cobra nada. Si recibes un 200 con input_tokens, la clave está activa y puede usar ese modelo.
curl https://halfoff.dev/v1/messages/count_tokens \
-H "x-api-key: $HALFOFF_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "content-type: application/json" \
-d '{
"model": "claude-sonnet-5.5",
"messages": [{"role": "user", "content": "¿Funciona esta clave?"}]
}'Endpoints públicos#
El catálogo de modelos es abierto, así que puedes consultar ids y precios antes de registrarte. Si envías una clave a estos endpoints, se ignora.
| Endpoint | Devuelve |
|---|---|
GET /v1/models | Todos los modelos con tamaño de contexto, precios y grupos de canales |
GET /v1beta/models | El mismo catálogo en formato Gemini |
Cualquier petición a un modelo necesita clave, también el conteo de tokens.
Errores 401#
Si la clave falta, no existe, está revocada o ha caducado, recibes un 401 con la forma de error de la API que estabas llamando.
| Causa | Mensaje |
|---|---|
| La petición no lleva clave | Missing API key |
| Clave desconocida o revocada, o cuenta suspendida | Invalid or revoked API key |
| La clave ya pasó su fecha de caducidad | This API key has expired |
{"type": "error", "error": {"type": "authentication_error", "message": "Invalid or revoked API key"}}Una clave válida también puede ser rechazada por sus propios límites: 403 si el modelo no está en su lista permitida, 402 cuando agota su tope de gasto y 429 al alcanzar su límite de peticiones. Claves de API explica esos límites y Errores recoge todos los códigos.
Cómo cuidar tus claves#
- Solo en el servidor. La API acepta peticiones de cualquier origen, así que una clave incluida en una web o una app móvil la puede copiar y gastar cualquiera. Llama a Half Off Dev desde tu backend.
- Nunca en el repositorio. Lee las claves de variables de entorno o de un gestor de secretos y añade los archivos
.enva.gitignore. - Una clave por app y por entorno. Si se filtra la de pruebas, producción no corre peligro, y en Logs ves qué clave hizo cada petición.
- Limita las claves compartidas. Las que usen CI, scripts o compañeros deberían tener tope de gasto, lista de modelos permitidos y fecha de caducidad. Mira Claves de API.
- Rótalas con regularidad, y de inmediato si se va alguien que tenía acceso. Más consejos en Seguridad.