跳到主要内容

Messages API

API 参考/Messages/创建消息

创建消息

POST/v1/messages

使用 Anthropic 原生 Messages API 格式调用 Claude 系列模型，适合已有 Anthropic SDK 或原生协议集成的项目。

认证​

Anthropic 原生协议使用 x-api-key 请求头，并要求传入 anthropic-version。

x-api-keystring必填

API Key。Anthropic 原生协议使用 x-api-key，而不是 Authorization Bearer。

默认值：-
anthropic-versionstring必填

Anthropic API 版本。

默认值：2023-06-01
Content-Typestring必填

请求体格式。

默认值：application/json
Request-Idstring可选

客户侧生成的唯一请求标识，用于追踪和排查。

默认值：-

请求​

请求体必须包含 model、messages 和 max_tokens。

modelstring必填

Claude 模型 ID，例如 claude-sonnet-4-6。

默认值：-
messagesarray必填

对话消息列表。

默认值：-
messages[].rolestring必填

消息角色：user 或 assistant。

默认值：-
messages[].contentstring | array必填

文本字符串或多模态内容块数组。

默认值：-
max_tokensinteger必填

本次响应最多生成的 Token 数。

默认值：-
systemstring可选

系统提示词。

默认值：-
streamboolean可选

是否启用 SSE 流式输出。

默认值：false
temperaturenumber可选

采样温度。

默认值：1
top_pnumber可选

核采样参数。

默认值：-
top_kinteger可选

仅采样概率最高的前 K 个 Token。

默认值：-
stop_sequencesarray可选

停止序列列表。

默认值：-
toolsarray可选

Anthropic 工具定义列表。

默认值：-
tool_choiceobject可选

工具调用控制。

默认值：-
metadataobject可选

请求元数据，例如 user_id。

默认值：-

响应​

响应返回 Anthropic 原生 message 对象。

idstring必填

消息唯一标识。

默认值：-
typestring必填

对象类型。

默认值：message
rolestring必填

响应角色。

默认值：assistant
modelstring必填

实际执行请求的 Claude 模型。

默认值：-
contentarray必填

回复内容块列表。

默认值：-
stop_reasonstring可选

停止原因，例如 end_turn、max_tokens、stop_sequence 或 tool_use。

默认值：-
stop_sequencestring | null可选

命中的停止序列。

默认值：-
usageobject可选

Token 用量统计。

默认值：-

多模态输入​

messages[].content 支持数组格式，可混合文本和图片。

{
  "role": "user",
  "content": [
    {"type": "text", "text": "描述这张图片"},
    {
      "type": "image",
      "source": {
        "type": "base64",
        "media_type": "image/png",
        "data": "BASE64_ENCODED_IMAGE_DATA"
      }
    }
  ]
}

流式响应​

设置 stream: true 后，响应以 Anthropic SSE 事件返回，例如 message_start、content_block_delta、message_delta 和 message_stop。

错误​

状态码说明
400请求体字段错误或消息格式不符合 Anthropic 原生协议
401API Key 缺失或无效
403当前账户无权调用该模型
429请求超过速率限制
500 / 503平台或上游模型服务异常

相关指南​