核心指南
API 格式
選擇 Chat Completions、Responses、Messages 或 Gemini
一個 TokenLab API key 可與四種常見的 API 格式搭配使用。除非您需要特定模型的功能,否則請保留應用程式目前使用的格式。
| 格式 | 端點 | 選擇時機 |
|---|---|---|
| Chat Completions | /v1/chat/completions | 您使用與 OpenAI 相容的聊天客戶端,或需要廣泛的模型相容性 |
| Responses | /v1/responses | 您的應用程式使用 Responses 事件、背景回應或 Responses 工具 |
| Anthropic Messages | /v1/messages | 您需要 Claude Messages 欄位,例如思考過程 (thinking) 或 Claude 工具使用 |
| Gemini | /v1beta/models/:model:generateContent | 您已經在使用 Gemini contents、parts、files、cache 或 Gemini 工具 |
請查看模型頁面或 GET /v1/models/{model} 中的 tokenlab.accepted_request_formats。模型不一定會接受所有四種格式。
Chat Completions
對於現有的 OpenAI 相容客戶端和可攜式聊天功能,Chat Completions 是最簡單的選擇。
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-5.6-luna",
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)請在以下情況使用此格式:
- 現有的 OpenAI 相容聊天整合
- 標準訊息歷史記錄與串流
- 所選模型支援的函式呼叫 (function calling)
不保證其他 API 格式特有的欄位在此處能正常運作。
Responses
僅在所選模型於 accepted_request_formats 中列出 openai_responses 時,才使用 Responses。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh/v1",
)
response = client.responses.create(
model="gpt-5.6-terra",
input="Explain why the sky is blue in two sentences.",
)
print(response.output_text)Responses API 支援建立、檢索、壓縮、刪除、串流、WebSocket 建立與延續,以及所選模型支援的背景回應。刪除操作會移除已儲存的回應;它不會取消正在進行中的回應。
Anthropic Messages
使用 Anthropic SDK 搭配 TokenLab 主機,且無需在 base URL 中加入 /v1。
import os
from anthropic import Anthropic
client = Anthropic(
api_key=os.environ["TOKENLAB_API_KEY"],
base_url="https://api.tokenlab.sh",
)
message = client.messages.create(
model="claude-sonnet-5",
max_tokens=512,
messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)針對 Claude 特有的請求與回應欄位,請選擇 Messages。請在此格式中保留 Claude 工具呼叫、思考區塊 (thinking blocks) 和 prompt-cache 欄位。
Gemini
Gemini 請求使用 TokenLab 主機與 Gemini REST 路徑。
curl "https://api.tokenlab.sh/v1beta/models/gemini-3.6-flash:generateContent" \
-H "Authorization: Bearer $TOKENLAB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contents": [{"parts": [{"text": "Hello!"}]}]
}'當您的應用程式已經在使用 Gemini content parts、函式宣告、檔案、快取內容或其他 Gemini 欄位時,請選擇 Gemini。系統同時接受 lowerCamelCase 的 ProtoJSON 名稱與原始 snake_case 的 proto 名稱;請避免在同一個請求中同時傳送同一欄位的兩種拼寫方式。
請勿在同一個對話中混合使用格式
Messages、Responses、Chat Completions 和 Gemini 對對話狀態與工具呼叫的表示方式不同。請在同一個對話中保持使用單一格式。如果您必須遷移已儲存的歷史記錄,請在傳送下一個請求之前,先在您的應用程式中進行轉換與驗證。
未知欄位
TokenLab 可能會傳遞它無法識別的欄位,但這並不代表每個模型都接受這些欄位。只有在所選模型有相關文件說明,且您的應用程式能處理「不支援的欄位」錯誤時,依賴該功能才是安全的。