原生客户端协议

版本与范围

本页原生接口在 v0.1.0-rc.1 之后引入，该版本不包含它们；在包含此功能的新版本发布前使用源码构建。

客户端协议与订阅供应商独立。请求仍然只能选择个人密钥组内、报告支持目标模型的账号，由 CLIProxyAPI 执行器处理供应商转换。完整真实账号与桌面客户端兼容性仍需单独验收。

接口与认证

协议	接口	凭据
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] 标记。

共享规则

每次请求检查密钥、成员、组、模型策略、账号容量和成员限额。新请求中 Responses/Chat 优先可用 Codex，Messages 优先 Claude，Gemini 优先 Antigravity，其他支持目标模型的供应商可作备选。已有绑定优先且不会自动迁移。

会话使用 Session_id；Claude 未显式指定时还可用 metadata.user_id。取消请求会释放成员与账号槽位。请求与事件大小上限 8 MiB，操作期限 10 分钟。无效或缺失结束事件不被当成成功空响应。

合成测试覆盖 24 种供应商、协议与流式组合，不等于所有真实客户端特性均已认证。当前不实现 token-count、Message Batches、Files、Gemini Live 或 Antigravity 桌面连接协议。CC Switch 快速导入仍只支持 Codex 配置。