# Anthropic Messages API

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

## 前提条件

- 已从[获取可用模型](../getting-started/available-models.md)取得支持 Messages 的模型 ID。
- 已准备 Genesis 访问令牌；创建和管理凭据请参阅[管理 Genesis 访问凭据](../../../../guides/genesis/api-keys.md)。
- 使用图像输入时，已确认模型支持多模态输入。

## 请求地址

```text
POST <GENESIS_BASE_URL>/messages
```

## 发送文本消息

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

```bash
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 版本。建议使用控制台「使用」页当前示例中的值。 |

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

## 成功响应

```json
{
  "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` 写为内容块数组。使用支持多模态输入的模型，并将图片替换为可访问的地址：

```json
{
  "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"
          }
        }
      ]
    }
  ]
}
```

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

## 处理流式响应

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

```text
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 请求相同的输入结构。该请求不生成模型回复：

```bash
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 访问凭据](../../../../guides/genesis/api-keys.md)中检查凭据状态和权限。 |
| 模型不可用 | `model` 值和当前可用模型列表 | 选择当前凭证可访问且支持 Messages 的模型。 |
| 响应中没有 `choices[]` | 是否按 OpenAI Chat Completions 解析响应 | 从 `content[]` 中读取内容块。 |
| 流式文本不完整 | 是否按完整 JSON 一次读取，或在事件结束前丢弃缓存 | 按 SSE 帧处理 `data:` 内容，并在结束事件后完成消息。 |
| 图像或工具请求失败 | 模型、端点和当前服务配置是否支持该能力 | 先恢复文本最小请求，再单独验证所需能力。 |

## 下一步

- [使用 Anthropic Python SDK](../../../sdk/genesis-compatible/anthropic-sdk.md)
- [查看当前凭证可用的模型](../getting-started/available-models.md)
- [在控制台调试 Messages 请求](../../../../guides/genesis/debug.md)