✨ TokenLab API 整合技能

本頁說明維護中的共用 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 工作流程

先產生符合使用者語言與 API 家族的最小可執行範例。
模型選擇未確定時，先呼叫 /v1/models 或 https://api.tokenlab.sh/llms.txt，不要硬編碼。
非聊天任務先呼叫 /v1/models?recommended_for=<scene>，其中 <scene> 可為 image、video、music、3d、tts、stt、embedding、rerank 或 translation。
修改失敗的非聊天請求前，讀取 /v1/models/:model，並對齊 supported_operations、supported_parameters、request_endpoint, request_endpoint_by_operation、request_shape_mode 和 recommended_request。
如果 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"

原生協定選擇

常見聊天、圖像、嵌入、音訊和 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 可直接解析的欄位：

錯誤	有用欄位	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`	依模型詳細資訊重建請求；對會改變意圖的欄位傳回明確錯誤

支援的 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

skill 沒有自動觸發？

在請求中提到 “TokenLab” 或 “TokenLab API”，例如：用 TokenLab 給我的 Node.js 應用加入圖像生成。

支援哪些 coding agent？

任何支援共用 skill 或 rules 目錄的 coding agent 都可以使用這個資料夾。skills 安裝器會自動處理支援的 agent。

如何更新 skill？

重新執行安裝命令即可，它會從規範公開 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。

快速入門

核心指南

媒體指南

✨ TokenLab API 整合技能

這個技能做什麼

安裝

更新既有安裝

驗證安裝

取得 API Key

建議的 Agent 工作流程

最小聊天範例

模型探索與対応状況

原生協定選擇

Agent-First 錯誤恢復

支援的 API 家族

最佳實務

API Key 安全

非聊天先看契約

最小可執行範例

使用結構化提示

FAQ

資源

Agent-First API

API 文件

模型

llms.txt

​這個技能做什麼

​安裝

​更新既有安裝

​驗證安裝

​取得 API Key

​建議的 Agent 工作流程

​最小聊天範例

​模型探索與対応状況

​原生協定選擇

​Agent-First 錯誤恢復

​支援的 API 家族

​最佳實務

API Key 安全

非聊天先看契約

最小可執行範例

使用結構化提示

​FAQ

​資源

Agent-First API

API 文件

模型

llms.txt

這個技能做什麼

安裝

更新既有安裝

驗證安裝

取得 API Key

建議的 Agent 工作流程

最小聊天範例

模型探索與対応状況

原生協定選擇

Agent-First 錯誤恢復

支援的 API 家族

最佳實務

FAQ

資源