核心
API 參考
端點、身份驗證、回應標頭與錯誤
概覽
TokenLab 支援與 OpenAI 相容的端點,以及 Anthropic 和 Gemini 的請求格式。現有的 OpenAI 客戶端可以使用 /v1;僅在您的應用程式需要該 API 特有的行為時,才選擇其他格式。POST /v1/responses 是選用的,取決於模型支援。
基礎 URL (Base URL)
https://api.tokenlab.sh身份驗證
模型請求使用 TokenLab API 金鑰。標準身份驗證標頭為:
Authorization: Bearer sk-your-api-keyGET /v1/models、GET /v1/models/{model}、GET /v1/models/{model}/pricing 以及 GET /v1/pricing 為公開端點,無需金鑰。Anthropic Messages 也接受 x-api-key;Gemini 除了 Bearer 身份驗證外,也接受 x-goog-api-key 或 ?key=。/v1/management/* 需要管理權杖 (management token) (mt-...)。
請從 控制台 (Console) 取得您的 API 金鑰。
交付政策 (Delivery policy)
生成請求接受 X-TokenLab-Delivery-Policy: auto | verified | official。請求標頭會覆寫 API 金鑰設定,而 API 金鑰設定會覆寫工作區 (Workspace) 的預設值。
Auto:在可用時使用 TokenLab Verified,必要時則使用 Official。您需為完成請求的選項付費。TokenLab Verified:由 TokenLab 驗證交付。適用 Verified 價格。Official:按 Official 價格計費,即模型製造商公佈的價格。- 即時 (Realtime) 工作階段使用 API 金鑰或工作區設定,不接受請求覆寫。
無效的標頭會回傳 400。如果請求的選項不可用,TokenLab 會回傳 503 delivery_tier_unavailable 以及一個請求 ID。請閱讀 retryable:當所選操作無供應時,該值為 false。請勿重複發送未經修改的相同請求。
帶有請求表單的 API 頁面會接受您的 TokenLab API 金鑰並發送真實請求。這些請求會使用您的帳戶餘額與額度。您也可以使用 cURL、Postman 或 SDK。
支援的端點
聊天與文字生成
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/chat/completions | POST | 與 OpenAI 相容的聊天完成 |
/v1/messages | POST | 與 Anthropic 相容的 Messages |
/v1/messages/count_tokens | POST | 計算 Messages 請求的輸入 token 數量 |
/v1/messages/batches | POST, GET | 建立 與 列出 Message Batches |
/v1/messages/batches/{message_batch_id} | GET, DELETE | 檢索 或 刪除 Message Batch |
/v1/messages/batches/{message_batch_id}/results | GET | 讀取結果 |
/v1/messages/batches/{message_batch_id}/cancel | POST | 取消 Message Batch |
/v1/responses | POST | OpenAI Responses API |
/v1/responses/{id} | GET, DELETE | 檢索 或 刪除 已儲存的回應 |
/v1/responses/compact | POST | 壓縮 Responses 對話的上下文 |
/v1/translations | POST | 文字轉文字翻譯 |
嵌入與重排序 (Embeddings & Rerank)
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/embeddings | POST | 建立文字嵌入 |
/v1/multimodal/embeddings | POST | 使用多模態嵌入模型建立嵌入 |
/v1/rerank | POST | 文件重排序 |
決策 (Decisions)
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/systemone | POST | 評估類型化決策問題 |
檔案與批次 (Files & Batches)
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/files | POST, GET | 上傳 與 列出 檔案 |
/v1/files/{file_id} | GET, DELETE | 檢索 或 刪除 檔案 |
/v1/files/{file_id}/content | GET | 下載檔案內容 |
/v1/batches | POST, GET | 建立 與 列出 批次 |
/v1/batches/{batch_id} | GET | 檢索批次 |
/v1/batches/{batch_id}/cancel | POST | 取消批次 |
圖像
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/images/generations | POST | 從文字生成圖像 |
/v1/images/edits | POST | 編輯圖像 |
/v1/images/variations | POST | 建立圖像變體 |
/v1/images/generations/{id} | GET | 基於任務的圖像回應之相容性狀態路徑 |
圖像模型可能會回傳完成的圖像或非同步任務。如果回應包含 status: "pending" 或任務 ID,請輪詢 GET /v1/tasks/{id}。
音訊
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/audio/speech | POST | 文字轉語音 (TTS) |
/v1/audio/transcriptions | POST | 語音轉文字 (STT) |
/v1/audio/translations | POST | 將語音翻譯為英文文字 |
即時 (Realtime)
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/realtime?model={model} | WS | 即時 WebSocket 工作階段 |
使用 /v1/realtime 進行 WebSocket 升級。單純的 GET /v1/realtime 會回傳端點元資料。這並非 OpenAI Realtime REST 介面;client-secret、Calls 以及舊版測試版工作階段端點皆不適用。
影片
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/videos/generations | POST | 建立影片生成任務 |
/v1/videos/generations/{id} | GET | 相容性狀態路徑 |
/v1/videos/assets | POST, GET | 建立並列出 Seedance 素材資產 |
/api/v3/contents/generations/tasks | POST, GET | 使用 Volcengine 請求格式的 Seedance 任務 |
使用任務 id 輪詢 GET /v1/tasks/{id}。/v1/videos/generations/{id} 仍可供現有整合使用。
非同步任務 (Async Tasks)
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/tasks/{id} | GET | 任何非同步任務的狀態 |
/v1/tasks/{id} | DELETE | 取消非同步任務 |
針對每個非同步任務輪詢 GET /v1/tasks/{id}:圖像、影片、音樂、3D、Worlds 以及非同步音訊轉錄。請使用建立回應中的 id 或 task_id。Worlds 建立回應會在 /v1/worlds/generations/{id} 下回傳 poll_url;請在那裡輪詢 /v1/tasks/{id}。本頁面上的各模態狀態路徑均為現有整合的相容性端點。
音樂
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/music/generations | POST | 建立音樂生成任務 |
/v1/music/generations/{id} | GET | 相容性狀態路徑 |
3D 生成
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/3d/generations | POST | 建立 3D 模型生成任務 |
/v1/3d/generations/{id} | GET | 相容性狀態路徑 |
Worlds
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/worlds/generations | POST | 建立世界生成任務 |
/v1/worlds/list | POST | 列出 Worlds |
/v1/worlds/{id} | GET, DELETE | 檢索或刪除 World |
/v1/worlds/media-assets/prepare-upload | POST | 準備媒體資產上傳 |
模型與定價
| 端點 | 方法 | 說明 |
|---|---|---|
/v1/models | GET | 列出所有可用模型 |
/v1/models/{model} | GET | 取得特定模型資訊 |
/v1/models/{model}/pricing | GET | 取得單一模型價格 |
/v1/pricing | GET | 列出模型價格 |
Gemini (v1beta)
原生 Google Gemini API 格式支援:
| 端點 | 方法 | 說明 |
|---|---|---|
/v1beta/models | GET | 列出接受 Gemini 請求的模型 |
/v1beta/models/{model} | GET | 取得模型 |
/v1beta/models/{model}:generateContent | POST | 生成內容 |
/v1beta/models/{model}:streamGenerateContent | POST | 串流生成內容 |
/v1beta/models/{model}:countTokens | POST | 計算 token |
/v1beta/files, /v1beta/cachedContents | POST, GET, DELETE | Gemini 檔案與快取內容 |
Gemini 端點除了標準 Bearer token 外,亦支援 ?key= 查詢參數身份驗證。
管理 (Management)
/v1/management/* 使用管理權杖來管理餘額、API 金鑰與 Webhook。請參閱 管理 API。
回應格式
每個端點皆保留其 API 格式。下方的成功與錯誤範例使用 Chat Completions 格式。
成功回應
{
"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
}
}回應標頭
當這些標頭存在時,請使用它們。
| 標頭 | 說明 |
|---|---|
X-Request-ID | 用於支援與除錯的請求識別碼 |
X-Routing-Time-MS | 非串流:到上游回應為止的總耗時(毫秒),包含上游排隊與推論。串流:固定為 0。不可用來判斷排隊或路由開銷。 |
X-Task-ID | 基於任務的回應之公開非同步任務識別碼 |
X-Billing-Transaction-ID | 最終計費後的帳務交易識別碼 |
官方請求拒絕可能包含 upstream,其中包含服務回報的錯誤與公開服務名稱。請參閱 處理 API 錯誤。
錯誤回應
{
"error": {
"message": "Invalid API key provided",
"type": "invalid_api_key",
"code": "invalid_api_key"
}
}速率限制 (Rate Limits)
限制取決於帳戶等級,並適用於每個 API 金鑰。429 回應會帶有 Retry-After、X-RateLimit-Limit、X-RateLimit-Remaining 與 X-RateLimit-Reset。請參閱 速率限制 以了解等級與重試方式。
OpenAPI 規範
OpenAPI 規範
下載完整的 OpenAPI 3.1 規範