Anthropic /v1/messages

cc-router 在本地启动一套 HTTP 代理，对外同时暴露 Anthropic Messages API（主入口）与 OpenAI Responses API（v2.3+ 兼容入口）两套协议。本页是 Anthropic /v1/messages 的完整参考——它是 Claude Code 及任何讲 Anthropic Messages 协议的客户端的首选入口。

适用版本：cc-router v3.0.0 及以上。

监听与端口

配置	默认值	说明
监听地址	127.0.0.1	设置中开启「监听所有网卡」会切换到 0.0.0.0（UI 会红色警告）
HTTP 端口	23456	端口被占用时自动 +1 探测，最多 100 次
HTTPS 端口	由设置中的 https_port 控制	通过代理模式决定是否启用
端口/地址变更	需重启 app	代理未做热重载

客户端最少配置

export ANTHROPIC_BASE_URL=http://127.0.0.1:23456
# 默认未开启鉴权时此行可省略
export ANTHROPIC_API_KEY=<cc-router 设置页提供的 token>

# 把 Claude Code 的三个模型槽指向 cc-router 虚拟模型
export ANTHROPIC_DEFAULT_OPUS_MODEL=model-opus
export ANTHROPIC_DEFAULT_SONNET_MODEL=model-sonnet
export ANTHROPIC_DEFAULT_HAIKU_MODEL=model-haiku

---

鉴权

• 默认关闭：任何请求直通，无需 token。
• 启用后，cc-router 从以下两处读取 token（任一存在即可）：
  • x-api-key: <token>（对应 Claude Code 的 ANTHROPIC_API_KEY，优先）
  • Authorization: Bearer <token>（对应 Claude Code 的 ANTHROPIC_AUTH_TOKEN）
• 提取到的 token 必须完全等于设置页配置的 auth_token，否则返回 401。
• 白名单：/v1/models、/health、所有 OPTIONS 预检请求永远直通，即使开启鉴权也不拦。
  • 目的：让客户端启动期的 list-models 与浏览器调试不被挡住；真正消耗 token 配额的接口（/v1/messages 与 /v1/responses）则必须鉴权。

cc-router 这里收的 token 是给 cc-router 自己用的，与你上游各家厂商的真实 API Key 无关——真实 Key 由 cc-router 按虚拟模型调度规则替换到上游请求里。

CORS 默认开启：Access-Control-Allow-Origin: *，方法允许 GET / POST / OPTIONS，所有头放行，预检直接 204。401 响应也带 CORS 头，浏览器 fetch 能拿到响应体。

---

请求

POST /v1/messages
Content-Type: application/json

Header	必需	说明
Content-Type: application/json	是	请求体必须是 JSON
x-api-key 或 Authorization: Bearer ...	视鉴权设置	开启鉴权时二选一
anthropic-version / anthropic-beta / …	否	cc-router 不消费，原样透传给上游

请求体沿用 Anthropic Messages API 标准格式。cc-router 只读取两个字段做调度，其余字段（messages / system / tools / temperature / max_tokens / thinking / …）原样透传给上游。

字段	类型	必需	行为
model	string	是	解析为虚拟模型，详见下文映射表。缺失返回 400
stream	boolean	否（默认 false）	true 走 SSE；false 走非流式

cc-router 会改写请求体的 model 字段：

• 命中 model-opus / model-sonnet / model-haiku → 改写为该虚拟模型绑定的真实模型名（如 glm-4.6、qwen3-max）
• 命中 fallback → 不改写，原样透传给上游

非流式请求示例

curl http://127.0.0.1:23456/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "model-sonnet",
    "max_tokens": 256,
    "messages": [
      { "role": "user", "content": "用一句话说明 cc-router 是什么" }
    ]
  }' | jq

---

响应（非流式）

• 200 OK，Content-Type: application/json
• 响应体是 Anthropic 标准 message JSON
• cc-router 把 message.model 反向改写为虚拟模型名（fallback 模式不改），方便客户端按虚拟模型聚合缓存与统计
• usage.*（含 cache_creation_input_tokens / cache_read_input_tokens）透传，cc-router 同时抽取一份用于内部统计

{
  "id": "msg_xxx",
  "type": "message",
  "role": "assistant",
  "model": "model-sonnet",
  "content": [
    { "type": "text", "text": "..." }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 42, "output_tokens": 128 }
}

---

响应（流式 SSE）

• 200 OK，Content-Type: text/event-stream
• 上游 SSE 帧几乎全部原字节透传，仅以下两类事件特殊处理：

事件	cc-router 行为
message_start	解析 JSON，改写 message.model 为虚拟模型名（fallback 不改），抽取 usage.* 记账，重新序列化后写出
message_delta	不改写，仅旁路抽取 usage.output_tokens 等做记账，原字节透传
其余所有事件（content_block_* / message_stop / ping 等）	原字节透传

流式请求示例

curl -N http://127.0.0.1:23456/v1/messages \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "model-sonnet",
    "max_tokens": 256,
    "stream": true,
    "messages": [
      { "role": "user", "content": "ping" }
    ]
  }'

-N 关闭 curl 缓冲，实时打印每一帧 SSE。

首事件 lookahead：上游返 200 但首事件其实是 event: error（典型场景：智谱 1302/1308 配额耗尽伪装成 200）时，cc-router 不会把这帧透传给客户端，而是触发自动重试切下一家订阅。客户端只感知到一次正常的成功或一次最终失败。

传输中断：上游连接中途断开时，cc-router 会在已发送的事件后追加一个 event: error 帧 + data: [DONE]，让客户端能感知到中断而非永久挂起。

---

虚拟模型映射

cc-router 把请求里的 model 字段映射到一个虚拟模型，然后按虚拟模型绑定的订阅列表 + 调度模式（顺序 / 轮询）依次尝试上游。

客户端发送的 model	命中虚拟模型
model-opus、claude-opus-4-7、gpt-5.5、anthropic/model-opus、anthropic/claude-opus-4-7、openai/gpt-5.5	model-opus
model-sonnet、claude-sonnet-4-6、gpt-5.4、anthropic/model-sonnet、anthropic/claude-sonnet-4-6、openai/gpt-5.4	model-sonnet
model-haiku、claude-haiku-4-5、gpt-5.4-mini、anthropic/model-haiku、anthropic/claude-haiku-4-5、openai/gpt-5.4-mini	model-haiku
model-fallback、anthropic/model-fallback	Fallback（显式）
其他任意值（自定义模型名等）	Fallback（隐式，原样透传 model）

• anthropic/ 前缀用于兼容 LiteLLM 风格的 vendor-prefixed 命名。
• openai/ 前缀同理，主要给 OpenAI /v1/responses 入口 的客户端使用。
• gpt-5.5 / gpt-5.4 / gpt-5.4-mini 是 cc-router 故意挑选的 OpenAI 风格别名，复用 Opus / Sonnet / Haiku 三槽位，不新增虚拟模型。

---

错误响应

/v1/messages 入口所有错误都用 Anthropic 风格：

{
  "type": "error",
  "error": {
    "type": "<kind>",
    "message": "<人类可读消息>"
  }
}

cc-router 自身产生的错误：

HTTP Status	kind	触发场景
400	invalid_request_error	JSON 解析失败 / 缺少 model 字段
401	authentication_error	开启鉴权时 token 不匹配
500	api_error	pipeline 内部错误（所有订阅都失败等）
503	overloaded_error	fallback 虚拟模型的订阅列表为空
4xx / 5xx	视上游而定	所有订阅都失败时，cc-router 透传最后一家上游的 status + 错误体

SSE 流内的 error 帧：

• 流首事件就是 event: error → cc-router 拦截并自动重试切到下一家订阅，客户端无感知
• 流中途出现的 error 帧 → 按上游错误透传给客户端，kind 固定为 upstream_error

---

未实现的 Anthropic 接口

下列官方接口在 cc-router 中未实现，属于设计选择：

• POST /v1/messages/count_tokens
• POST /v1/messages/batches 与所有 batches 相关接口
• POST /v1/files（Files API）
• Workbench / Admin API

cc-router 的设计场景是 Claude Code 风格的实时对话代理，CC 只依赖 POST /v1/messages + GET /v1/models，所以未实现这些接口。如果你需要预估 token 数，可以在客户端用 tiktoken 本地估算，或直接调一次 /v1/messages 看响应中的 usage.input_tokens。

如果你的客户端讲的是 OpenAI Responses 协议（如 Codex CLI），请改用 OpenAI /v1/responses 入口，cc-router 会自动把请求翻译成 Anthropic Messages 走同一条调度 pipeline。