API Reference

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

All API endpoints require authentication using a Bearer token:

Authorization: Bearer sk-your-api-key

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. TokenLab prices apply.
Official is based on the model maker’s public price. The price shown on TokenLab is what you pay.
Realtime sessions use the API key or Workspace setting and do not accept a query-string override.

An invalid header returns 400. If the requested option is unavailable, TokenLab returns 503 with code: delivery_tier_unavailable, retryable: true, and a request ID.

The playground does not accept API keys. To send a real request, use one of these options:

cURL — Copy an example and replace sk-your-api-key
Postman — Import the OpenAPI spec
SDK — Set the TokenLab base URL in a supported SDK

Supported Endpoints

Chat & Text Generation

Endpoint	Method	Description
`/v1/chat/completions`	POST	OpenAI-compatible chat completions
`/v1/messages`	POST	Anthropic-compatible messages API
`/v1/responses`	POST	OpenAI Responses API

Embeddings & Rerank

Endpoint	Method	Description
`/v1/embeddings`	POST	Create text embeddings
`/v1/rerank`	POST	Rerank documents

Images

Endpoint	Method	Description
`/v1/images/generations`	POST	Generate images from text
`/v1/images/edits`	POST	Edit images
`/v1/images/generations/{id}`	GET	Image task status path for task-based image responses

Image models may return a finished image or an asynchronous task. If the response includes poll_url, use that URL to check the task.

Audio

Endpoint	Method	Description
`/v1/audio/speech`	POST	Text-to-speech (TTS)
`/v1/audio/transcriptions`	POST	Speech-to-text (STT)

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/tasks/{id}`	GET	Get async task status for video jobs
`/v1/videos/generations/{id}`	GET	Legacy-compatible video task status path

Use the poll_url returned when the task is created. /v1/videos/generations/{id} remains available for older clients.

Async Tasks

Endpoint	Method	Description
`/v1/tasks/{id}`	GET	Status for an asynchronous task

Video, music, 3D, and some image requests may return this endpoint in poll_url.

Music

Endpoint	Method	Description
`/v1/music/generations`	POST	Create music generation task
`/v1/music/generations/{id}`	GET	Music-specific status path

Use the returned poll_url. /v1/music/generations/{id} remains available for clients that need the music-specific path.

3D Generation

Endpoint	Method	Description
`/v1/3d/generations`	POST	Create 3D model generation task
`/v1/3d/generations/{id}`	GET	3D-specific status path

Use the returned poll_url. /v1/3d/generations/{id} remains available for clients that need the 3D-specific path.

Models

Endpoint	Method	Description
`/v1/models`	GET	List all available models
`/v1/models/{model}`	GET	Get specific model info

Gemini (v1beta)

Native Google Gemini API format support:

Endpoint	Method	Description
`/v1beta/models/{model}:generateContent`	POST	Generate content (Gemini format)
`/v1beta/models/{model}:streamGenerateContent`	POST	Stream generate content (Gemini format)

Gemini endpoints support ?key= query parameter authentication in addition to standard Bearer token.

Response Format

Each endpoint keeps the response shape documented for its API format. This is a Chat Completions example:

Success Response

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "gpt-5.6-terra",
  "choices": [...],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

Request identifiers

Private delivery details are not part of the public response contract. Use the public headers below when they are present.

Header	Description
`X-Routing-Time-MS`	Time spent selecting delivery, when available
`X-Request-ID`	Request identifier for support and debugging, when available
`X-Task-ID`	Public async task identifier for task-based responses, when available
`X-Billing-Transaction-ID`	Billing transaction identifier after final billing, when available

Error Response

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

Rate Limits

Rate limits are role-based and configurable by administrators. Default values:

Role	Requests/min
User	1,000
Partner	10,000
VIP	10,000

Contact support for custom rate limits. Exact values may vary by account configuration.

When rate limits are exceeded, the API returns a 429 status code with a Retry-After header indicating how long to wait.

OpenAPI Specification

OpenAPI Spec

Download the complete OpenAPI 3.0 specification

Core

Text

Files & Batches

Images

Audio & Realtime

Music

Video & Materials

Worlds

3D

Async Jobs

Gemini Native

Management

Overview

Base URL

Authentication

Delivery policy

Supported Endpoints

Chat & Text Generation

Embeddings & Rerank

Images

Audio

Realtime

Video

Async Tasks

Music

3D Generation

Models

Gemini (v1beta)

Response Format

Success Response

Request identifiers

Error Response

Rate Limits

OpenAPI Specification

OpenAPI Spec

​Overview

​Base URL

​Authentication

​Delivery policy

​Supported Endpoints

​Chat & Text Generation

​Embeddings & Rerank

​Images

​Audio

​Realtime

​Video

​Async Tasks

​Music

​3D Generation

​Models

​Gemini (v1beta)

​Response Format

​Success Response

​Request identifiers

​Error Response

​Rate Limits

​OpenAPI Specification

OpenAPI Spec

Overview

Base URL

Authentication

Delivery policy

Supported Endpoints

Chat & Text Generation

Embeddings & Rerank

Images

Audio

Realtime

Video

Async Tasks

Music

3D Generation

Models

Gemini (v1beta)

Response Format

Success Response

Request identifiers

Error Response

Rate Limits

OpenAPI Specification