TokenLab

核心指南

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 可能會傳遞它無法識別的欄位,但這並不代表每個模型都接受這些欄位。只有在所選模型有相關文件說明,且您的應用程式能處理「不支援的欄位」錯誤時,依賴該功能才是安全的。

相關參考

本頁內容