TokenLab

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.sh

Authentication

Model requests use a TokenLab API key. The standard authentication header is:

Authorization: Bearer sk-your-api-key

GET /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.

  • Auto uses TokenLab Verified when available, then Official if needed. You pay for the option that completes your request.
  • TokenLab Verified is delivery verified by TokenLab. The Verified price applies.
  • Official bills 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

EndpointMethodDescription
/v1/chat/completionsPOSTOpenAI-compatible chat completions
/v1/messagesPOSTAnthropic-compatible Messages
/v1/messages/count_tokensPOSTCount the input tokens of a Messages request
/v1/messages/batchesPOST, GETCreate and list Message Batches
/v1/messages/batches/{message_batch_id}GET, DELETERetrieve or delete a Message Batch
/v1/messages/batches/{message_batch_id}/resultsGETRead the results
/v1/messages/batches/{message_batch_id}/cancelPOSTCancel a Message Batch
/v1/responsesPOSTOpenAI Responses API
/v1/responses/{id}GET, DELETERetrieve or delete a stored response
/v1/responses/compactPOSTCompact the context of a Responses conversation
/v1/translationsPOSTText-to-text translation

Embeddings & Rerank

EndpointMethodDescription
/v1/embeddingsPOSTCreate text embeddings
/v1/multimodal/embeddingsPOSTCreate embeddings with a multimodal embedding model
/v1/rerankPOSTRerank documents

Decisions

EndpointMethodDescription
/v1/systemonePOSTEvaluate typed decision questions

Files & Batches

EndpointMethodDescription
/v1/filesPOST, GETUpload and list files
/v1/files/{file_id}GET, DELETERetrieve or delete a file
/v1/files/{file_id}/contentGETDownload file content
/v1/batchesPOST, GETCreate and list batches
/v1/batches/{batch_id}GETRetrieve a batch
/v1/batches/{batch_id}/cancelPOSTCancel a batch

Images

EndpointMethodDescription
/v1/images/generationsPOSTGenerate images from text
/v1/images/editsPOSTEdit images
/v1/images/variationsPOSTCreate image variations
/v1/images/generations/{id}GETCompatibility 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

EndpointMethodDescription
/v1/audio/speechPOSTText-to-speech (TTS)
/v1/audio/transcriptionsPOSTSpeech-to-text (STT)
/v1/audio/translationsPOSTTranslate speech into English text

Realtime

EndpointMethodDescription
/v1/realtime?model={model}WSRealtime 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

EndpointMethodDescription
/v1/videos/generationsPOSTCreate video generation task
/v1/videos/generations/{id}GETCompatibility status path
/v1/videos/assetsPOST, GETCreate and list Seedance material assets
/api/v3/contents/generations/tasksPOST, GETSeedance 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

EndpointMethodDescription
/v1/tasks/{id}GETStatus for any asynchronous task
/v1/tasks/{id}DELETECancel 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

EndpointMethodDescription
/v1/music/generationsPOSTCreate music generation task
/v1/music/generations/{id}GETCompatibility status path

3D Generation

EndpointMethodDescription
/v1/3d/generationsPOSTCreate 3D model generation task
/v1/3d/generations/{id}GETCompatibility status path

Worlds

EndpointMethodDescription
/v1/worlds/generationsPOSTCreate a world generation task
/v1/worlds/listPOSTList worlds
/v1/worlds/{id}GET, DELETERetrieve or delete a world
/v1/worlds/media-assets/prepare-uploadPOSTPrepare a media asset upload

Models & Pricing

EndpointMethodDescription
/v1/modelsGETList all available models
/v1/models/{model}GETGet specific model info
/v1/models/{model}/pricingGETGet the prices of one model
/v1/pricingGETList model prices

Gemini (v1beta)

Native Google Gemini API format support:

EndpointMethodDescription
/v1beta/modelsGETList models that accept Gemini requests
/v1beta/models/{model}GETGet a model
/v1beta/models/{model}:generateContentPOSTGenerate content
/v1beta/models/{model}:streamGenerateContentPOSTStream generate content
/v1beta/models/{model}:countTokensPOSTCount tokens
/v1beta/files, /v1beta/cachedContentsPOST, GET, DELETEGemini 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.

HeaderDescription
X-Request-IDRequest identifier for support and debugging
X-Routing-Time-MSNon-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-IDPublic async task identifier for task-based responses
X-Billing-Transaction-IDBilling 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

On this page