Skip to main content

概覽

TokenLab 以一組 API 金鑰提供四個協議介面:Chat Completions、Responses、Anthropic Messages 與 Gemini 原生協議。只有模型公開該格式且存在同協議 upstream 路徑時,原生入口才可用;原生入口絕不回落 Chat Completions。只有 Chat 入口可以單向編譯至相容的目標協議。

OpenAI 格式

/v1/chat/completions 標準格式,最高相容性

Responses

/v1/responses 原生 Responses 生命週期與事件

Anthropic 格式

/v1/messages 延伸思考,Claude 原生功能

Gemini 格式

/v1beta/models/:model:generateContent 整合 Google 生態系

為何使用多格式?

格式比較

OpenAI 格式

這是面向已有 OpenAI SDK 整合、可移植聊天或 embeddings 的相容路由。需要 Claude 或 Gemini 原生行為時,請使用下面的 Anthropic 或 Gemini 格式。
適用情境:
  • 一般用途
  • 既有 OpenAI SDK 整合
  • 最高相容性

Anthropic 格式

Anthropic 原生 Messages API。若要使用 Claude 特有功能(例如延伸思考),需使用此格式。

延伸思考(Claude Opus 4.6)

僅在 Anthropic 格式中提供:
適用情境:
  • Claude 特有功能
  • 延伸思考模式
  • 使用原生 Anthropic SDK 的用戶

Gemini 格式

原生 Google Gemini API 格式,便於整合 Google 生態系。

串流

適用情境:
  • Google Cloud 整合
  • 既有 Gemini SDK 程式碼
  • 原生 Gemini 功能
Gemini Files 和 Cache: 原生 Gemini 路徑支援 /upload/v1beta/files/v1beta/files/v1beta/files:register/v1beta/cachedContents。Files 使用相容 Gemini File API 的上游渠道;顯式 Cache 資源也可以走 Vertex AI 渠道。透過 TokenLab 建立的資源會綁定到同一個上游渠道/key,後續 generateContent 會沿用該綁定。

工具相容邊界

只有 Chat 入口可在目標能完整表達工具閉環時單向編譯函式工具。供應商原生工具必須保留在對應的原生路徑上:
  • OpenAI Responses 託管和原生工具,例如 tool_searchweb_searchfile_searchcode_interpreter、MCP、shell/apply_patch 和 computer-use 工具,需要 /v1/responses
  • Anthropic server/native 工具,例如 web_search_*web_fetch_*code_execution_*tool_search_*、bash、computer-use 和 text-editor 工具,需要 /v1/messages
  • Gemini 內建工具,例如 googleSearchcodeExecutionurlContextcomputerUse 以及類似的 tools 欄位,需要 /v1beta
TokenLab 不會將原生協議請求降級成 Chat Completions。未知欄位與工具組合會 best-effort 透傳,由選中的 upstream 決定是否支援。

選擇合適的格式

遷移指南

從 OpenAI 官方 API 遷移

從 Anthropic 官方 API 遷移

從 Google AI Studio 遷移

可攜式 Chat 相容性

當單一客戶端需要存取由不同 upstream 協議承載的模型時,請使用 /v1/chat/completions。可攜式 Chat 請求只有在能完整表達時,才可單向編譯成 Responses、Messages 或 Gemini。Responses、Messages 與 Gemini 原生請求絕不轉成 Chat;模型名或供應商名不代表原生協議一定可用。

Responses 與 Gemini 邊界

目前 Responses 介面包含建立、壓縮、讀取、刪除與 SSE;background 僅透過 HTTP 執行。WebSocket 只接受 response.create,stream 為隱含行為,且不提供 backgroundresponse.cancel。刪除不是取消。 Gemini 的 ProtoJSON lowerCamelCase 與原始 proto snake_case 名稱都是官方拼法,混合請求也會原樣保留。目前介面包含 model list/get、generateContentstreamGenerateContentcountTokensembedContentbatchEmbedContents,不包含 Interactions 或 Live。未知欄位會 best-effort 透傳,由 upstream 決定是否支援。