Primeros pasos
Autenticación
Autentique las solicitudes a la API de TokenLab con una clave API
API Keys
Las llamadas a modelos y los recursos privados requieren una API key. Los endpoints de descubrimiento públicos como GET /v1/models y GET /v1/models/{model} funcionan sin una. Una respuesta de descubrimiento exitosa no verifica que su clave funcione; siga la Guía de inicio rápido (Quickstart) para enviar una solicitud de modelo. Utilice la clave completa guardada; el prefijo en la lista de claves no puede autenticar.
Para endpoints compatibles con OpenAI, envíela como:
Authorization: Bearer sk-your-api-keyPara solicitudes /v1/messages compatibles con Anthropic, también puede usar:
x-api-key: sk-your-api-keyLas solicitudes /v1beta/* compatibles con Gemini también aceptan x-goog-api-key: sk-your-api-key. Prefiera un encabezado sobre el parámetro de consulta ?key=, ya que las URLs a menudo terminan en los registros (logs).
Management Tokens
Los endpoints de la API de gestión utilizan un tipo de token diferente:
Authorization: Bearer mt-your-management-tokenUtilice los Management Tokens solo con endpoints /v1/management/*. Abra API → Tokens para el espacio de trabajo seleccionado para crear o reemplazar un token. Guarde el token completo cuando se muestre; solo se visualiza una vez después de su creación o reemplazo.
Los Management Tokens no se pueden utilizar para la inferencia de modelos, y las API keys estándar sk-... no se pueden utilizar para la Management API.
Obtener una API key
- Inicie sesión en TokenLab Console
- Abra API Keys
- Cree una nueva clave
- Asígnele un nombre descriptivo
- Cópiela inmediatamente porque solo se muestra una vez
- Nunca exponga las API keys en código del lado del cliente
- Nunca suba las API keys a sistemas de control de versiones
- Utilice variables de entorno o un gestor de secretos
- Rote las claves periódicamente
- Elimine las claves no utilizadas
Usar una API key
Consulte la Guía de inicio rápido para obtener información sobre variables de entorno y una primera solicitud completa. Utilice el SDK que coincida con el formato de API elegido; mantenga las claves en el servidor.
Configuración de claves
Puede establecer estos parámetros en cada API key en la consola, y a través de la API de gestión:
| Configuración | Descripción |
|---|---|
| Límite de gasto | No limit permite que la clave utilice el saldo del espacio de trabajo. Fixed limit hace que la clave devuelva 402 quota_exceeded después de alcanzar el monto. |
| Modelos permitidos | La clave solo puede llamar a estos modelos. Otros modelos devuelven 403 model_not_allowed. Vacío significa que no hay restricción a nivel de clave. |
| Opción de entrega | Auto, Verified o Official para solicitudes desde esta clave. Vacío utiliza el valor predeterminado del espacio de trabajo. Consulte Facturación y precios. |
| Expiración | Después de este tiempo, la clave devuelve 401 expired_api_key. |
| Estado | Una clave inactive (pausada) devuelve 401 invalid_api_key. Una clave revoked no puede volver a habilitarse. |
Prefijo de clave
Todas las API keys de TokenLab comienzan con sk-.
Respuestas de error
| Código de estado | Tipo | Código | Descripción |
|---|---|---|---|
| 401 | invalid_api_key | invalid_api_key | La API key falta, es inválida, está inactiva o revocada |
| 401 | expired_api_key | expired_api_key | La clave ha expirado |
| 402 | insufficient_balance | insufficient_balance | El saldo de la cuenta es insuficiente |
| 402 | quota_exceeded | quota_exceeded | Se alcanzó el límite de uso de la API key |
| 403 | permission_error | model_not_allowed | La clave no tiene permiso para usar el modelo solicitado |
| 403 | permission_error | user_suspended, account_restricted | La cuenta no puede usar la API |
| 429 | rate_limit_exceeded | rate_limit_exceeded | Demasiados intentos de autenticación fallidos desde una dirección IP. Espere según Retry-After y corrija la clave; no cree bucles con 401 |
Ejemplo:
{
"error": {
"message": "Invalid API key",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}