Claude Code 网关 HTTP 请求合同

目标

根据本 skill，实现大模型请求网关的 HTTP 接口层。你是在写服务端 endpoint，不是在写 Claude Code 客户端 SDK 调用。

主入口请先读 claude-code-llm-gateway。本 skill 只负责 HTTP contract：路径、headers、query、body、响应和错误。

必须实现的入口

Endpoint	Method	用途
/v1/messages	POST	主模型请求，支持流式和非流式
/v1/messages?beta=true	POST	同上；beta=true 只作兼容开关
/v1/messages/count_tokens	POST	token 统计
/v1/files	POST	multipart 文件上传
/v1/files	GET	文件列表
/v1/files/{file_id}/content	GET	文件下载
/v1/models	GET	模型列表/能力缓存

详细字段表见 references/request-wire-format.md。

公共处理流程

1. 解析鉴权：接受 Authorization: Bearer <token> 和 x-api-key。网关可自行决定映射关系，但不能因为 Claude Code 使用其中一种就拒绝另一种。
2. 解析公共头：anthropic-version、anthropic-beta、x-app、User-Agent、X-Claude-Code-Session-Id、x-client-request-id。
3. 读取 body 并做宽松校验：必需字段缺失才 400；未知字段默认忽略或透传。
4. 将 model 映射到你的上游模型。
5. 根据 stream 分支：
   • true：交给 SSE 子协议，见 claude-code-api-streaming。
   • false 或缺失：返回完整 Anthropic message JSON。
6. 按 Anthropic 风格返回错误 JSON，并保留可重试状态码语义。

/v1/messages 最小 body 支持

必须识别：

{
  "model": "claude-sonnet-4-5",
  "messages": [],
  "system": [],
  "tools": [],
  "tool_choice": { "type": "auto" },
  "max_tokens": 8000,
  "thinking": { "type": "adaptive" },
  "temperature": 1,
  "metadata": { "user_id": "..." },
  "stream": true,
  "betas": [],
  "context_management": { "edits": [] },
  "output_config": {},
  "speed": "fast"
}

兼容要求：

• thinking.budget_tokens 必须小于 max_tokens；不支持 thinking 时忽略或降级。
• tools 可能包含普通工具、deferred tool、server tool。不要因为未知工具字段直接失败。
• messages 中可能含 tool_result、thinking、redacted_thinking、cache_edits、cache_reference。
• betas 和 anthropic-beta 都可能出现；建议合并后作为能力开关。

/v1/messages/count_tokens

返回：

{ "input_tokens": 1234 }

如果没有精确 tokenizer，可以稳定估算。字段类型必须是 number。

Files API

上传：POST /v1/files，multipart 字段 file 和 purpose=user_data。返回至少 id、filename、size_bytes。

列表：GET /v1/files?after_created_at=...&after_id=...。返回 { data: [], has_more: false }。

下载：GET /v1/files/{file_id}/content。返回二进制 body。

Models API

GET /v1/models 返回 { data: [...], has_more: false }。如果你的平台只有静态模型，返回静态列表即可。

错误与重试

• 400：字段真正非法才返回。
• 401/403：认证或权限失败。
• 408/409/429/5xx/529：Claude Code 会按可重试错误处理；429 可带 retry-after。
• 404：如果只是不支持 stream endpoint，Claude Code 可能尝试非流式 fallback；但 /v1/messages 本身最好不要 404。