5 分鐘內從 OpenAI 遷移至 TokenLab

更換服務提供商時，修改 Base URL 是最簡單的部分；遷移失敗通常源於錯誤處理路徑。若要從 OpenAI 遷移至 TokenLab，您只需更改 OpenAI SDK 客戶端中的兩個值：base_url 和 api_key。本指南的其餘部分將涵蓋您在進行此變更時需要確認的事項，包括：您發送的模型 ID、當前價格、串流 (Streaming)、工具呼叫 (Tool calls)、錯誤處理、逾時 (Timeouts) 以及計費。以下資訊來自 TokenLab 文件及即時模型 API，並標註了觀察日期。

重點摘要

• 核心變更為兩個值：TokenLab 的 Base URL https://api.tokenlab.sh/v1 以及 TokenLab API 金鑰（以 sk- 開頭）。
• TokenLab 的文件支援 Chat Completions 和 Responses 的 OpenAI SDK。選用參數、工具選項以及僅限 Responses 的欄位仍取決於所選模型。
• 在做任何決定前，請先從即時 API 讀取模型的價格。於 2026-10-03，gpt-5.5 的價格為每 100 萬個 token 輸入 1.50 美元，輸出 9.00 美元。
• 在將生產流量遷移過來之前，請先執行結尾的檢查清單。大多數突發狀況都發生在錯誤處理、逾時和計費中，而非順利的執行路徑上。

從 OpenAI 遷移至 TokenLab 的兩項數值變更

首先從金鑰開始。根據 快速入門 (Quickstart)（觀察日期 2026-10-03），您需要建立帳戶、建立 API 金鑰，並立即儲存完整數值。該數值僅顯示一次，且金鑰列表中的前綴無法用於驗證請求。在進行首次呼叫前請先檢查餘額，因為請求會依照所選模型的當前價格計費。

接著更改客戶端。遷移指南（觀察日期 2026-10-03）描述的操作步驟為：將 base_url / baseURL 設定為 https://api.tokenlab.sh/v1，替換金鑰，並從 GET /v1/models 選擇一個模型 ID。

例如，假設某個服務的設定中包含字串 gpt-5.5。在進行兩項數值變更後，該字串依然是有效的請求，但我們仍建議先確認該 ID。GET /v1/models 和 GET /v1/models/{model} 是公開的探索端點，無需金鑰即可運作。

Python

import os
from openai import OpenAI

# Before: client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
client = OpenAI(
    api_key=os.environ["TOKENLAB_API_KEY"],
    base_url="https://api.tokenlab.sh/v1",
    timeout=30.0,
    max_retries=0,
)

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello, world!"}],
)
print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai';

// Before: new OpenAI({ apiKey: process.env.OPENAI_API_KEY })
const client = new OpenAI({
  apiKey: process.env.TOKENLAB_API_KEY,
  baseURL: 'https://api.tokenlab.sh/v1',
  timeout: 30_000,
  maxRetries: 0,
});

const completion = await client.chat.completions.create({
  model: 'gpt-5.5',
  messages: [{ role: 'user', content: 'Hello' }],
});
console.log(completion.choices[0].message.content);

cURL

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer $TOKENLAB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[{"role":"user","content":"Say hello"}]}'

前兩個範例中的逾時和重試設定反映了快速入門範例（觀察日期 2026-10-03），該範例使用 30 秒逾時和零 SDK 重試。我們在測試期間將重試次數設為零，以便讓失敗的請求顯現出來，而不是靜默重試。

請在客戶端設定中明確傳遞 Base URL。SDK 指南（觀察日期 2026-10-03）建議採用此方式，而非依賴較舊的環境變數別名。請將金鑰保留在伺服器端和密鑰管理服務中，切勿放入客戶端程式碼。

選擇模型 ID 並讀取其價格

遷移時不應預設模型 ID 或價格，兩者皆存在於模型 API 中。我們於 2026-10-03 讀取了 https://api.tokenlab.sh/v1/models/gpt-5.5 和 https://api.tokenlab.sh/v1/models/laguna-s-2.1。兩者的定價皆於 2026-10-02T16:53:30.068Z 最後更新。

欄位	gpt-5.5	laguna-s-2.1
生命週期階段	active	active
最大輸入 / 輸出 tokens	1,000,000 / 128,000	1,048,576 / 131,072
接受的請求格式	openai_chat_completions, openai_responses	openai_chat_completions
列出的功能	coding, json-mode, prompt-cache, reasoning, tool-use, vision	tool-use
輸入，每 1M tokens 美元	1.5	0.1
輸出，每 1M tokens 美元	9	0.2
快取讀取，每 1M tokens 美元	0.15	0.01

資料來源：gpt-5.5 和 laguna-s-2.1，皆於 2026-10-03 觀察。

若要將這些費率轉換為實際金額，以下是計算範例。假設一個工作包含 100 萬個輸入 token 和 10 萬個輸出 token，且沒有快取命中。

• gpt-5.5：1 × $1.50 + 0.1 × $9.00 = $1.50 + $0.90 = $2.40。
• laguna-s-2.1：1 × $0.10 + 0.1 × $0.20 = $0.10 + $0.02 = $0.12。

這些是根據列出的每 token 費率所做的估算。您的最終費用以使用量 (Usage) 紀錄為準。Tokenization 方式因模型而異，因此相同的文字在不同模型上會產生不同的 token 數量。

我們在此不宣稱一定能節省費用。若要與您目前的支出進行比較，請在切換當天將 TokenLab 的費率與您的 OpenAI 發票或 OpenAI 定價頁面進行對照。價格會變動，且計費指南（觀察日期 2026-10-03）建議不要將複製的價格表寫死在程式碼中。指南建議使用 GET /v1/models/:model/pricing 來獲取當前數值。

其他模型 ID 遵循相同的模式。文件範例在 Chat Completions 中使用 gpt-5.6-terra 和 gpt-5.6-luna，並在各自的路由上使用 claude-sonnet-5 和 gemini-3.5-flash。在將流量導向模型前，請先閱讀每個模型接受的格式。如需更廣泛的比較，請參閱模型目錄、OpenRouter 與 TokenLab 比較以及模型排名。圖像和影片團隊可從 2026 年最佳 AI 圖像模型 API 與 2026 年最佳 AI 影片模型 API 開始。關於程式碼任務，請參閱最佳 AI 程式碼模型。

遷移至 TokenLab 後的下一步檢查

TokenLab 的文件指出 OpenAI SDK 可與 Chat Completions 和 Responses 搭配使用。這代表請求與回應格式的相容性，並不保證每個模型的行為完全一致。API 格式指南（觀察日期 2026-10-03）指出選用參數取決於模型。它也提到模型不一定接受所有四種 API 格式，且 tokenlab.accepted_request_formats 會顯示該模型接受的格式。請將以下每個領域視為需要透過實際流量進行測試的項目。

串流 (Streaming)

stream: true 會以伺服器發送事件 (SSE) 的形式發送部分訊息增量。根據 建立 Chat Completion 參考文件（觀察日期 2026-10-03），請設定 stream_options 並將 include_usage 設為 true，以便在串流區塊中接收 token 使用量。

stream = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Count to five."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        print(chunk.choices[0].delta.content or "", end="")

有兩種行為需要規劃。如果串流在輸出到達後中斷，請勿將其視為完整回應。錯誤處理指南（觀察日期 2026-10-03）警告說，重複執行可能會產生不同的輸出或產生第二次計費。此外，串流可能會在計費完成前結束，因此計費 ID 可能會缺失。

工具呼叫 (Tool calls)

Chat Completions 參考文件列出了 tools、tool_choice 和 parallel_tool_calls。文件指出平行呼叫在「所選模型支援時」有效。函式呼叫被記錄為「由所選模型支援」，因此請檢查功能列表。在上表中，gpt-5.5 和 laguna-s-2.1 皆列出了 tool-use，但只有 gpt-5.5 列出了 json-mode 和 vision。請發送您真實的工具結構 (schemas)，而非範例，並檢查回傳的參數是否能正確解析。

如果您打算呼叫 Claude 模型，請注意遷移指南的規則。Claude 的工具呼叫、思考區塊 (thinking blocks) 和 Anthropic 訊息欄位屬於 /v1/messages，Chat Completions 不保證支援這些功能。

錯誤形狀 (Error shapes)

Chat Completions 和 Responses 會回傳 OpenAI 風格的 error 物件。根據錯誤處理指南，只有 message 和 type 是必定存在的。諸如 code、param、 retryable 和 retry_after 等欄位僅在相關時出現。請根據 HTTP 狀態碼和 code 進行分支處理，而非根據訊息文字，並確保您的解析器能容忍缺失的欄位。Anthropic Messages 和 Gemini 保留其各自的錯誤格式，因此單一解析器無法涵蓋所有路由。

狀態碼	代碼	含義
401	invalid_api_key	金鑰缺失、無效、未啟用或已撤銷
401	expired_api_key	金鑰已過期
402	insufficient_balance	帳戶餘額不足以支付請求
402	quota_exceeded	已達到該金鑰的使用限制
403	model_not_allowed	此金鑰無法使用所請求的模型
429	rate_limit_exceeded	請求過多；請等待 Retry-After

資料來源：身分驗證 和 錯誤處理，觀察日期 2026-10-03。

此表修正了一個常見假設：餘額不足是 402，而非 401。如果您的現有程式碼將所有 4xx 視為金鑰錯誤，請務必更新。

逾時與重試

遷移指南指出，現有的重試、逾時和串流程式碼通常可以保留。請根據記錄的重試規則進行審查。

• 請勿原樣重複 400、401、402、403、404 或 413 回應。
• 在伺服器提供的延遲後重試 429。
• 僅在 retryable 為 true 時重試 500–504，並遵守 retry_after。
• 503 all_channels_failed 可能會回傳 retryable: false。在這種情況下，該作業在所選的交付層中沒有供應，因此重複執行無濟於事。

請將回應標頭中的 Request ID 與模型及您自己的工作 ID 一起儲存，這是進行調查時所需的資訊。

計費

根據計費指南，單一餘額適用於所有模型，無訂閱或最低消費要求。每個完成的請求都會針對產生該請求的交付選項收取一次費用。選項包括 TokenLab Verified、Official 和 Auto，其中 Auto 會優先嘗試 Verified，然後是 Official。若您需要強制停止，請為每個 API 金鑰設定消費上限。當達到上限時，使用該金鑰的請求將回傳 402。

非串流的 OpenAI 相容回應會在計費於回應發送前完成時包含 billing_transaction_id。它也可能出現在 X-Billing-Transaction-ID 標頭中。請儲存該 ID，並與使用量頁面進行對帳，而非依賴您自己的 token 計算。

遷移至 TokenLab 後的驗證檢查清單

在生產流量遷移前，請依序針對測試金鑰執行這些步驟。每一行皆對應上述記錄的行為。

步驟	執行項目	預期結果
1. 模型探索	GET /v1/models/gpt-5.5 (無需金鑰)	生命週期為 active 以及您計劃使用的格式
2. 驗證請求	上述 Python 或 cURL 範例	非空回應；請求出現在 Requests 檢視中，包含模型、狀態和使用量
3. 使用量欄位	讀取非串流回應的 usage	prompt_tokens, completion_tokens, total_tokens
4. 串流	stream: true 搭配 include_usage: true	SSE 區塊，隨後是使用量；中斷的串流被視為不完整
5. 工具呼叫	您真實的 tools 和 tool_choice	參數解析成功並符合您的結構
6. Vision 或 JSON 模式	僅當模型列出 vision 或 json-mode 時	預期輸出；若未列出該功能則跳過測試
7. 金鑰錯誤	使用已刪除或錯誤的金鑰請求	401 invalid_api_key
8. 無餘額或金鑰限制	使用低限額金鑰或空工作區	402 insufficient_balance 或 quota_exceeded
9. 模型限制	限制金鑰的模型列表，然後請求其他模型	403 model_not_allowed
10. 逾時與重試	在測試環境中強制逾時	您的程式碼僅根據 retryable 和 retry_after 進行重試
11. 計費	比較 billing_transaction_id 和使用量與您的估算	費用符合模型的當前價格與記錄的 token 數

在通過上述表格檢查後，請更改您的生產環境設定並部署。在確認新路徑穩定之前，請保持舊的 OpenAI 金鑰處於啟用狀態。

常見問題解答

從 OpenAI 切換時，我需要更改模型名稱嗎？

不一定，但請務必確認每一個名稱。TokenLab 模型 ID 是精確的字串，請使用 GET /v1/models 或 GET /v1/models/{model} 進行檢查。於 2026-10-03，即時 API 將 gpt-5.5 列為 active。如果請求回傳 model_not_found，則代表該 ID 未知或不可用。請閱讀模型列表並使用當前的 ID。

串流和工具呼叫的行為會與 OpenAI 的 API 完全相同嗎？

TokenLab 透過 SSE 記錄串流，並透過 OpenAI 相容的請求格式記錄函式呼叫。文件也指出支援的選項取決於所選模型。因此，我們將結果視為相容，而非完全相同。請使用您計劃執行的特定模型來測試串流、tools、tool_choice 以及您使用的任何 response_format。

當餘額用盡時，我會收到什麼狀態碼？

您會收到 HTTP 402，代碼為 insufficient_balance。達到自身消費上限的金鑰也會回傳 402，代碼為 quota_exceeded。缺失、無效或已撤銷的金鑰會回傳 401。請勿原樣重試這些請求。請儲值餘額、提高金鑰限額或更換金鑰。

我可以從同一個 OpenAI 客戶端呼叫 Claude 或 Gemini 模型嗎？

模型目錄將 claude-sonnet-5 和 gemini-3.5-flash 列為包含 openai_chat_completions 請求格式。因此，基礎聊天可以透過同一個客戶端進行。Claude 特有的欄位（如思考區塊和 Claude 工具使用）屬於 /v1/messages。Gemini 原生欄位保留在 /v1beta 路由上。請在每個對話中保持使用一種 API 格式。

開始在 TokenLab 上開發

請在 TokenLab 建立金鑰，將 Base URL 設定為 https://api.tokenlab.sh/v1，並在觸及生產環境前執行快速入門請求。