Base

Referencia de la API

Endpoints, autenticación, encabezados de respuesta y errores

Descripción general

TokenLab admite endpoints compatibles con OpenAI, además de los formatos de solicitud de Anthropic y Gemini. Los clientes de OpenAI existentes pueden usar /v1; elija otro formato solo cuando su aplicación necesite un comportamiento específico de esa API. POST /v1/responses es opcional y depende de la compatibilidad del modelo.

URL base

https://api.tokenlab.sh

Autenticación

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

Authorization: Bearer sk-your-api-key

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

Obtenga su clave de API desde la Consola.

Política de entrega

Las solicitudes de generación aceptan X-TokenLab-Delivery-Policy: auto | verified | official. Un encabezado de solicitud anula la configuración de la clave de API, la cual a su vez anula el valor predeterminado del Workspace.

  • Auto utiliza TokenLab Verified cuando está disponible, y luego Official si es necesario. Usted paga por la opción que completa su solicitud.
  • TokenLab Verified es una entrega verificada por TokenLab. Se aplica el precio de Verified.
  • Official factura al precio Official, que es el precio publicado por el creador del modelo.
  • Las sesiones en tiempo real utilizan la clave de API o la configuración del Workspace y no aceptan una anulación en la solicitud.

Un encabezado no válido devuelve 400. Si la opción solicitada no está disponible, TokenLab devuelve 503 delivery_tier_unavailable y un ID de solicitud. Lea retryable: cuando la operación seleccionada no tiene disponibilidad, es false. No repita la misma solicitud sin cambios.

Las páginas de la API con un formulario de solicitud aceptan su clave de API de TokenLab y envían solicitudes reales. Estas solicitudes utilizan el saldo y los límites de su cuenta. También puede usar cURL, Postman o un SDK.

Endpoints admitidos

Chat y generación de texto

EndpointMétodoDescripción
/v1/chat/completionsPOSTCompletado de chat compatible con OpenAI
/v1/messagesPOSTMensajes compatibles con Anthropic
/v1/messages/count_tokensPOSTContar los tokens de entrada de una solicitud de Mensajes
/v1/messages/batchesPOST, GETCrear y listar lotes de mensajes
/v1/messages/batches/{message_batch_id}GET, DELETERecuperar o eliminar un lote de mensajes
/v1/messages/batches/{message_batch_id}/resultsGETLeer los resultados
/v1/messages/batches/{message_batch_id}/cancelPOSTCancelar un lote de mensajes
/v1/responsesPOSTAPI de respuestas de OpenAI
/v1/responses/{id}GET, DELETERecuperar o eliminar una respuesta almacenada
/v1/responses/compactPOSTCompactar el contexto de una conversación de respuestas
/v1/translationsPOSTTraducción de texto a texto

Embeddings y Rerank

EndpointMétodoDescripción
/v1/embeddingsPOSTCrear embeddings de texto
/v1/multimodal/embeddingsPOSTCrear embeddings con un modelo de embedding multimodal
/v1/rerankPOSTReclasificar (rerank) documentos

Decisiones

EndpointMétodoDescripción
/v1/systemonePOSTEvaluar preguntas de decisión tipadas

Archivos y lotes

EndpointMétodoDescripción
/v1/filesPOST, GETSubir y listar archivos
/v1/files/{file_id}GET, DELETERecuperar o eliminar un archivo
/v1/files/{file_id}/contentGETDescargar el contenido de un archivo
/v1/batchesPOST, GETCrear y listar lotes
/v1/batches/{batch_id}GETRecuperar un lote
/v1/batches/{batch_id}/cancelPOSTCancelar un lote

Imágenes

EndpointMétodoDescripción
/v1/images/generationsPOSTGenerar imágenes a partir de texto
/v1/images/editsPOSTEditar imágenes
/v1/images/variationsPOSTCrear variaciones de imágenes
/v1/images/generations/{id}GETRuta de estado de compatibilidad para respuestas de imágenes basadas en tareas

Los modelos de imagen pueden devolver una imagen terminada o una tarea asíncrona. Si la respuesta incluye status: "pending" o un ID de tarea, consulte GET /v1/tasks/{id}.

Audio

EndpointMétodoDescripción
/v1/audio/speechPOSTTexto a voz (TTS)
/v1/audio/transcriptionsPOSTVoz a texto (STT)
/v1/audio/translationsPOSTTraducir voz a texto en inglés

Tiempo real

EndpointMétodoDescripción
/v1/realtime?model={model}WSSesiones WebSocket en tiempo real

Utilice /v1/realtime para actualizaciones de WebSocket. Un GET /v1/realtime simple devuelve metadatos del endpoint. Esta no es la superficie REST de OpenAI Realtime; los secretos de cliente, las llamadas (Calls) y los endpoints de sesión beta heredados no están disponibles.

Video

EndpointMétodoDescripción
/v1/videos/generationsPOSTCrear tarea de generación de video
/v1/videos/generations/{id}GETRuta de estado de compatibilidad
/v1/videos/assetsPOST, GETCrear y listar activos de material de Seedance
/api/v3/contents/generations/tasksPOST, GETTareas de Seedance con el formato de solicitud de Volcengine

Consulte GET /v1/tasks/{id} con el id de la tarea. /v1/videos/generations/{id} sigue estando disponible para integraciones existentes.

Tareas asíncronas

EndpointMétodoDescripción
/v1/tasks/{id}GETEstado de cualquier tarea asíncrona
/v1/tasks/{id}DELETECancelar una tarea asíncrona

Consulte GET /v1/tasks/{id} para cada tarea asíncrona: imágenes, video, música, 3D, Worlds y transcripción de audio asíncrona. Utilice el id o task_id de la respuesta de creación. Una respuesta de creación de Worlds devuelve una poll_url bajo /v1/worlds/generations/{id}; consulte /v1/tasks/{id} allí también. Las rutas de estado por modalidad en esta página son endpoints de compatibilidad para integraciones existentes.

Música

EndpointMétodoDescripción
/v1/music/generationsPOSTCrear tarea de generación de música
/v1/music/generations/{id}GETRuta de estado de compatibilidad

Generación 3D

EndpointMétodoDescripción
/v1/3d/generationsPOSTCrear tarea de generación de modelo 3D
/v1/3d/generations/{id}GETRuta de estado de compatibilidad

Worlds

EndpointMétodoDescripción
/v1/worlds/generationsPOSTCrear una tarea de generación de mundo
/v1/worlds/listPOSTListar mundos
/v1/worlds/{id}GET, DELETERecuperar o eliminar un mundo
/v1/worlds/media-assets/prepare-uploadPOSTPreparar una subida de activo multimedia

Modelos y precios

EndpointMétodoDescripción
/v1/modelsGETListar todos los modelos disponibles
/v1/models/{model}GETObtener información de un modelo específico
/v1/models/{model}/pricingGETObtener los precios de un modelo
/v1/pricingGETListar precios de modelos

Gemini (v1beta)

Soporte nativo para el formato de API de Google Gemini:

EndpointMétodoDescripción
/v1beta/modelsGETListar modelos que aceptan solicitudes de Gemini
/v1beta/models/{model}GETObtener un modelo
/v1beta/models/{model}:generateContentPOSTGenerar contenido
/v1beta/models/{model}:streamGenerateContentPOSTGenerar contenido en streaming
/v1beta/models/{model}:countTokensPOSTContar tokens
/v1beta/files, /v1beta/cachedContentsPOST, GET, DELETEArchivos y contenido en caché de Gemini

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

Gestión

/v1/management/* gestiona el saldo, las claves de API y los webhooks con un token de gestión. Consulte la API de gestión.

Formato de respuesta

Cada endpoint conserva su formato de API. Los ejemplos de éxito y error a continuación utilizan el formato de Chat Completions.

Respuesta de éxito

{
  "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
  }
}

Encabezados de respuesta

Utilice estos encabezados cuando estén presentes.

EncabezadoDescripción
X-Request-IDIdentificador de solicitud para soporte y depuración
X-Routing-Time-MSSin streaming: tiempo total en milisegundos hasta que llega la respuesta del upstream, incluida su cola e inferencia. Streaming: siempre 0. No es una medición de enrutamiento ni de cola.
X-Task-IDIdentificador público de tarea asíncrona para respuestas basadas en tareas
X-Billing-Transaction-IDIdentificador de transacción de facturación después de la facturación final

Los rechazos de solicitudes oficiales pueden incluir upstream con el error reportado por el servicio y el nombre público del servicio. Consulte Manejo de errores de API.

Respuesta de error

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

Límites de tasa

Los límites dependen del nivel de la cuenta y se aplican por clave de API. Una respuesta 429 incluye Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset. Consulte Límites de tasa para conocer los niveles y cómo reintentar.

Especificación OpenAPI

Especificación OpenAPI

Descargue la especificación completa de OpenAPI 3.1

En esta página