> ## 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.

# IDE 與 SDK 相容性

> 針對 AI 編碼工具、SDK 和框架的實證相容性指南

## 概覽

TokenLab 提供多種 API 格式，讓常見的編碼工具、SDK 和框架能以最少的膠水程式碼（glue code）進行整合。

本頁面的內容刻意比行銷矩陣更為精簡：

* **支援 (Supported)**：代表我們記錄了具體的設定路徑，且 TokenLab 提供了該路徑所預期的協定格式。
* **強原生路徑 (Strong native path)**：代表該儲存庫針對該協定系列擁有直接的轉接器（adapter）或請求格式實證。
* **盡力而為 (Best-effort)**：代表整合可能運作，但上游客戶端並未將此自訂閘道工作流程視為穩定的合約。

<Note>
  不支援的欄位處理方式不盡相同。在相容性路由上，某些欄位會被忽略或標準化。在 `/v1/responses` 上，當該路由無法保證所請求的行為時，可能會回傳明確的 `400` 或 `503` 錯誤。
</Note>

## 支援的 API 格式

| 端點 (Endpoint)                           | 格式                 | 使用案例        |
| --------------------------------------- | ------------------ | ----------- |
| `/v1/chat/completions`                  | OpenAI Chat        | 通用相容性       |
| `/v1/responses`                         | OpenAI Responses   | 有狀態對話       |
| `/v1/messages`                          | Anthropic Messages | Claude 原生功能 |
| `/v1beta/models/:model:generateContent` | Google Gemini      | Gemini 原生功能 |

## IDE 與 CLI 相容性

### 已記錄的工具路徑

| 工具                  | 支援層級         | 格式               | 備註                                                                       |
| ------------------- | ------------ | ---------------- | ------------------------------------------------------------------------ |
| **Cursor**          | 支援（有限制）      | OpenAI 相容        | 適用於 BYOK 標準聊天/編輯器流程，無法取代 Cursor 管理的功能（如 Tab Completion）                  |
| **Claude Code CLI** | 強原生路徑        | Anthropic        | 原生 `/v1/messages` 路由，包含對 thinking 和 `tool_choice` 的轉接器支援                 |
| **Codex CLI**       | 支援（模型/路徑有限制） | OpenAI Responses | 將 `/v1/responses` 視為 Codex 特定工作流程的進階路徑；並非所有模型和路由路徑都能保證支援僅限 Responses 的欄位 |
| **Gemini CLI**      | 盡力而為 / 實驗性   | Gemini           | 自訂 TokenLab 基礎 URL 流程並非官方 Gemini CLI 整合                                  |
| **OpenCode**        | 支援           | OpenAI 相容        | 預設使用 OpenAI 相容提供者；僅在明確需要時才切換至基於 Responses 的提供者                           |
| **OpenHands**       | 支援           | OpenAI 相容        | 使用 LiteLLM/OpenAI 相容路徑，設定 `openai/<model>` 並使用 TokenLab 的 `/v1` 基礎 URL   |

<Note>
  其他 OpenAI 相容的編輯器和代理工具通常也適用相同的基礎 URL 模式；在生產環境使用前，請先檢查該工具本身的自訂提供者支援情況。
</Note>

### 設定範例

<Tabs>
  <Tab title="Cursor">
    ```
    Base URL: https://api.tokenlab.sh/v1
    API Key: sk-your-tokenlab-key
    ```

    Cursor 內部使用 Anthropic 風格的工具格式。TokenLab 兩者皆支援：

    * OpenAI 格式：`{ type: "function", function: { name, parameters } }`
    * Anthropic 格式：`{ name, input_schema }` (無 type 欄位)
  </Tab>

  <Tab title="Claude Code">
    ```bash theme={null}
    export ANTHROPIC_BASE_URL="https://api.tokenlab.sh"
    export ANTHROPIC_API_KEY="sk-your-tokenlab-key"
    ```
  </Tab>

  <Tab title="OpenCode">
    ```bash theme={null}
    export OPENAI_API_KEY="sk-your-tokenlab-key"
    export LOCAL_ENDPOINT="https://api.tokenlab.sh/v1"
    ```
  </Tab>

  <Tab title="Aider">
    ```bash theme={null}
    export OPENAI_API_KEY="sk-your-tokenlab-key"
    export OPENAI_BASE_URL="https://api.tokenlab.sh/v1"
    aider --model gpt-5.4
    ```
  </Tab>
</Tabs>

## SDK 相容性

### 已記錄的 SDK 與框架路徑

| SDK / 框架                                                 | 語言                      | 支援層級                   | 備註                                                                                                                |
| -------------------------------------------------------- | ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **OpenAI SDK**                                           | Python/JS/Go            | 支援核心路徑                 | 用於 `/v1` Chat Completions 和 Embeddings 的相容路徑；針對提供者特定行為請使用原生提供者路由，且不要假設僅限 Responses 的欄位適用於所有模型                     |
| **Anthropic SDK**                                        | Python/JS               | 強原生路徑                  | 原生 Messages 路由，直接支援 tools、thinking 和 prompt caching                                                               |
| **Vercel AI SDK**                                        | TypeScript              | 建議整合模式                 | 優先使用 `@ai-sdk/openai-compatible`；僅在明確需要 Responses 原生行為時才使用 `@ai-sdk/openai`                                       |
| **LangChain**                                            | Python/JS               | 支援標準介面                 | `ChatOpenAI` 和 `OpenAIEmbeddings` 為預期範圍；廠商原生擴充功能不在範圍內                                                             |
| **LlamaIndex**                                           | Python                  | 透過 `OpenAILike` 支援     | 對於 TokenLab 等第三方閘道，請使用 `OpenAILike` 而非內建的 OpenAI 類別                                                               |
| **OpenAI Agents SDK**                                    | Python                  | 支援 chat-completions 路徑 | 使用 `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` 搭配 `OpenAIChatCompletionsModel`；原生 Responses 行為取決於所選模型與路由 |
| **AutoGen**                                              | Python                  | 支援自訂端點路徑               | 使用 `OpenAIChatCompletionClient` 並設定 `base_url: https://api.tokenlab.sh/v1`                                        |
| **Semantic Kernel**                                      | .NET                    | 支援自訂端點路徑               | 使用 OpenAI 聊天完成連接器的自訂端點，並指向 `https://api.tokenlab.sh/v1`                                                           |
| **CrewAI**                                               | Python                  | 支援自訂端點路徑               | 將 `OPENAI_API_BASE` 或 `LLM(base_url=...)` 設定為 TokenLab 的 `/v1` 端點                                                 |
| **Pydantic AI**                                          | Python                  | 支援 OpenAI 相容提供者路徑      | 使用 `OpenAIChatModel` 搭配 `OpenAIProvider(base_url="https://api.tokenlab.sh/v1")`                                   |
| **DSPy**                                                 | Python                  | 支援自訂端點路徑               | 使用 `dspy.LM("openai/<model>", api_base="https://api.tokenlab.sh/v1")`                                             |
| **Langflow**                                             | Python / Web            | 支援（有限制）                | 使用 OpenAI 元件的 **OpenAI API Base** 欄位並填入 TokenLab 的 `/v1` 端點                                                       |
| **Haystack**                                             | Python                  | 支援自訂端點路徑               | 使用 `OpenAIChatGenerator(api_base_url="https://api.tokenlab.sh/v1")`                                               |
| **Graphiti**                                             | Python                  | 支援自訂端點路徑               | 使用 `OpenAIGenericClient` 搭配 TokenLab 的 `/v1` 端點                                                                   |
| **Dify**                                                 | -                       | 支援（有限制）                | 預期路徑為 OpenAI 提供者與 chat-completions 導向流程；不適用於 Codex 特定的 Responses 或 WebSocket 行為                                   |
| **Flowise**                                              | Web / Node              | 支援（有限制）                | 若可用請使用 TokenLab 聊天節點，或使用指向 `https://api.tokenlab.sh/v1` 的 ChatOpenAI 相容節點                                         |
| **Mem0**                                                 | Python                  | 支援自訂端點路徑               | 保留 OpenAI 提供者並將 `openai_base_url` 設定為 TokenLab 的 `/v1` 端點                                                         |
| **Agno**                                                 | Python                  | 支援路徑                   | 若可用請使用 TokenLab 模型封裝，或使用 OpenAI 相容的基礎 URL 路徑                                                                      |
| **Browser Use**                                          | Python                  | 支援自訂端點路徑               | 使用 `ChatOpenAILike` 搭配 TokenLab 的 `/v1` 端點                                                                        |
| **VoltAgent**                                            | TypeScript              | 支援自訂端點路徑               | 傳入設定為 `baseURL: "https://api.tokenlab.sh/v1"` 的 AI SDK OpenAI 提供者                                                 |
| **Ragas**                                                | Python                  | 支援自訂端點路徑               | 將 `AsyncOpenAI(base_url="https://api.tokenlab.sh/v1")` 傳入 `llm_factory`                                           |
| **Guardrails**                                           | Python                  | 支援驗證路徑                 | 傳入設定為 TokenLab `/v1` 端點的 OpenAI SDK 聊天完成可呼叫物件                                                                     |
| **Prompt flow**                                          | Python / CLI            | 支援自訂端點路徑               | 建立一個 `base_url=https://api.tokenlab.sh/v1` 的 OpenAI 連線                                                            |
| **Promptfoo**                                            | CLI / Node              | 支援路徑                   | 使用 `apiBaseUrl: https://api.tokenlab.sh/v1` 的 OpenAI 聊天或 Responses 提供者                                            |
| **Portkey Gateway**                                      | Gateway                 | 支援路徑                   | 將 TokenLab 作為 OpenAI 相容聊天與 Responses 流量的上游提供者                                                                     |
| **Helicone**                                             | Gateway / Observability | 支援可觀測性路徑               | 透過 Helicone Gateway 路由 OpenAI 相容請求，並設定 `Helicone-Target-Url: https://api.tokenlab.sh`                             |
| **Langfuse**                                             | Observability           | 支援追蹤路徑                 | 使用 TokenLab 的 `/v1` 基礎 URL 設定 Langfuse OpenAI 整合                                                                  |
| **OpenLIT**                                              | Observability           | 支援追蹤路徑                 | 對設定為 TokenLab `/v1` 基礎 URL 的 OpenAI SDK 客戶端進行檢測                                                                   |
| **OpenLLMetry**                                          | Observability           | 支援追蹤路徑                 | 使用設定為 TokenLab `/v1` 基礎 URL 的 OpenAI SDK 檢測                                                                       |
| **Phoenix**                                              | Observability           | 支援追蹤路徑                 | 自動檢測設定為 TokenLab `/v1` 基礎 URL 的 OpenAI SDK 客戶端                                                                    |
| **Opik**                                                 | Observability           | 支援追蹤路徑                 | 封裝設定為 TokenLab `/v1` 基礎 URL 的 OpenAI SDK 客戶端                                                                      |
| **LangBot**                                              | Bot Platform            | 支援聊天路徑                 | 若可用請使用 TokenLab 請求器，或設定指向 TokenLab `/v1` 端點的 OpenAI 相容請求器                                                         |
| **Open WebUI**                                           | Web Chat                | 支援聊天應用路徑               | 新增 TokenLab 作為 OpenAI 相容 API 連線並重新整理模型列表                                                                          |
| **Chatbox / DeepChat / Jan / LibreChat / Cherry Studio** | Desktop / Web           | 支援聊天應用路徑               | 使用各應用程式的 OpenAI 相容自訂提供者流程；這些應用通常以 chat-completions 為導向                                                            |

## Chat Completions 參數

### 核心參數

| 參數            | 類型      | 描述           |
| ------------- | ------- | ------------ |
| `model`       | string  | 模型識別碼 (必填)   |
| `messages`    | array   | 對話訊息 (必填)    |
| `max_tokens`  | integer | 最大輸出 token 數 |
| `temperature` | number  | 取樣溫度 (0-2)   |
| `top_p`       | number  | 核取樣 (0-1)    |
| `stream`      | boolean | 啟用串流         |

### 工具呼叫 (Tool Calling)

```json theme={null}
{
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": { "type": "string" }
          }
        },
        "strict": true
      }
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true
}
```

### 工具選擇選項 (Tool Choice Options)

| 格式           | 範例                                                                    | 描述             |
| ------------ | --------------------------------------------------------------------- | -------------- |
| 字串           | `"auto"`, `"none"`, `"required"`                                      | 簡單選擇           |
| OpenAI 物件    | `{ "type": "function", "function": { "name": "fn" } }`                | 強制指定函式         |
| Anthropic 物件 | `{ "type": "tool", "name": "fn", "disable_parallel_tool_use": true }` | Anthropic 原生格式 |

### 進階參數

| 參數                  | 類型           | 描述                                                         |
| ------------------- | ------------ | ---------------------------------------------------------- |
| `stream_options`    | object       | 僅限 Chat Completions：`{ include_usage: true }` 以取得 token 計數 |
| `reasoning_effort`  | string       | 針對啟用推理功能的 GPT-5 模型：`"low"`, `"medium"`, `"high"`           |
| `service_tier`      | string       | `"auto"` 或 `"default"`                                     |
| `seed`              | integer      | 確定性輸出                                                      |
| `logprobs`          | boolean      | 回傳對數機率                                                     |
| `top_logprobs`      | integer      | 前 N 個對數機率 (0-20)                                           |
| `logit_bias`        | object       | Token 偏差映射 (-100 到 100)                                    |
| `frequency_penalty` | number       | 重複懲罰 (-2 到 2)                                              |
| `presence_penalty`  | number       | 主題懲罰 (-2 到 2)                                              |
| `stop`              | string/array | 停止序列                                                       |
| `n`                 | integer      | 完成次數 (1-128)                                               |
| `user`              | string       | 用於追蹤的使用者識別碼                                                |

### OpenAI 進階功能

| 參數           | 類型      | 描述                        |
| ------------ | ------- | ------------------------- |
| `modalities` | array   | 多模態設定：`["text", "audio"]` |
| `audio`      | object  | 音訊輸出設定 (語音、格式)            |
| `prediction` | object  | 預測輸出以加速完成                 |
| `metadata`   | object  | 用於追蹤的鍵值對                  |
| `store`      | boolean | 儲存以供後續檢索                  |

### 提供者特定選項

```json theme={null}
{
  "anthropic_options": {
    "thinking": {
      "type": "enabled",
      "budget_tokens": 10000
    },
    "prompt_caching": true
  },
  "google_options": {
    "safety_settings": [...],
    "google_search": true,
    "code_execution": true
  }
}
```

## Anthropic Messages 參數

### 核心參數

| 參數           | 類型           | 描述               |
| ------------ | ------------ | ---------------- |
| `model`      | string       | 模型識別碼            |
| `messages`   | array        | 對話訊息             |
| `max_tokens` | integer      | 最大輸出 (最高 128000) |
| `system`     | string/array | 系統提示詞            |
| `stream`     | boolean      | 啟用串流             |

### 工具呼叫 (Tool Calling)

```json theme={null}
{
  "tools": [
    {
      "name": "get_weather",
      "description": "Get weather",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": { "type": "string" }
        }
      }
    }
  ],
  "tool_choice": {
    "type": "auto",
    "disable_parallel_tool_use": false
  }
}
```

### 擴充推理 (Extended Thinking)

```json theme={null}
{
  "model": "claude-opus-4-6",
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}
```

## Responses API 參數

### 核心參數

| 參數                     | 類型           | 描述           |
| ---------------------- | ------------ | ------------ |
| `model`                | string       | 模型識別碼        |
| `input`                | string/array | 輸入內容         |
| `instructions`         | string       | 系統指令         |
| `max_output_tokens`    | integer      | 最大輸出 token 數 |
| `previous_response_id` | string       | 延續對話         |

### 進階參數

| 參數                    | 類型     | 描述                                |
| --------------------- | ------ | --------------------------------- |
| `truncation_strategy` | string | `"auto"` 或 `"disabled"`           |
| `include`             | array  | `["reasoning.encrypted_content"]` |
| `reasoning_effort`    | string | 針對推理模型                            |
| `service_tier`        | string | 優先級層級                             |

### 工具格式

支援 OpenAI 與 Anthropic 工具格式：

```json theme={null}
// OpenAI 格式
{ "type": "function", "name": "fn", "parameters": {...} }

// Anthropic 格式 (Cursor 相容性)
{ "name": "fn", "input_schema": {...} }
```

## Gemini API 參數

### 核心參數

| 參數                  | 類型     | 描述    |
| ------------------- | ------ | ----- |
| `contents`          | array  | 對話內容  |
| `systemInstruction` | object | 系統提示詞 |
| `generationConfig`  | object | 生成設定  |

### 工具 (Tools)

```json theme={null}
{
  "tools": [{
    "functionDeclarations": [{
      "name": "search",
      "description": "Search the web",
      "parameters": {...}
    }],
    "codeExecution": {},
    "googleSearch": {}
  }],
  "toolConfig": {
    "functionCallingConfig": {
      "mode": "AUTO"
    }
  }
}
```

### 安全設定 (Safety Settings)

```json theme={null}
{
  "safetySettings": [
    {
      "category": "HARM_CATEGORY_HARASSMENT",
      "threshold": "BLOCK_MEDIUM_AND_ABOVE"
    }
  ]
}
```

### 其他參數

| 參數                 | 類型     | 描述                                    |
| ------------------ | ------ | ------------------------------------- |
| `cachedContent`    | string | 快取內容參照                                |
| `responseMimeType` | string | `"text/plain"` 或 `"application/json"` |
| `responseSchema`   | object | 用於結構化輸出的 JSON schema                  |

## 串流 (Streaming)

支援 `stream: true` 的生成端點（包含 Chat Completions 與 Responses）使用 Server-Sent Events (SSE)：

```bash theme={null}
# Chat Completions
curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -d '{"model": "gpt-4o", "messages": [...], "stream": true}'

# Chat Completions 使用量追蹤
-d '{"...", "stream_options": {"include_usage": true}}'
```

## 錯誤處理

TokenLab 回傳 OpenAI 相容的錯誤回應：

```json theme={null}
{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_api_key",
    "code": "invalid_api_key"
  }
}
```

詳情請參閱 [錯誤處理指南](/guides/error-handling)。

## 最佳實踐

<AccordionGroup>
  <Accordion title="針對未知參數使用透傳 (passthrough)">
    未知參數僅在所選的公開路由與模型支援時才會被轉發。
  </Accordion>

  <Accordion title="僅在 Chat Completions 使用 stream_options.include_usage">
    對於 Chat Completions 串流，請啟用 `stream_options.include_usage` 以取得準確的 token 計數。Responses 擁有自己的串流合約，並不公開此 Chat 專用選項。
  </Accordion>

  <Accordion title="使用適當的 tool_choice 格式">
    請符合您 SDK 預期的格式。TokenLab 同時接受 OpenAI 與 Anthropic 格式。
  </Accordion>
</AccordionGroup>