Core
API Reference
Endpoints, authentication, response headers, and errors
Overview
TokenLab supports OpenAI-compatible endpoints plus Anthropic and Gemini request formats. Existing OpenAI clients can use /v1; choose another format only when your application needs behavior specific to that API. POST /v1/responses is optional and depends on model support.
Base URL
https://api.tokenlab.shAuthentication
Model requests use a TokenLab API key. The standard authentication header is:
Authorization: Bearer sk-your-api-keyGET /v1/models, GET /v1/models/{model}, GET /v1/models/{model}/pricing, and GET /v1/pricing are public and need no key. Anthropic Messages also accepts x-api-key; Gemini accepts x-goog-api-key or ?key= as well as Bearer authentication. /v1/management/* requires a management token (mt-...).
Get your API key from the Console.
Delivery policy
Generation requests accept X-TokenLab-Delivery-Policy: auto | verified | official. A request header overrides the API key setting, which overrides the Workspace default.
Autouses TokenLab Verified when available, then Official if needed. You pay for the option that completes your request.TokenLab Verifiedis delivery verified by TokenLab. The Verified price applies.Officialbills the Official price, which is the model maker's published price.- Realtime sessions use the API key or Workspace setting and do not accept a request override.
An invalid header returns 400. If the requested option is unavailable, TokenLab returns 503 delivery_tier_unavailable and a request ID. Read retryable: when the selected operation has no supply, it is false. Do not repeat the same request unchanged.
API pages with a request form accept your TokenLab API key and send real requests. These requests use your account balance and limits. You can also use cURL, Postman, or an SDK.
Supported Endpoints
Chat & Text Generation
| Endpoint | Method | Description |
|---|---|---|
/v1/chat/completions | POST | OpenAI-compatible chat completions |
/v1/messages | POST | Anthropic-compatible Messages |
/v1/messages/count_tokens | POST | Count the input tokens of a Messages request |
/v1/messages/batches | POST, GET | Create and list Message Batches |
/v1/messages/batches/{message_batch_id} | GET, DELETE | Retrieve or delete a Message Batch |
/v1/messages/batches/{message_batch_id}/results | GET | Read the results |
/v1/messages/batches/{message_batch_id}/cancel | POST | Cancel a Message Batch |
/v1/responses | POST | OpenAI Responses API |
/v1/responses/{id} | GET, DELETE | Retrieve or delete a stored response |
/v1/responses/compact | POST | Compact the context of a Responses conversation |
/v1/translations | POST | Text-to-text translation |
Embeddings & Rerank
| Endpoint | Method | Description |
|---|---|---|
/v1/embeddings | POST | Create text embeddings |
/v1/multimodal/embeddings | POST | Create embeddings with a multimodal embedding model |
/v1/rerank | POST | Rerank documents |
Decisions
| Endpoint | Method | Description |
|---|---|---|
/v1/systemone | POST | Evaluate typed decision questions |
Files & Batches
| Endpoint | Method | Description |
|---|---|---|
/v1/files | POST, GET | Upload and list files |
/v1/files/{file_id} | GET, DELETE | Retrieve or delete a file |
/v1/files/{file_id}/content | GET | Download file content |
/v1/batches | POST, GET | Create and list batches |
/v1/batches/{batch_id} | GET | Retrieve a batch |
/v1/batches/{batch_id}/cancel | POST | Cancel a batch |
Images
| Endpoint | Method | Description |
|---|---|---|
/v1/images/generations | POST | Generate images from text |
/v1/images/edits | POST | Edit images |
/v1/images/variations | POST | Create image variations |
/v1/images/generations/{id} | GET | Compatibility status path for task-based image responses |
Image models may return a finished image or an asynchronous task. If the response includes status: "pending" or a task ID, poll GET /v1/tasks/{id}.
Audio
| Endpoint | Method | Description |
|---|---|---|
/v1/audio/speech | POST | Text-to-speech (TTS) |
/v1/audio/transcriptions | POST | Speech-to-text (STT) |
/v1/audio/translations | POST | Translate speech into English text |
Realtime
| Endpoint | Method | Description |
|---|---|---|
/v1/realtime?model={model} | WS | Realtime WebSocket sessions |
Use /v1/realtime for WebSocket upgrades. A plain GET /v1/realtime returns endpoint metadata. This is not the OpenAI Realtime REST surface; client-secret, Calls, and legacy beta session endpoints are not available.
Video
| Endpoint | Method | Description |
|---|---|---|
/v1/videos/generations | POST | Create video generation task |
/v1/videos/generations/{id} | GET | Compatibility status path |
/v1/videos/assets | POST, GET | Create and list Seedance material assets |
/api/v3/contents/generations/tasks | POST, GET | Seedance tasks with the Volcengine request format |
Poll GET /v1/tasks/{id} with the task id. /v1/videos/generations/{id} remains available for existing integrations.
Async Tasks
| Endpoint | Method | Description |
|---|---|---|
/v1/tasks/{id} | GET | Status for any asynchronous task |
/v1/tasks/{id} | DELETE | Cancel an asynchronous task |
Poll GET /v1/tasks/{id} for every async task: images, video, music, 3D, Worlds, and async audio transcription. Use the id or task_id from the create response. A Worlds create response returns a poll_url under /v1/worlds/generations/{id}; poll /v1/tasks/{id} there too. The per-modality status paths on this page are compatibility endpoints for existing integrations.
Music
| Endpoint | Method | Description |
|---|---|---|
/v1/music/generations | POST | Create music generation task |
/v1/music/generations/{id} | GET | Compatibility status path |
3D Generation
| Endpoint | Method | Description |
|---|---|---|
/v1/3d/generations | POST | Create 3D model generation task |
/v1/3d/generations/{id} | GET | Compatibility status path |
Worlds
| Endpoint | Method | Description |
|---|---|---|
/v1/worlds/generations | POST | Create a world generation task |
/v1/worlds/list | POST | List worlds |
/v1/worlds/{id} | GET, DELETE | Retrieve or delete a world |
/v1/worlds/media-assets/prepare-upload | POST | Prepare a media asset upload |
Models & Pricing
| Endpoint | Method | Description |
|---|---|---|
/v1/models | GET | List all available models |
/v1/models/{model} | GET | Get specific model info |
/v1/models/{model}/pricing | GET | Get the prices of one model |
/v1/pricing | GET | List model prices |
Gemini (v1beta)
Native Google Gemini API format support:
| Endpoint | Method | Description |
|---|---|---|
/v1beta/models | GET | List models that accept Gemini requests |
/v1beta/models/{model} | GET | Get a model |
/v1beta/models/{model}:generateContent | POST | Generate content |
/v1beta/models/{model}:streamGenerateContent | POST | Stream generate content |
/v1beta/models/{model}:countTokens | POST | Count tokens |
/v1beta/files, /v1beta/cachedContents | POST, GET, DELETE | Gemini Files and cached content |
Gemini endpoints support ?key= query parameter authentication in addition to standard Bearer token.
Management
/v1/management/* manages balance, API keys, and webhooks with a management token. See the Management API.
Response Format
Each endpoint preserves its API format. The success and error examples below use Chat Completions format.
Success Response
{
"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
}
}Response headers
Use these headers when they are present.
| Header | Description |
|---|---|
X-Request-ID | Request identifier for support and debugging |
X-Routing-Time-MS | Non-streaming: total time in milliseconds until the upstream response arrives, including upstream queueing and inference. Streaming: always 0. Not a routing/queueing measurement. |
X-Task-ID | Public async task identifier for task-based responses |
X-Billing-Transaction-ID | Billing transaction identifier after final billing |
Official request rejections may include upstream with the service's reported error and public service name. See Handle API errors.
Error Response
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}Rate Limits
Limits depend on the account tier and apply per API key. A 429 response carries Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. See Rate limits for the tiers and how to retry.
OpenAPI Specification
OpenAPI Spec
Download the complete OpenAPI 3.1 specification