原生客戶端協定

版本與範圍

本頁原生介面在 v0.1.0-rc.1 之後引入，該版本不包含它們；在包含此功能的新版本發布之前使用源碼建置。

Codex、Claude、Antigravity 和 Grok Build 訂閱以及 API 渠道均可使用。Claude Messages、Gemini 生成、Responses 和 Chat Completions 是獨立於上游的用戶端格式。請求依密鑰資源群組的權限、路由與備援規則選擇支援模型的資源。API 渠道可獨立設定上游協定：Messages 可維持原生格式，也可轉換為 Chat Completions、Responses 或 Gemini。公開 SDK 整合保留明確輸出上限與未完成狀態；/v1/responses/compact 仍僅支援 Codex。真實服務商與用戶端相容性需另行驗證。

介面與認證

協定	介面	憑證
Claude Messages	`POST /v1/messages`	`x-api-key` 或 Bearer
Gemini JSON	`POST /v1beta/models/{model}:generateContent`	`x-goog-api-key`、Bearer 或 `key` 查詢參數
Gemini SSE	`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`	與 Gemini JSON 相同

使用 SubLane 個人金鑰。多個位置提供憑證時必須一致，無效 Authorization 不能回退到其他金鑰。優先使用請求頭，避免其他代理程式將查詢金鑰記錄到 URL 日誌。瀏覽器 Cookie 不能認證模型請求。

透過 GET /v1/models 取得群組內原生模型 ID。 Gemini 使用 URL 中的模型，內文 model 或 stream 不能覆蓋路由。

Claude 範例

在本地環境設定 SUBLANE_URL 和 SUBLANE_API_KEY，並用目錄中的 ID 取代佔位模型：

Claude Messages 请求

curl "$SUBLANE_URL/v1/messages" \
  -H "x-api-key: $SUBLANE_API_KEY" \
  -H 'anthropic-version: 2023-06-01' \
  -H 'content-type: application/json' \
  --data '{"model":"YOUR_MODEL_ID","max_tokens":1024,"messages":[{"role":"user","content":"Hello"}]}'

增加 "stream": true 使用命名 SSE 事件。工具、快取和 thinking 欄位的完整支援受所選供應商與 SDK 轉換路徑影響。

Gemini 範例

Gemini 生成请求

curl "$SUBLANE_URL/v1beta/models/YOUR_MODEL_ID:generateContent" \
  -H "x-goog-api-key: $SUBLANE_API_KEY" \
  -H 'content-type: application/json' \
  --data '{"contents":[{"role":"user","parts":[{"text":"Hello"}]}]}'

串流呼叫改用 :streamGenerateContent?alt=sse 並添加 curl --no-buffer。返回原生 candidates、parts 和 usageMetadata；SSE 沒有 OpenAI 的 [DONE] 標記。

共享規則

每次請求都會檢查金鑰、成員、資源群組、模型策略、容量及成員限額。新請求可依群組路由及備援策略使用符合條件的訂閱帳號或 API 渠道。既有對話保留原資源綁定；資源停用或移除不會觸發自動切換帳號。

對話使用 Session_id；Claude 未明確指定時也可使用 metadata.user_id。取消請求會釋放成員及帳號槽位。請求本文預設上限為 128 MiB，可透過 SUBLANE_MAX_REQUEST_BODY_MB 調整；回應本文和串流事件分別限制為 8 MiB。請求總逾時預設 30 分鐘（SUBLANE_GATEWAY_REQUEST_TIMEOUT），推理回應標頭等待預設 5 分鐘（SUBLANE_INFERENCE_HEADER_TIMEOUT），同樣適用於原生協定。無效或缺少結束事件不會被當成成功的空回應。

合成測試仍涵蓋 24 種供應商、協定與串流組合，測試不等於所有真實使用者端特性均已認證。目前不實作 token-count、Message Batches、Files、Gemini Live 或 Antigravity 桌面連線協定。CC Switch 快速導入支援 Codex、OpenCode、Claude Code、OpenClaw、Hermes、Gemini CLI 和 Grok Build。「API 金鑰 → 存取指南」也提供 Cline / OpenAI 相容設定與 Chat Completions 請求範例，範例使用 SUBLANE_API_KEY 環境變量，不讀取金鑰原文。

Gemini CLI 0.37.2 另已在隔離的模擬服務下，使用合成金鑰和模型完成文字串流請求及一次唯讀工具呼叫往返。此檢查驗證使用者端請求路徑和回應處理，不代表已驗證真實訂閱推理、所有 CLI 功能或其他使用者端的完整工作流程。