Referencia de la API

Visión general

TokenLab es nativo primero y compatible con OpenAI. Usa rutas nativas del proveedor como POST /v1/messages para Anthropic y /v1beta/models/...:generateContent para Gemini cuando necesites comportamiento nativo, y endpoints /v1 compatibles con OpenAI cuando migres SDKs o herramientas de estilo OpenAI. POST /v1/responses sigue siendo una ruta avanzada opcional para comportamiento específico de Responses.

URL base

https://api.tokenlab.sh

Autenticación

Las solicitudes a modelos usan una clave API de TokenLab. El encabezado estándar de autenticación es:

Authorization: Bearer sk-your-api-key

GET /v1/models, GET /v1/models/{model} y GET /v1/pricing son públicos y no requieren clave. Anthropic Messages también acepta x-api-key; Gemini acepta x-goog-api-key o ?key= además de Bearer. /v1/management/* requiere un token de gestión (mt-...).

Obtén tu clave API en el Panel de control.

Las solicitudes de generación aceptan X-TokenLab-Delivery-Policy: auto | verified | official. El encabezado prevalece sobre la clave API y esta sobre el espacio de trabajo. auto prioriza TokenLab Verified y después Official si hace falta; se cobra según el modo que completa la solicitud. verified usa precios TokenLab; official se basa en precios públicos del fabricante, al precio mostrado en TokenLab. Realtime usa la configuración de la clave o del espacio de trabajo y no admite cambios por consulta. Un encabezado inválido devuelve 400; un modo no disponible devuelve 503 delivery_tier_unavailable y un ID de solicitud.

Acerca del Playground interactivo: el playground en este sitio de documentación es solo para fines de demostración y no admite ingresar claves API. Para probar la API, por favor utiliza:

cURL - Copia los comandos de ejemplo y reemplaza sk-your-api-key con tu clave real
Postman - Importa nuestra OpenAPI spec
SDK - Usa el SDK de OpenAI/Anthropic con nuestra URL base

Endpoints compatibles

Chat y generación de texto

Punto de acceso	Método	Descripción
`/v1/chat/completions`	POST	Chat completions compatibles con OpenAI
`/v1/messages`	POST	API de mensajes compatible con Anthropic
`/v1/responses`	POST	API de respuestas de OpenAI

Embeddings y rerank

Punto de acceso	Método	Descripción
`/v1/embeddings`	POST	Crear embeddings de texto
`/v1/rerank`	POST	Reordenar documentos

Imágenes

Punto de acceso	Método	Descripción
`/v1/images/generations`	POST	Generar imágenes a partir de texto
`/v1/images/edits`	POST	Editar imágenes
`/v1/images/generations/{id}`	GET	Ruta de estado de tarea para respuestas de imagen basadas en tareas

Los modelos de imagen pueden devolver una imagen terminada o una tarea asíncrona. Si la respuesta incluye poll_url, usa esa URL para consultar la tarea.

Audio

Punto de acceso	Método	Descripción
`/v1/audio/speech`	POST	Texto a voz (TTS)
`/v1/audio/transcriptions`	POST	Voz a texto (STT)

Tiempo real

Endpoint	Método	Descripción
`/v1/realtime?model={model}`	WS	Sesiones WebSocket en tiempo real

Usa /v1/realtime para solicitudes de upgrade WebSocket. Un GET /v1/realtime normal devuelve metadatos del endpoint para clientes que no pueden inspeccionar rutas WebSocket directamente. No es la superficie REST de OpenAI Realtime; los endpoints de client secret, translation client secret, Calls y legacy beta session no se exponen actualmente.

Video

Punto de acceso	Método	Descripción
`/v1/videos/generations`	POST	Crear tarea de generación de video
`/v1/tasks/{id}`	GET	Obtener estado de tarea asincrónica para trabajos de video
`/v1/videos/generations/{id}`	GET	Ruta de estado de tarea de video compatible con versiones anteriores

Para clientes nuevos, prefiera /v1/tasks/{id} y siga el poll_url devuelto por las respuestas de creación. Mantenga /v1/videos/generations/{id} solo por compatibilidad con versiones anteriores.

Tareas asincrónicas

Punto de acceso	Método	Descripción
`/v1/tasks/{id}`	GET	Endpoint unificado de estado de tareas asincrónicas. Recomendado cuando se sigue un `poll_url` devuelto

Este endpoint no está limitado a video, música y 3D. Algunas tareas de imagen también pueden usar /v1/tasks/{id} como la ruta canónica de polling.

Música

Punto de acceso	Método	Descripción
`/v1/music/generations`	POST	Crear tarea de generación de música
`/v1/music/generations/{id}`	GET	Ruta de estado específica para música

Para clientes nuevos, prefiera primero el poll_url devuelto. Si necesitas un endpoint fijo de estado de tarea, usa /v1/tasks/{id}; mantén /v1/music/generations/{id} para rutas de compatibilidad específicas de música.

Generación 3D

Punto de acceso	Método	Descripción
`/v1/3d/generations`	POST	Crear tarea de generación de modelo 3D
`/v1/3d/generations/{id}`	GET	Ruta de estado específica para 3D

Para clientes nuevos, prefiera primero el poll_url devuelto. Si necesitas un endpoint fijo de estado de tarea, usa /v1/tasks/{id}; mantén /v1/3d/generations/{id} para rutas de compatibilidad específicas de 3D.

Modelos

Punto de acceso	Método	Descripción
`/v1/models`	GET	Listar todos los modelos disponibles
`/v1/models/{model}`	GET	Obtener información de un modelo específico

Gemini (v1beta)

Soporte nativo para el formato de la API Google Gemini:

Punto de acceso	Método	Descripción
`/v1beta/models/{model}:generateContent`	POST	Generar contenido (formato Gemini)
`/v1beta/models/{model}:streamGenerateContent`	POST	Generar contenido en streaming (formato Gemini)

Los endpoints de Gemini admiten la autenticación mediante el parámetro de consulta ?key= además del token Bearer estándar.

Formato de respuesta

Cada endpoint conserva su formato API. Los ejemplos de éxito y error siguientes usan el formato Chat Completions.

Respuesta exitosa

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "Hello!"}, "finish_reason": "stop"}],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Transparencia de enrutamiento

TokenLab no expone detalles de proveedor, canal, política ni credenciales en los cuerpos de respuesta públicos. No dependas de _routing ni de otros campos internos de enrutamiento como campos admitidos por la API.

Para depuración y soporte, usa los encabezados públicos de respuesta cuando estén presentes:

Encabezado	Descripción
`X-Routing-Time-MS`	Tiempo de selección de ruta, cuando esté disponible
`X-Request-ID`	Identificador de solicitud para soporte y depuración, cuando esté disponible
`X-Task-ID`	Identificador público de tarea asíncrona para respuestas basadas en tareas, cuando esté disponible
`X-Billing-Transaction-ID`	Identificador de transacción de facturación después de la facturación final, cuando esté disponible

Respuesta de error

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}

Límites de tasa

Los límites de tasa son basados en roles y configurables por los administradores. Valores predeterminados:

Rol	Solicitudes/min
User	1,000
Partner	10,000
VIP	10,000

Contacta con el soporte para límites de tasa personalizados. Los valores exactos pueden variar según la configuración de la cuenta.

Cuando se exceden los límites de tasa, la API devuelve un código de estado 429 con un encabezado Retry-After que indica cuánto tiempo esperar.

Especificación OpenAPI

Descarga la especificación completa OpenAPI 3.1

Referencia de la API

Visión generalCopy Anchor Link

URL baseCopy Anchor Link

AutenticaciónCopy Anchor Link

Endpoints compatiblesCopy Anchor Link

Chat y generación de textoCopy Anchor Link

Embeddings y rerankCopy Anchor Link

ImágenesCopy Anchor Link

AudioCopy Anchor Link

Tiempo realCopy Anchor Link

VideoCopy Anchor Link

Tareas asincrónicasCopy Anchor Link

MúsicaCopy Anchor Link

Generación 3DCopy Anchor Link

ModelosCopy Anchor Link

Gemini (v1beta)Copy Anchor Link

Formato de respuestaCopy Anchor Link

Respuesta exitosaCopy Anchor Link

Transparencia de enrutamientoCopy Anchor Link

Respuesta de errorCopy Anchor Link

Límites de tasaCopy Anchor Link

Especificación OpenAPICopy Anchor Link

Especificación OpenAPI

En esta página

Visión general

URL base

Autenticación

Endpoints compatibles

Chat y generación de texto

Embeddings y rerank

Imágenes

Audio

Tiempo real

Video

Tareas asincrónicas

Música

Generación 3D

Modelos

Gemini (v1beta)

Formato de respuesta

Respuesta exitosa

Transparencia de enrutamiento

Respuesta de error

Límites de tasa

Especificación OpenAPI