Anthropic Messages API¶

使用 Anthropic Messages 请求和响应格式调用 Genesis 模型。本页说明 POST /messages 的文本与图像输入、流式响应和 Token 计数；它不使用 OpenAI Chat Completions 的 messages 或 choices[] 结构。

前提条件¶

已从获取可用模型取得支持 Messages 的模型 ID。
已准备 Genesis 访问令牌；创建和管理凭据请参阅管理 Genesis 访问凭据。
使用图像输入时，已确认模型支持多模态输入。

请求地址¶

POST <GENESIS_BASE_URL>/messages

发送文本消息¶

最小请求包含模型、最大输出 Token 数和一条用户消息：

curl -X POST "$GENESIS_BASE_URL/messages" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "<MESSAGES_MODEL_ID>",
    "max_tokens": 1024,
    "messages": [
      {
        "role": "user",
        "content": "用一句话解释数据血缘。"
      }
    ]
  }'

成功后，从 content[] 中读取模型输出；不要按 Chat Completions 的 choices[0].message.content 解析响应。

请求参数¶

字段	类型	必需	说明
`model`	string	是	支持 Messages 的模型 ID。调用前从当前凭证可用模型中确认。
`max_tokens`	integer	是	本次请求允许的最大输出 Token 数。
`messages`	array	是	按对话顺序传入的消息列表。角色使用 `user` 或 `assistant`。
`messages[].content`	string 或 array	是	文本消息可传字符串；图文消息使用内容块数组。
`system`	string 或 array	否	系统级指令。需要与用户消息分开传递时使用。
`stream`	boolean	否	设为 `true` 后返回 Anthropic Messages SSE 事件。
`thinking`	object	否	扩展思考配置。仅在模型和当前服务配置支持时使用。
`tools`	array	否	工具定义。是否可用由端点、模型和当前服务配置共同决定。
`anthropic-version`	header	否	Anthropic API 版本。建议使用控制台「使用」页当前示例中的值。

首次接入时只发送最小请求。需要扩展思考、工具或其他可选能力时，先在控制台确认模型支持范围，再逐项发送最小请求验证。

成功响应¶

{
  "id": "<message-id>",
  "type": "message",
  "role": "assistant",
  "model": "<MESSAGES_MODEL_ID>",
  "content": [
    {
      "type": "text",
      "text": "数据血缘描述数据从来源到处理和消费环节的关系。"
    }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0
  }
}

字段	类型	返回条件	说明
`id`	string	成功响应返回	本次 Messages 请求的标识。排查问题时提供该值。
`type`	string	成功响应返回	响应对象类型。
`role`	string	成功响应返回	回复角色。
`model`	string	成功响应返回	实际处理本次请求的模型 ID。
`content[]`	array	成功响应返回	内容块列表。文本输出位于 `content[].text`。
`stop_reason`	string 或 null	当前响应包含时	生成结束原因。达到输出限制时，不应将结果视为完整回答。
`usage`	object	当前响应包含时	本次请求的 Token 用量。只读取实际返回的字段。

content[] 可能包含非文本内容块。应用应先检查内容块的 type，再读取相应字段。

发送图文消息¶

图文消息将 content 写为内容块数组。使用支持多模态输入的模型，并将图片替换为可访问的地址：

{
  "model": "<MULTIMODAL_MESSAGES_MODEL_ID>",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "描述这张图片的主要内容。"
        },
        {
          "type": "image",
          "source": {
            "type": "url",
            "url": "https://example.com/photo.jpg"
          }
        }
      ]
    }
  ]
}

调用前先在模型目录或调试页确认所选模型的能力。模型显示为可用不等于其在 Messages 接口中一定支持图像输入。

处理流式响应¶

将 stream 设为 true 后，响应以 SSE 事件返回。客户端应逐帧读取 data: 内容，按事件类型处理开始、内容增量和结束事件。常见事件包括 message_start、content_block_delta 和 message_stop：

event: message_start
data: {"type":"message_start","message":{"id":"<message-id>","type":"message","role":"assistant","content":[]}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"数据"}}

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

网络分片不一定与 SSE 事件边界对齐。收到空行前应保留未完成的事件帧；连接中断后重试会形成新的请求，不能直接把两次流的文本拼接为同一回复。

估算输入 Token¶

需要在调用前估算输入 Token 时，向 POST /messages/count_tokens 提交与 Messages 请求相同的输入结构。该请求不生成模型回复：

curl -X POST "$GENESIS_BASE_URL/messages/count_tokens" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "<MESSAGES_MODEL_ID>",
    "messages": [
      {
        "role": "user",
        "content": "用一句话解释数据血缘。"
      }
    ]
  }'

响应中的 input_tokens 表示本次输入的估算 Token 数。该值用于请求前估算，不替代实际响应返回的用量字段。

工具能力限制¶

tools 不是所有 Messages 模型的共同能力。即使模型可用于 Chat Completions，也不能据此判断它支持 Messages 工具调用。先确认端点和模型能力，再发送最小工具请求；如出现服务端错误，请保留脱敏后的请求 ID、端点、模型 ID 和状态码进行排查。

常见问题¶

现象	先检查	下一步
认证失败	请求地址、令牌和 `Authorization` Header	确认请求使用 `Authorization: Bearer <ACCESS_TOKEN>`，并在管理 Genesis 访问凭据中检查凭据状态和权限。
模型不可用	`model` 值和当前可用模型列表	选择当前凭证可访问且支持 Messages 的模型。
响应中没有 `choices[]`	是否按 OpenAI Chat Completions 解析响应	从 `content[]` 中读取内容块。
流式文本不完整	是否按完整 JSON 一次读取，或在事件结束前丢弃缓存	按 SSE 帧处理 `data:` 内容，并在结束事件后完成消息。
图像或工具请求失败	模型、端点和当前服务配置是否支持该能力	先恢复文本最小请求，再单独验证所需能力。

下一步¶

最后更新于 2026 年 8 月 14 日