# TokenLab API — Agent Quick Reference

> 298+ AI models via OpenAI-compatible API. Errors include structured hints for self-correction.

## Base URL
https://api.tokenlab.sh

## Authentication
Authorization: Bearer YOUR_API_KEY

## Endpoints
- POST /v1/chat/completions — Chat (OpenAI format)
- POST /v1/messages — Claude (Anthropic format)
- POST /v1/responses — Responses API (OpenAI format)
- POST /v1/embeddings — Embeddings
- POST /v1/images/generations — Image generation
- POST /v1/audio/speech — TTS
- POST /v1/audio/transcriptions — STT
- WS /v1/realtime?model={model} — Realtime WebSocket proxy (no Realtime REST client secrets or Calls)
- POST /v1/translations — Text translation
- POST /v1/videos/generations — Video generation
- POST /v1/music/generations — Music generation
- POST /v1/3d/generations — 3D generation
- POST /v1/worlds/generations — World generation
- POST /v1/rerank — Reranking
- GET /v1/models — List models (supports ?category= and ?provider= filters)
- GET /v1/models?recommended_for=image|video|music|3d|tts|stt|embedding|rerank|translation — ranked non-chat shortlist
- GET /v1/models/:model — Read full public contract for one model
- GET /v1/models/:model/pricing — Read pricing-only detail for one model

## Agent-First Error Handling

Error responses include structured hints so agents can self-correct:

| Field | Type | When |
|-------|------|------|
| did_you_mean | string | model_not_found — closest valid model ID |
| suggestions | array | model_not_found — top models in same category |
| hint | string | Always — human-readable recovery instruction |
| retry_after | number | rate_limit / model_unavailable — seconds to wait |
| retryable | boolean | Whether retrying the same request may succeed |
| balance_usd | number | insufficient_balance — current balance |
| estimated_cost_usd | number | insufficient_balance — estimated request cost |
| alternatives | array | model_unavailable — other models in same family |
| supported_operations | array | non-chat contract errors — public operations you may retry with |
| supported_parameters | array | non-chat contract errors — public parameters supported by the model |
| agent_preferences | object | /v1/models?recommended_for=... — cached 24h recommendation snapshot for non-chat scenes |
| allowed_resolutions | array | non-chat media errors — allowed resolution values |
| allowed_durations | array | non-chat media errors — allowed duration values |
| allowed_aspect_ratios | array | non-chat media errors — allowed aspect ratio values |
| recommended_request | object | non-chat contract errors — minimal request skeleton to retry with |
| request_endpoint | string | non-chat contract errors — canonical endpoint to call |
| request_shape_mode | string | non-chat contract errors — public request transport shape |
| status_mode | string | non-chat contract errors — status polling mode |

## Recommended Agent Workflow

1. Try the request directly
2. On error, read the structured hints from the error response
3. If did_you_mean is present, retry with the corrected model
4. If retryable is true, wait retry_after seconds and retry
5. If suggestions/alternatives are present, try one of those
6. For non-chat models, read GET /v1/models/:model before retrying so you can align with the public contract

## Quick Start

### Python
```python
from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.tokenlab.sh/v1"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
```

### cURL
```bash
curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Text/Chat Models (124)
- allam-2-7b
- claude-fable-5
- claude-fable-5-1
- claude-haiku-4-5
- claude-opus-4-6
- claude-opus-4-7
- claude-opus-4-8
- claude-opus-5
- claude-sonnet-4-6
- claude-sonnet-5
- deepseek-v4-flash
- deepseek-v4-flash-vision-exp
- deepseek-v4-pro
- deepseek-v4.1-flash
- doubao-seed-2.0-code
- doubao-seed-2.0-lite
- doubao-seed-2.0-mini
- doubao-seed-2.0-pro
- doubao-seed-2.1-pro
- doubao-seed-2.1-turbo
- doubao-seed-character
- doubao-seed-evolving
- gemini-2.5-pro
- gemini-3-flash-preview
- gemini-3.1-flash-lite
- gemini-3.1-pro-preview
- gemini-3.5-flash
- gemini-3.5-flash-lite
- gemini-3.6-flash
- gemini-3.7-flash
- gemini-3.8-flash
- glm-5
- glm-5-turbo
- glm-5.1
- glm-5.2
- glm-5.3
- glm-5.3-flash
- glm-5v-turbo
- gpt-4.1
- gpt-4.1-mini
- gpt-4o
- gpt-4o-mini
- gpt-5
- gpt-5-mini
- gpt-5-nano
- gpt-5-pro
- gpt-5-search-api
- gpt-5.1
- gpt-5.2
- gpt-5.2-pro
- gpt-5.3-codex
- gpt-5.4
- gpt-5.4-mini
- gpt-5.4-nano
- gpt-5.4-pro
- gpt-5.5
- gpt-5.5-pro
- gpt-5.6-luna
- gpt-5.6-sol
- gpt-5.6-terra
- gpt-6-astra
- gpt-audio-1.5
- gpt-oss-120b
- gpt-oss-20b
- grok-4.20
- grok-4.20-multi-agent
- grok-4.20-non-reasoning
- grok-4.3
- grok-4.5
- grok-4.6
- grok-build-0.1
- groq-compound
- groq-compound-mini
- hunyuan-role
- hy-mt2-pro
- hy3
- kimi-k2.5
- kimi-k2.6
- kimi-k2.7-code
- kimi-k2.7-code-highspeed
- kimi-k3
- mimo-v2.5
- mimo-v2.5-pro
- minimax-m2
- minimax-m2.1
- minimax-m2.1-highspeed
- minimax-m2.5-highspeed
- minimax-m2.7
- minimax-m2.7-highspeed
- minimax-m3
- o3
- qwen-deep-research
- qwen-doc-turbo
- qwen-flash
- qwen-flash-character
- qwen-max
- qwen-mt-flash
- qwen-mt-lite
- qwen-mt-plus
- qwen-plus
- qwen-plus-character
- qwen-vl-ocr
- qwen3-coder-flash
- qwen3-omni-flash
- qwen3-vl-plus
- qwen3.5-27b
- qwen3.5-flash
- qwen3.5-ocr
- qwen3.5-omni-flash
- qwen3.5-omni-plus
- qwen3.5-plus
- qwen3.6-27b
- qwen3.6-max-preview
- qwen3.7-max
- qwen3.7-plus
- qwen3.8-2.4t-a95b
- qwen3.8-27b
- qwen3.8-flash
- qwen3.8-max
- step-3.5-flash
- step-3.7-flash
- tongyi-intent-detect-v3
- tongyi-xiaomi-analysis-flash
- tongyi-xiaomi-analysis-pro

## Image Models (67)
- flux-1-dev
- flux-2-flex
- flux-2-klein-4b
- flux-2-klein-9b
- flux-2-max
- flux-2-pro
- flux-kontext-max
- flux-kontext-pro
- flux-pro-1.0-fill
- flux-pro-1.1
- flux-pro-1.1-ultra
- gemini-2.5-flash-image
- gemini-3-pro-image
- gemini-3.1-flash-image
- gemini-3.1-flash-lite-image
- gpt-image-2
- gpt-image-2.5-flare
- gpt-image-2.5-sunburst
- grok-imagine-image
- grok-imagine-image-2.0
- grok-imagine-image-quality
- hy-image-lite
- hy-image-v3.0
- ideogram-edit-v3
- ideogram-reframe-v3
- ideogram-remix-v3
- ideogram-v3
- image-background-remover
- image-upscaler
- kling-image
- kling-omni-image
- nano-banana
- nano-banana-2
- nano-banana-2-lite
- nano-banana-edit
- nano-banana-pro
- qwen-image
- qwen-image-2.0
- qwen-image-2.0-pro
- qwen-image-3.0
- qwen-image-3.0-pro
- qwen-image-edit
- qwen-mt-image
- sd3.5-flash
- sd3.5-large
- sd3.5-large-turbo
- sd3.5-medium
- seedream-4.0
- seedream-4.5
- seedream-5.0
- seedream-5.0-lite
- seedream-5.0-pro
- stability-control-sketch
- stability-control-structure
- stability-inpaint
- stability-style-guide
- stability-upscale-conservative
- stability-upscale-fast
- stable-image-core
- stable-image-ultra
- vidu-image-lite
- vidu-image-pro
- wan-2.7
- wanx-sketch-to-image-lite
- wanx-style-repaint-v1
- z-image
- z-image-turbo

## Video Models (48)
- grok-imagine-video
- grok-imagine-video-1.5
- grok-imagine-video-1.5-preview
- hailuo-2.3
- hailuo-2.3-pro
- hailuo-2.3-standard
- hailuo-h3
- happyhorse-1.0
- happyhorse-1.1
- kling-2.6-motion-control
- kling-3.0-motion-control
- kling-ai-avatar-pro
- kling-ai-avatar-standard
- kling-omni-video
- kling-v2.1-master
- kling-v2.5-turbo-pro
- kling-v2.6-std
- kling-v3.0
- pixverse-c1
- pixverse-v5.6
- pixverse-v6
- seedance-1.0-pro
- seedance-1.0-pro-fast
- seedance-1.5-pro
- seedance-2.0
- seedance-2.0-fast
- seedance-2.0-mini
- seedance-2.5
- veo3.1
- veo3.1-fast
- video-style-transform
- videoretalk
- viduq2
- viduq2-pro
- viduq2-pro-fast
- viduq2-turbo
- viduq3
- viduq3-mix
- viduq3-pro
- viduq3-turbo
- wan-2.5
- wan-2.6
- wan-3.0
- wan-3.0-prime
- wan2.2-animate-mix
- wan2.2-animate-move
- wan2.2-s2v
- wanx2.1-vace-plus

## Audio / Speech Models (38)
- cosyvoice-v3.5-plus
- fun-asr
- fun-asr-flash-2026-06-15
- fun-asr-realtime
- gpt-4o-mini-transcribe
- gpt-4o-mini-tts
- gpt-4o-transcribe
- gpt-4o-transcribe-diarize
- gpt-live-transcribe
- gpt-realtime-1.5
- gpt-realtime-2
- gpt-realtime-2.1
- gpt-realtime-2.1-mini
- gpt-transcribe
- grok-voice-latest
- grok-voice-stt
- grok-voice-think-fast-2.0
- grok-voice-tts
- paraformer-8k-v2
- paraformer-realtime-8k-v2
- paraformer-realtime-v2
- paraformer-v2
- qwen3-asr-flash
- qwen3-asr-flash-filetrans
- qwen3-asr-flash-realtime
- qwen3-tts-flash
- qwen3-tts-flash-realtime
- qwen3.5-omni-flash-realtime
- qwen3.5-omni-plus-realtime
- sambert-zhiyuan-v1
- speech-2.8-hd
- suno-lyrics
- suno-music
- tts-1
- tts-1-hd
- whisper-1
- whisper-large-v3
- whisper-large-v3-turbo

## Embedding Models (7)
- gemini-embedding-001
- qwen3-vl-embedding
- text-embedding-3-large
- text-embedding-3-small
- text-embedding-ada-002
- text-embedding-v4
- tongyi-embedding-vision-plus

## 3D Models (9)
- hitem3d-2.0
- hyper3d-gen2
- marble-1.0
- marble-1.0-draft
- marble-1.1
- marble-1.1-plus
- seed3d-2.0
- tripo-h3.1
- tripo-p1.0

## Rerank Models (1)
- qwen3-vl-rerank

## Translation Models (4)
- doubao-seed-translation
- gpt-realtime-translate
- qwen3-livetranslate-flash
- qwen3.5-livetranslate-flash-realtime

## Model Discovery
- GET /v1/models — all models
- GET /v1/models?category=chat — chat/text models
- GET /v1/models?category=image — image generation models
- GET /v1/models?category=video — video generation models
- GET /v1/models?category=audio — compatibility alias for audio + tts + stt + music
- GET /v1/models?category=tts — text-to-speech models
- GET /v1/models?category=stt — speech-to-text models
- GET /v1/models?category=music — music generation models
- GET /v1/models?category=3d — 3D generation models
- GET /v1/models?category=embedding — embedding models
- GET /v1/models?category=rerank — rerank models
- GET /v1/models/:model — full non-chat public contract (operations/parameters/recommended request)
- GET /v1/models/:model/pricing — pricing-only detail; use this when you need prices, not request construction
- Web model catalog: https://tokenlab.sh/en/models
- Model Data Center: https://tokenlab.sh/en/models/data
- Machine-readable catalog: https://tokenlab.sh/model-data/catalog.json
- Latest public model list: https://tokenlab.sh/model-data/latest.json
- Public trend snapshot: https://tokenlab.sh/model-data/trends.json
- Markdown model-data summary: https://tokenlab.sh/model-data/summary.md

## Native Endpoints
Native request formats are advertised per logical model in tokenlab.accepted_request_formats on GET /v1/models/:model.
Use the matching documented endpoint only when that model advertises the format.

## Links
- Docs: https://docs.tokenlab.sh
- MCP: https://tokenlab.sh/en/mcp
- Dashboard: https://tokenlab.sh/dashboard
- Pricing: https://tokenlab.sh/dashboard/models
- Model Data Center: https://tokenlab.sh/en/models/data
- Model Trends: https://tokenlab.sh/en/models/trends
- Model Research: https://tokenlab.sh/en/models/research