> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# ✨ TokenLab API 整合技能

> 安裝維護中的 TokenLab API 整合技能，讓 coding agent 能探索模型、讀取対応状況並從 API 錯誤中恢復。

<Note>
  本頁說明維護中的共用 `tokenlab-api-integration` skill。規範分發源位於 [hedging8563/tokenlab-skills](https://github.com/hedging8563/tokenlab-skills)，公開 repository 有意只保留這個 skill。
</Note>

<Note>
  本頁用於 skill 安裝與 agent 工作流程說明。端點、SDK 或客戶端設定請查看對應工具的專門整合頁或 API Reference。
</Note>

## 這個技能做什麼

* 為 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 錯誤提示。

## 安裝

<Note>
  請使用規範的非互動式安裝命令：

  ```bash theme={null}
  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 目錄。
</Note>

### 更新既有安裝

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

### 驗證安裝

詢問你的 coding agent：

```
有哪些可用的 skills？
```

如果能看到 `tokenlab-api-integration`，表示安裝成功。

## 取得 API Key

<Steps>
  <Step title="造訪 TokenLab">
    前往 [tokenlab.sh](https://tokenlab.sh)
  </Step>

  <Step title="登入">
    建立帳戶或登入
  </Step>

  <Step title="取得 API Key">
    開啟 [Dashboard → API Keys](https://tokenlab.sh/dashboard/api) 並建立新的 key
  </Step>

  <Step title="複製 key">
    你的 key 以 `sk-...` 開頭，請妥善保存。
  </Step>
</Steps>

<Tip>
  不要把 API key 貼到提示詞或原始碼裡。skill 應詢問要使用哪個環境變數，並產生從該變數讀取 key 的程式碼。
</Tip>

## 建議的 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：

```python theme={null}
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)
```

執行方式：

```bash theme={null}
pip install openai
export TOKENLAB_API_KEY="sk-your-api-key"
python app.py
```

## 模型探索與対応状況

優先使用即時探索，不依賴陳舊的打包列表：

```bash theme={null}
# 機器可讀 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`                                                       |

## 最佳實務

<CardGroup cols={2}>
  <Card title="API Key 安全" icon="shield">
    使用環境變數和伺服器端呼叫，不要在前端程式碼裡暴露 key。
  </Card>

  <Card title="非聊天先看契約" icon="file-code">
    重試圖像、影片、音樂、3D、翻譯、音訊、嵌入或 rerank 請求前，先讀取 `/v1/models?recommended_for=...` 和 `/v1/models/:model`。
  </Card>

  <Card title="最小可執行範例" icon="terminal">
    先產生一個能跑通的呼叫，再加入抽象、佇列或 UI 流程。
  </Card>

  <Card title="使用結構化提示" icon="rotate-cw">
    修改程式碼前先解析 `did_you_mean`、`retry_after`、`alternatives` 和 `recommended_request`。
  </Card>
</CardGroup>

## FAQ

<AccordionGroup>
  <Accordion title="skill 沒有自動觸發？">
    在請求中提到 “TokenLab” 或 “TokenLab API”，例如：`用 TokenLab 給我的 Node.js 應用加入圖像生成`。
  </Accordion>

  <Accordion title="支援哪些 coding agent？">
    任何支援共用 skill 或 rules 目錄的 coding agent 都可以使用這個資料夾。`skills` 安裝器會自動處理支援的 agent。
  </Accordion>

  <Accordion title="如何更新 skill？">
    重新執行安裝命令即可，它會從規範公開 repository 刷新本地副本。

    ```bash theme={null}
    npx skills add https://github.com/hedging8563/tokenlab-skills --skill tokenlab-api-integration -y
    ```
  </Accordion>
</AccordionGroup>

## 資源

<CardGroup cols={2}>
  <Card title="Agent-First API" icon="robot" href="/zh-Hant/guides/agent-first-api">
    結構化錯誤提示和恢復行為
  </Card>

  <Card title="API 文件" icon="book" href="https://docs.tokenlab.sh">
    端點設定和 API Reference
  </Card>

  <Card title="模型" icon="sparkles" href="https://tokenlab.sh/zh-TW/models">
    瀏覽可用模型
  </Card>

  <Card title="llms.txt" icon="file-lines" href="https://api.tokenlab.sh/llms.txt">
    面向 agents 的機器可讀 API 概覽
  </Card>
</CardGroup>

<Info>
  有問題？請使用 [GitHub Issues](https://github.com/hedging8563/tokenlab-skills/issues) 或聯絡 [support@tokenlab.sh](mailto:support@tokenlab.sh)。
</Info>