核心指南
✨ TokenLab API 整合技能
安裝維護中的 TokenLab API 整合技能，讓 coding agent 能探索模型、讀取対応状況並從 API 錯誤中恢復。
讀取本頁並將 TokenLab Skill 加入我目前的 agent。先檢查已安裝版本及目前設定，保留既有帳戶、提供者、權限與其他設定。備份檔案並展示變更。API key 由我在本機輸入，不得在對話中索取或顯示。先驗證設定載入；執行任何付費測試前，先說明測試。
https://tokenlab.sh/docs/zh-TW/integrations/coding-agent-skill本頁說明維護中的共用 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
造訪 TokenLab
前往 tokenlab.sh
登入
建立帳戶或登入
取得 API Key
開啟 Dashboard → API Keys 並建立新的 key
複製 key
你的 key 以 sk-... 開頭，請妥善保存。
不要把 API key 貼到提示詞或原始碼裡。skill 應詢問要使用哪個環境變數，並產生從該變數讀取 key 的程式碼。
建議的 Agent 工作流程
先讀取目前模型清單，再讀取所選模型的 tokenlab.accepted_request_formats 與公開請求欄位。同一對話與工具呼叫保持相同格式；不同格式的欄位不會自動轉換。保留使用者選定的模型，不要因錯誤自行改模型或協定。
最小聊天範例
這個範例使用 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-5.6-luna",
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 $TOKENLAB_API_KEY"
curl "https://api.tokenlab.sh/v1/models?category=image" -H "Authorization: Bearer $TOKENLAB_API_KEY"
# 非聊天場景推薦列表
curl "https://api.tokenlab.sh/v1/models?recommended_for=image" -H "Authorization: Bearer $TOKENLAB_API_KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=video" -H "Authorization: Bearer $TOKENLAB_API_KEY"
curl "https://api.tokenlab.sh/v1/models?recommended_for=translation" -H "Authorization: Bearer $TOKENLAB_API_KEY"
# 非聊天請求重試前讀取單一模型対応状況
curl "https://api.tokenlab.sh/v1/models/gpt-image-2" -H "Authorization: Bearer $TOKENLAB_API_KEY"
# 僅價格詳情
curl "https://api.tokenlab.sh/v1/models/gpt-image-2/pricing" -H "Authorization: Bearer $TOKENLAB_API_KEY"原生協定選擇
常見聊天、圖像、嵌入、音訊和 rerank 範例預設走 OpenAI 相容 /v1。不要根據模型名稱、供應商名稱或 Chat 回應標頭推斷原生協定是否可用；應讀取 GET /v1/models/{model}，只使用模型詳情明確公告的請求格式。
應讀取的欄位是 tokenlab.accepted_request_formats。
協定端點分別為 Chat Completions 的 /v1/chat/completions、Responses 的 /v1/responses、Messages 的 /v1/messages，以及 Gemini 的 /v1beta/models/{model}:generateContent。
Agent-First 錯誤恢復
錯誤回應包含 coding agent 可直接解析的欄位：
以 HTTP 狀態和錯誤 code 為主要依據。模型名稱錯誤時可參考 did_you_mean，但未經使用者選擇不得切換模型。遇到 429，依 Retry-After 或 retry_after 等待；只有錯誤允許且已明確決定重試時才重試。驗證、鑑權、餘額及權限錯誤需要先修正，不要直接重送。建立請求逾時時，先查詢是否已有任務，避免重複建立。
支援的 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
資源
API 或帳戶問題請使用站內支援，核對預覽後明確提交。個別請求請從請求記錄及調查指南開始。Skill 本身的缺陷請回報至 GitHub Issues。