跳轉到主要內容
本頁說明維護中的共用 tokenlab-api-integration skill。規範分發源位於 hedging8563/tokenlab-skills，公開 repository 有意只保留這個 skill。
本頁用於 skill 安裝與 agent 工作流程說明。端點、SDK 或客戶端設定請查看對應工具的專門整合頁或 API Reference。

​
這個技能做什麼

  • 為 TokenLab 聊天、圖像、音訊、影片、翻譯等 API 家族產生最小可執行範例。
  • OpenAI 相容客戶端使用 https://api.tokenlab.sh/v1，並說明何時切到 Anthropic 或 Gemini 原生路由。
  • 透過 /v1/models、/llms.txt 和 recommended_for 推薦列表探索模型，而不是依賴陳舊的本地列表。
  • 非聊天請求重試前讀取模型対応状況，避免靜默丟棄不支援的欄位。
  • 處理 did_you_mean、suggestions、retry_after、recommended_request 等 Agent-First 錯誤提示。

​
安裝

請使用規範的非互動式安裝命令：
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
這會從 TokenLab skills repository 安裝共用的 tokenlab-api-integration skill。如果你的工具不支援安裝器，請把 repository 裡的 skills/tokenlab-api-integration/ 複製到工具的共用 skills 或 rules 目錄。

​
更新既有安裝

如果你之前已安裝過該 skill，請重新執行同一條命令以更新到目前公開包。

​
驗證安裝

詢問你的 coding agent： 
有哪些可用的 skills？
如果能看到 tokenlab-api-integration，表示安裝成功。

​
取得 API Key

1

造訪 TokenLab

前往 tokenlab.sh
2

登入

建立帳戶或登入
3

取得 API Key

開啟 Dashboard → API Keys 並建立新的 key
4

複製 key

你的 key 以 sk-... 開頭，請妥善保存。
不要把 API key 貼到提示詞或原始碼裡。skill 應詢問要使用哪個環境變數，並產生從該變數讀取 key 的程式碼。

​
建議的 Agent 工作流程

  1. 先產生符合使用者語言與 API 家族的最小可執行範例。
  2. 模型選擇未確定時，先呼叫 /v1/models 或 https://api.tokenlab.sh/llms.txt，不要硬編碼。
  3. 非聊天任務先呼叫 /v1/models?recommended_for=<scene>，其中 <scene> 可為 image、video、music、3d、tts、stt、embedding、rerank 或 translation。
  4. 修改失敗的非聊天請求前，讀取 /v1/models/:model，並對齊 supported_operations、supported_parameters、request_endpoint, request_endpoint_by_operation、request_shape_mode 和 recommended_request。
  5. 如果 API 返回 Agent-First 錯誤，使用結構化欄位修正請求；只有 retryable 表示可重試時才重試。

​
最小聊天範例

這個範例使用 OpenAI Python SDK 和 TokenLab base URL： 
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1"
)

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

print(response.choices[0].message.content)
執行方式： 
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py

​
模型探索與対応状況

優先使用即時探索，不依賴陳舊的打包列表： 
# 機器可讀 API 概覽
curl https://api.tokenlab.sh/llms.txt

# 列出模型
curl "https://api.tokenlab.sh/v1/models" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer sk-KEY"

# 非聊天場景推薦列表
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer sk-KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer sk-KEY"

# 非聊天請求重試前讀取單一模型対応状況
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer sk-KEY"

# 僅價格詳情
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer sk-KEY"

​
原生路由提示

常見聊天、Responses、圖像、嵌入、音訊和 rerank 範例預設走 OpenAI 相容 /v1。只有請求需要供應商特定行為，或 TokenLab 返回 X-TokenLab-Native-Endpoint 最佳化提示時，才切換 Anthropic 或 Gemini 原生路由。 
X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

​
Agent-First 錯誤恢復

錯誤回應包含 coding agent 可直接解析的欄位：
錯誤有用欄位Agent 處理方式
模型名稱錯誤did_you_mean, suggestions, hint使用修正後的模型或推薦替代項重試
餘額不足balance_usd, estimated_cost_usd, suggestions請求使用者確認，或切換到可負擔模型
速率限制或暫時不可用retryable, retry_after, alternatives等待後重試，或選擇列出的替代模型
非聊天請求不相容supported_operations, supported_parameters, request_endpoint, request_endpoint_by_operation, request_shape_mode, recommended_request按対応状況重建請求；會改變意圖的欄位必須 return a clear error

​
支援的 API 家族

家族主要路徑
聊天與 Responses/v1/chat/completions, /v1/responses
Claude 原生 messages/v1/messages
Gemini 原生請求/v1beta/models/{model}:generateContent
圖像/v1/images/generations, /v1/images/edits
影片/v1/videos/generations
音樂/v1/music/generations
Worlds/v1/worlds/generations 以及 world 狀態和媒體資產端點
3D/v1/3d/generations
音訊/v1/audio/speech, /v1/audio/transcriptions, /v1/audio/translations
Realtime/v1/realtime?model={model}
嵌入與 rerank/v1/embeddings, /v1/rerank
文字翻譯/v1/translations

​
最佳實務

API Key 安全

使用環境變數和伺服器端呼叫，不要在前端程式碼裡暴露 key。

非聊天先看契約

重試圖像、影片、音樂、3D、翻譯、音訊、嵌入或 rerank 請求前，先讀取 /v1/models?recommended_for=... 和 /v1/models/:model。

最小可執行範例

先產生一個能跑通的呼叫，再加入抽象、佇列或 UI 流程。

使用結構化提示

修改程式碼前先解析 did_you_mean、retry_after、alternatives 和 recommended_request。

​
FAQ

在請求中提到 “TokenLab” 或 “TokenLab API”，例如：用 TokenLab 給我的 Node.js 應用加入圖像生成。
任何支援共用 skill 或 rules 目錄的 coding agent 都可以使用這個資料夾。skills 安裝器會自動處理支援的 agent。
重新執行安裝命令即可，它會從規範公開 repository 刷新本地副本。
npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y

​
資源

Agent-First API

結構化錯誤提示和恢復行為

API 文件

端點設定和 API Reference

模型

瀏覽可用模型

llms.txt

面向 agents 的機器可讀 API 概覽
有問題？請使用 GitHub Issues 或聯絡 support@tokenlab.sh。