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-key

Para solicitudes /v1/messages compatibles con Anthropic, también puede usar:

x-api-key: sk-your-api-key

Las 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-token

Utilice 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

  1. Inicie sesión en TokenLab Console
  2. Abra API Keys
  3. Cree una nueva clave
  4. Asígnele un nombre descriptivo
  5. 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ónDescripción
Límite de gastoNo 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 permitidosLa 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 entregaAuto, Verified o Official para solicitudes desde esta clave. Vacío utiliza el valor predeterminado del espacio de trabajo. Consulte Facturación y precios.
ExpiraciónDespués de este tiempo, la clave devuelve 401 expired_api_key.
EstadoUna 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 estadoTipoCódigoDescripción
401invalid_api_keyinvalid_api_keyLa API key falta, es inválida, está inactiva o revocada
401expired_api_keyexpired_api_keyLa clave ha expirado
402insufficient_balanceinsufficient_balanceEl saldo de la cuenta es insuficiente
402quota_exceededquota_exceededSe alcanzó el límite de uso de la API key
403permission_errormodel_not_allowedLa clave no tiene permiso para usar el modelo solicitado
403permission_erroruser_suspended, account_restrictedLa cuenta no puede usar la API
429rate_limit_exceededrate_limit_exceededDemasiados 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"
  }
}

En esta página