TokenLab

核心

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-key

GET /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/completionsPOST與 OpenAI 相容的聊天完成
/v1/messagesPOST與 Anthropic 相容的 Messages
/v1/messages/count_tokensPOST計算 Messages 請求的輸入 token 數量
/v1/messages/batchesPOST, GET建立 與 列出 Message Batches
/v1/messages/batches/{message_batch_id}GET, DELETE檢索 或 刪除 Message Batch
/v1/messages/batches/{message_batch_id}/resultsGET讀取結果
/v1/messages/batches/{message_batch_id}/cancelPOST取消 Message Batch
/v1/responsesPOSTOpenAI Responses API
/v1/responses/{id}GET, DELETE檢索 或 刪除 已儲存的回應
/v1/responses/compactPOST壓縮 Responses 對話的上下文
/v1/translationsPOST文字轉文字翻譯

嵌入與重排序 (Embeddings & Rerank)

端點方法說明
/v1/embeddingsPOST建立文字嵌入
/v1/multimodal/embeddingsPOST使用多模態嵌入模型建立嵌入
/v1/rerankPOST文件重排序

決策 (Decisions)

端點方法說明
/v1/systemonePOST評估類型化決策問題

檔案與批次 (Files & Batches)

端點方法說明
/v1/filesPOST, GET上傳 與 列出 檔案
/v1/files/{file_id}GET, DELETE檢索 或 刪除 檔案
/v1/files/{file_id}/contentGET下載檔案內容
/v1/batchesPOST, GET建立 與 列出 批次
/v1/batches/{batch_id}GET檢索批次
/v1/batches/{batch_id}/cancelPOST取消批次

圖像

端點方法說明
/v1/images/generationsPOST從文字生成圖像
/v1/images/editsPOST編輯圖像
/v1/images/variationsPOST建立圖像變體
/v1/images/generations/{id}GET基於任務的圖像回應之相容性狀態路徑

圖像模型可能會回傳完成的圖像或非同步任務。如果回應包含 status: "pending" 或任務 ID,請輪詢 GET /v1/tasks/{id}。

音訊

端點方法說明
/v1/audio/speechPOST文字轉語音 (TTS)
/v1/audio/transcriptionsPOST語音轉文字 (STT)
/v1/audio/translationsPOST將語音翻譯為英文文字

即時 (Realtime)

端點方法說明
/v1/realtime?model={model}WS即時 WebSocket 工作階段

使用 /v1/realtime 進行 WebSocket 升級。單純的 GET /v1/realtime 會回傳端點元資料。這並非 OpenAI Realtime REST 介面;client-secret、Calls 以及舊版測試版工作階段端點皆不適用。

影片

端點方法說明
/v1/videos/generationsPOST建立影片生成任務
/v1/videos/generations/{id}GET相容性狀態路徑
/v1/videos/assetsPOST, GET建立並列出 Seedance 素材資產
/api/v3/contents/generations/tasksPOST, 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/generationsPOST建立音樂生成任務
/v1/music/generations/{id}GET相容性狀態路徑

3D 生成

端點方法說明
/v1/3d/generationsPOST建立 3D 模型生成任務
/v1/3d/generations/{id}GET相容性狀態路徑

Worlds

端點方法說明
/v1/worlds/generationsPOST建立世界生成任務
/v1/worlds/listPOST列出 Worlds
/v1/worlds/{id}GET, DELETE檢索或刪除 World
/v1/worlds/media-assets/prepare-uploadPOST準備媒體資產上傳

模型與定價

端點方法說明
/v1/modelsGET列出所有可用模型
/v1/models/{model}GET取得特定模型資訊
/v1/models/{model}/pricingGET取得單一模型價格
/v1/pricingGET列出模型價格

Gemini (v1beta)

原生 Google Gemini API 格式支援:

端點方法說明
/v1beta/modelsGET列出接受 Gemini 請求的模型
/v1beta/models/{model}GET取得模型
/v1beta/models/{model}:generateContentPOST生成內容
/v1beta/models/{model}:streamGenerateContentPOST串流生成內容
/v1beta/models/{model}:countTokensPOST計算 token
/v1beta/files, /v1beta/cachedContentsPOST, GET, DELETEGemini 檔案與快取內容

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 規範

本頁內容