原生客户端协议

版本与范围

本页原生接口在 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 功能或其他客户端的完整工作流。