Anthropic Messages

官方文档：Messages · Streaming messages · Count tokens

POST /v1/messages 是 Anthropic 原生报文入口：鉴权头、消息结构、事件流名都保持 Claude 的形状，Claude SDK、Claude Code 等客户端只需把 Base URL 指向 ModelGo，不需要任何改写。

项目	值
端点	`POST /v1/messages`
Base URL（Anthropic SDK）	`https://api.modelgo.ai`（不带 `/v1`）
鉴权	`x-api-key: $MODELGO_API_KEY`
版本头	`anthropic-version`，可省略，缺省按 `2023-06-01` 处理
协议声明	`anthropic_messages`

请求示例

bash

curl https://api.modelgo.ai/v1/messages \
  -H "x-api-key: $MODELGO_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<model>",
    "max_tokens": 1024,
    "system": "你是一个简洁的助手。",
    "messages": [{"role": "user", "content": "用一句话介绍 ModelGo。"}]
  }'

python

import os
import anthropic

client = anthropic.Anthropic(
    api_key=os.environ["MODELGO_API_KEY"],
    base_url="https://api.modelgo.ai",
)

msg = client.messages.create(
    model="<model>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "用一句话介绍 ModelGo。"}],
)
print(msg.content[0].text)

常用字段

字段	必填	说明
`model`	是	平台逻辑模型名
`max_tokens`	是	输出上限
`messages`	是	消息数组，`role` 取 `user` / `assistant`，`content` 是字符串或内容块数组
`system`	否	系统提示词，与 `messages` 分离
`temperature` / `top_p`	否	采样参数
`stop_sequences`	否	停止序列
`tools` / `tool_choice`	否	工具定义与选择；`tool_result` 以 `user` 消息内的内容块回传
`stream`	否	为 `true` 时返回原生事件流

响应中的 model 可能是上游内部名（例如 pa/venus-cathedral-5），与请求里的逻辑名不同；计费与策略以请求的 model 和控制台配置为准。

流式事件

流式返回保持 Anthropic 原生 event: 帧，网关不会把它改写成 OpenAI 的 data:-only SSE。事件顺序为 message_start → content_block_start → 若干 content_block_delta → content_block_stop → message_delta → message_stop，没有 data: [DONE] 哨兵，以 message_stop 结束。

message_start 中的 usage 带输入与缓存计数，message_delta 中的 usage 带输出计数，结算按两处合计的实际用量进行。

令牌计数

POST /v1/messages/count_tokens 由网关本地估算，不透传到上游：它按 system、messages、tools 内容计算 input_tokens，供 Claude Code 这类客户端判断何时压缩上下文。该接口同样受模型目录与策略约束，但不计费。

bash

curl https://api.modelgo.ai/v1/messages/count_tokens \
  -H "x-api-key: $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model>","messages":[{"role":"user","content":"hello"}]}'

关键约定

逻辑模型未声明 anthropic_messages 协议时，本入口返回 HTTP 400、error_class=model_protocol_not_offered（app_error_id=4005）。
错误信封是 Anthropic 形状：{"type":"error","error":{"type":"authentication_error","message":"...","code":401,"metadata":{...}}}，并带顶层 trace_id。
GET /v1/models 同时携带 x-api-key 与 anthropic-version 时，返回 Anthropic 形状的模型清单（data[].display_name）。
请求体上限 10 MiB。
请求已发往上游但中途失败时按预扣金额结算，规则见错误码与限流。

Claude Code 等客户端的具体配置见 Claude Code，三条文本入口的对照见文本生成总览。