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

# 遷移指南

> 將 OpenAI、Anthropic、Gemini 和媒體工作負載以小型、適合生產的變更移動到 TokenLab。

TokenLab 是多格式的：您可以保持 OpenAI 兼容的客戶端、Anthropic 原生的 Messages 調用、Gemini 原生的 REST 調用，以及媒體端點的自然形狀。最安全的遷移方式不是將每個工作負載轉換為一種通用格式。選擇擁有您的應用程序所需行為的路徑。

## 路徑映射

| 現有工作負載        | TokenLab 基本 URL              | 主要端點                                    | 遷移說明                                  |
| ------------- | ---------------------------- | --------------------------------------- | ------------------------------------- |
| OpenAI 聊天完成   | `https://api.tokenlab.sh/v1` | `/chat/completions`                     | 對於 OpenAI 兼容的聊天和函數調用，變更最小             |
| OpenAI 回應     | `https://api.tokenlab.sh/v1` | `/responses`                            | 當您的應用依賴於特定於回應的輸入、工具或輸出處理時使用           |
| Anthropic SDK | `https://api.tokenlab.sh`    | `/v1/messages`                          | 不要在 SDK 基本 URL 後附加 `/v1`              |
| Gemini REST   | `https://api.tokenlab.sh`    | `/v1beta/models/:model:generateContent` | 在 Gemini 路徑上保持 Gemini 原生字段            |
| 媒體生成          | `https://api.tokenlab.sh/v1` | `/images`, `/videos`, `/music`, `/3d`   | 使用 `recommended_for` 發現模型，並在文檔中預期異步輪詢 |
| 管理和計費         | `https://api.tokenlab.sh/v1` | `/management/...`                       | 對於伺服器端使用和計費對賬，使用管理令牌                  |

## OpenAI 兼容遷移

```python theme={null}
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh/v1",
)

response = client.chat.completions.create(
    model="gpt-5.4",
    messages=[{"role": "user", "content": "Hello from TokenLab"}],
)
```

保留您現有的重試、超時和流式代碼，但在生產流量之前使用 `GET /v1/models` 驗證模型 ID。對於圖像生成，明確發送 `model` 並閱讀圖像指南，因為圖像模型的差異大於聊天模型。

## Anthropic 遷移

```python theme={null}
from anthropic import Anthropic

client = Anthropic(
    api_key="sk-your-tokenlab-key",
    base_url="https://api.tokenlab.sh",
)

message = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explain TokenLab in one sentence."}],
)
```

對於 Claude 原生工具使用、思考流程和 Anthropic 消息語義，使用 `/v1/messages`。除非您故意想要 OpenAI 兼容的行為變更，否則不要通過聊天完成翻譯僅限於 Anthropic 的字段。

## Gemini 遷移

```bash theme={null}
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.5-flash:generateContent" \
  -H "Authorization: Bearer sk-your-tokenlab-key" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Hello"}]}]}'
```

當您的應用依賴於 Gemini 原生行為時，保持 Gemini 內置工具、文件 API 參考、緩存內容、函數聲明和原生內容部分在 `/v1beta` 上。

## 媒體遷移

1. 查詢 `GET /v1/models?recommended_for=image|video|music|3d`。
2. 在列表響應中閱讀 `tokenlab.public_contract_summary` 和可用的完整 `tokenlab.public_contract`。
3. 對於圖像端點，明確發送 `model`。
4. 存儲 `task_id`、`poll_url`、端點、模型和您自己的作業 ID 以進行異步作業。
5. 通過使用記錄和 `billing_transaction_id` 而不是供應商任務 ID 來對賬成本。

媒體工作負載需要自己的推出計劃，因為延遲、重試和最終資產的行為與聊天完成不同。

## 生產推出計劃

| 階段       | 目標                         | 檢查                           |
| -------- | -------------------------- | ---------------------------- |
| 1. 清單    | 列出端點、模型、請求字段、流式/異步行為和計費擁有者 | 不假設任何隱藏的僅限供應商字段為公共           |
| 2. 單路徑試點 | 移動一個端點和一個模型系列              | 響應形狀、成本和日誌符合預期               |
| 3. 影子或樣本 | 將選定的輸出與之前的供應商進行比較          | 用戶可見的質量和延遲是可接受的              |
| 4. 漸進推出  | 按鍵、組織或功能標誌增加流量             | 監控 `4xx`、`5xx`、延遲、平衡和重複的異步作業 |
| 5. 清理    | 只有在穩定使用後才刪除舊的供應商路徑         | 回滾路徑和支持手冊已記錄                 |

## 遷移陷阱

* 如果您的應用需要原生的 Anthropic、Gemini 或 Responses 行為，請不要將每個模型放在一個 OpenAI 聊天完成路徑後面。
* 不要假設舊的圖像默認值。明確發送 `model`。
* 在檢查任務是否已經創建之前，請不要重試異步創建請求。
* 不要在您的日誌或 UI 中暴露供應商路由元數據。
* 不要使用供應商任務 ID 來比較計費。使用 TokenLab 使用記錄。

## API 參考

| 主題            | 參考                                                              |
| ------------- | --------------------------------------------------------------- |
| 多格式 API       | [多格式 API](/zh-Hant/guides/api-formats)                          |
| OpenAI SDK    | [OpenAI SDK](/zh-Hant/integrations/openai-sdk)                  |
| Anthropic SDK | [Anthropic SDK](/zh-Hant/integrations/anthropic-sdk)            |
| Gemini 原生     | [Gemini 原生 API](/zh-Hant/api-reference/gemini/generate-content) |
| 圖像生成          | [圖像生成](/zh-Hant/guides/image-generation)                        |
| 異步作業與輪詢       | [異步作業與輪詢](/zh-Hant/guides/async-jobs-polling)                   |