Messages 概览
本节说明如何通过 Anthropic 兼容的 Messages 接口 /v1/messages 调用 Claude 模型。
如果你使用的是 Claude Code CLI 或 Claude 桌面端，这些客户端内部就是调用 /v1/messages——本节适合需要直接以 HTTP 或 Anthropic SDK 调用的开发者。
接入信息
接口地址：
text
POST https://api.aiqizhilian.tech/v1/messages请求头：
text
Authorization: Bearer <你的 API Key>
Content-Type: application/json
anthropic-version: 2023-06-01请求头要求
Authorization必须是Bearer <Key>，不要使用x-api-key头部（本网关不接受）。anthropic-version是 Anthropic 协议要求的版本头，目前使用2023-06-01。
适用模型
本接口仅支持 Claude 系列模型。完整清单与选型建议见 可用模型。
如需调用非 Claude 模型（GPT、Gemini、Qwen 等），请使用 Chat Completions 接口。
最小可用请求
bash
curl https://api.aiqizhilian.tech/v1/messages \
-H "Authorization: Bearer <你的 API Key>" \
-H "Content-Type: application/json" \
-H "anthropic-version: 2023-06-01" \
-d '{
"model": "claude-sonnet-4-6",
"max_tokens": 256,
"messages": [
{
"role": "user",
"content": "用一句话介绍你自己。"
}
]
}'正常响应：
json
{
"id": "msg_xxx",
"type": "message",
"role": "assistant",
"model": "claude-sonnet-4-6",
"content": [
{
"type": "text",
"text": "..."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 13,
"output_tokens": 24
}
}业务侧通常读取：
- 回复文本：
content[0].text（仅当content[0].type == "text"） - 结束原因：
stop_reason - Token 用量：
usage
与 Chat Completions 的差异
如果你之前用过 OpenAI 的 /v1/chat/completions，下面这些差异值得记一记：
| 维度 | OpenAI Chat Completions | Anthropic Messages |
|---|---|---|
| 系统提示 | messages 数组里 role:"system" 一项 | 顶层 system 字段，不放在 messages 中 |
| 用户/助手交替 | 不强制 | 必须严格交替 user / assistant |
| 必填字段 | model、messages | model、messages、max_tokens |
| 响应主体 | choices[0].message.content (string) | content[] (数组，含 text / tool_use 等块) |
| Token 字段 | prompt_tokens / completion_tokens | input_tokens / output_tokens |
| 结束原因字段 | finish_reason | stop_reason |
顶层字段速览
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
model | string | 是 | 模型 ID |
messages | array | 是 | 对话历史，严格 user / assistant 交替 |
max_tokens | number | 是 | 输出 token 上限，Messages 接口强制必填 |
system | string | 否 | 系统提示（不在 messages 中） |
temperature | number | 否 | 0–1，控制随机性 |
top_p | number | 否 | nucleus sampling |
top_k | number | 否 | Anthropic 专有 sampling 参数 |
stop_sequences | array | 否 | 自定义停止序列 |
stream | boolean | 否 | 是否流式输出，详见 流式输出 |
tools | array | 否 | 工具定义，详见 工具调用 |
tool_choice | object | 否 | 强制工具调用策略 |
多轮对话
messages 数组按时间顺序传入，必须以 role: user 起头并严格交替：
json
{
"model": "claude-sonnet-4-6",
"max_tokens": 512,
"system": "你是个简洁的助手",
"messages": [
{ "role": "user", "content": "你好" },
{ "role": "assistant", "content": "你好，有什么可以帮你？" },
{ "role": "user", "content": "用一句话介绍火星" }
]
}不要把 system 写进 messages
Anthropic 的 system 是顶层字段。如果误写成 {"role":"system",...} 放进 messages，请求会被拒或行为不可预期。