Messages

创建一条 Claude 消息。Messages API 是 BUZZ 的核心对话补全接口:输入消息列表,输出模型生成的消息。与 Anthropic Messages API 即插即用兼容。

鉴权

BUZZ 接受三种鉴权头格式:

anthropic-version 头在 BUZZ 上是可选的,缺失时默认使用 2023-06-01。建议你显式发送以保持代码可移植到 Anthropic 直连环境。

Authorization: Bearer <YOUR_BUZZ_KEY>
anthropic-version: 2023-06-01
content-type: application/json

请求示例

curl -X POST https://buzzai.cc/v1/messages \
  -H "Authorization: Bearer $BUZZ_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-haiku-4-5-20251001",
    "max_tokens": 80,
    "messages": [
      {"role": "user", "content": "reply with exactly: hello world"}
    ]
  }'

from anthropic import Anthropic

client = Anthropic(
    base_url="https://buzzai.cc",
    api_key="",
)

message = client.messages.create(
    model="claude-haiku-4-5-20251001",
    max_tokens=80,
    messages=[
        {"role": "user", "content": "reply with exactly: hello world"}
    ],
)

print(message.content[0].text)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://buzzai.cc",
  apiKey: process.env.BUZZ_API_KEY,
});

const message = await client.messages.create({
  model: "claude-haiku-4-5-20251001",
  max_tokens: 80,
  messages: [
    { role: "user", content: "reply with exactly: hello world" },
  ],
});

console.log(message.content[0].text);

响应

{
  "id": "msg_01ouKJ3o9AnAJb7JtWF25Dk2",
  "type": "message",
  "role": "assistant",
  "model": "claude-haiku-4-5-20251001",
  "content": [
    {"type": "text", "text": "hello world"}
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 6,
    "output_tokens": 2,
    "cache_creation_input_tokens": 0,
    "cache_read_input_tokens": 0,
    "service_tier": "standard"
  }
}

注:BUZZ 可能会附加额外字段(usage.iterations[]、context_management.applied_edits)用于计费透明化。请确保你的 JSON 解析器接受未知字段。

请求体参数

model必填

string — 完成 prompt 使用的模型。从 GET /v1/models 拉取实时列表。

常用值:

• claude-opus-4-7 — 能力最强
• claude-sonnet-4-6 — 性价比平衡
• claude-haiku-4-5-20251001 — 最快、价格最低

带日期的别名同样接受,例如 claude-haiku-4-5-20251001、claude-sonnet-4-5-20250929、claude-opus-4-5-20251101。如果该模型在你所在的 group 不可用,会返回 HTTP 503 model_not_found。

max_tokens必填

integer — 最大输出 token 数。不同模型上限不同,参考 Anthropic 官方模型文档。

messages必填

array — 对话轮次。每条消息有 role("user" 或 "assistant")和 content(字符串或内容块数组)。

"messages": [
  {"role": "user", "content": "你好"},
  {"role": "assistant", "content": "你好!需要什么帮助吗?"},
  {"role": "user", "content": "2 加 2 等于多少?"}
]

content 也可以是结构化数组,支持文本、图片、Tool Use、Tool Result:

{
  "role": "user",
  "content": [
    {"type": "text", "text": "这张图里是什么?"},
    {"type": "image", "source": {...}}
  ]
}

system可选

string | array — System prompt。在对话之外提供上下文和指令。数组形式支持 cache_control 用于 Prompt Cache。

"system": [
  {
    "type": "text",
    "text": "你是一个有帮助的助手。",
    "cache_control": {"type": "ephemeral"}
  }
]

stream可选

boolean — 设为 true 启用 Server-Sent Events 流式响应。详见下面流式部分。

temperature可选

number — 采样温度,0.0 到 1.0。越低越确定。

注意:使用 thinking 模式时(Opus 4.7),temperature / top_p / top_k 会被 Anthropic 忽略。

top_p可选

number — Nucleus 采样。和 temperature 二选一,不要同时用。

top_k可选

integer — 只从概率前 K 的候选中采样。

stop_sequences可选

array of strings — 自定义停止序列,模型生成到这些文本时停止。

tools可选

array — Tool Use / Function Calling 的工具定义。详见Tool Use 概念。

"tools": [
  {
    "name": "get_weather",
    "description": "获取某城市的当前天气",
    "input_schema": {
      "type": "object",
      "properties": {"city": {"type": "string"}},
      "required": ["city"]
    }
  }
]

tool_choice可选

object — 控制模型如何使用工具。

• {"type": "auto"} — 模型自主决定(默认)
• {"type": "any"} — 必须从给定工具中选一个
• {"type": "tool", "name": "..."} — 必须用指定工具
• {"type": "none"} — 禁用工具

thinking可选

object — Extended Thinking(Claude Opus 4.7+)。模型在可见输出之前预留思考 token。

"thinking": {
  "type": "enabled",
  "budget_tokens": 4096
}

metadata可选

object — 自由元数据。Anthropic 主要使用 {"user_id": "..."}。

cache_control(顶层)可选

object — 标记内容用于 Prompt Cache。详见 Prompt Caching 概念。

service_tier高级

string — Anthropic 服务等级。通道级开关:除非你的 channel 启用了相应权限,否则会被静默过滤。

响应

usage 子字段

流式

请求体加 "stream": true 启用 Server-Sent Events 流。流中包含以下事件类型:

实测流样本

event: message_start
data: {"type":"message_start","message":{"id":"msg_...","model":"claude-haiku-4-5-20251001","content":[],...}}

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: message_delta
data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":5}}

event: message_stop
data: {"type":"message_stop"}

Tool Use 示例

提供工具定义,Claude 会在合适的时候自动调用。

{
  "model": "claude-haiku-4-5-20251001",
  "max_tokens": 200,
  "tools": [
    {
      "name": "get_weather",
      "description": "获取某城市的当前天气",
      "input_schema": {
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"]
      }
    }
  ],
  "messages": [
    {"role": "user", "content": "东京天气怎么样?"}
  ]
}

响应(tool_use 轮)

{
  "id": "msg_01gxQPtqeRobjbfSNuCTyijE",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "tool_use",
      "id": "toolu_IbId2k5Cs4dpj5vgdvJJDA",
      "name": "get_weather",
      "input": {"city": "Tokyo"}
    }
  ],
  "stop_reason": "tool_use",
  "usage": {"input_tokens": 35, "output_tokens": 6}
}

完成 round-trip:把 assistant 的 tool_use 消息追加到对话,然后追加一个 user 消息,内容为 tool_result 块:

"messages": [
  {"role": "user", "content": "东京天气怎么样?"},
  {"role": "assistant", "content": [{"type": "tool_use", "id": "toolu_...", ...}]},
  {
    "role": "user",
    "content": [
      {
        "type": "tool_result",
        "tool_use_id": "toolu_...",
        "content": "晴,22°C"
      }
    ]
  }
]

Prompt Cache

给内容标记 cache_control: {"type": "ephemeral"} 启用 Anthropic Prompt Cache。第一次调用写入缓存(计入 cache_creation_input_tokens),后续调用读取缓存,价格只有原始输入的 1/10。

"system": [
  {
    "type": "text",
    "text": "你是数据分析师。下面是公司知识库全集...(20K tokens)",
    "cache_control": {"type": "ephemeral"}
  }
]

BUZZ 实测行为:

BUZZ 字节级透传 cache_control。详见Prompt Caching 概念。

错误码

错误响应包络(Anthropic 透传):

{
  "type": "error",
  "error": {"type": "rate_limit_error", "message": "..."},
  "request_id": "req_..."
}

错误响应包络(BUZZ 网关侧):

{
  "error": {
    "type": "buzz_error",
    "message": "... (request id: 202605260713594...)"
  }
}

详见 Claude API 错误码完全解读。

相关链接

• POST /v1/chat/completions — OpenAI 兼容路径
• Tool Use 概念
• Prompt Caching 概念
• 流式处理指南
• Prompt Cache 生产实战