# 创建 Anthropic Message

使用 Anthropic Messages 请求形态调用 Genesis 模型，并从 `content[]` 读取响应内容。该接口不使用 Chat Completions 的 `choices[]` 响应结构。

```text
POST https://token.moi.matrixorigin.cn/v1/messages
```

## 调用前准备

请求地址为 `https://token.moi.matrixorigin.cn/v1/messages`。准备支持 Messages 的模型 ID，以及个人访问令牌或服务账号 API Key。

下方示例使用：

- `$GENESIS_ACCESS_TOKEN`：实际个人访问令牌或服务账号 API Key，通过 `Authorization: Bearer` Header 传递。
- `$MODEL_ID`：要调用的模型 ID，填入请求体的 `model` 字段。

不要将任意 Chat 模型当作 Messages 模型使用。使用支持 Messages 的模型 ID，并按该模型实际支持的请求格式调用。

## 请求头

| 请求头 | 是否必填 | 说明 |
| --- | --- | --- |
| `Authorization` | 是 | 使用 `Bearer <GENESIS_ACCESS_TOKEN>` 传递个人访问令牌或服务账号 API Key。 |
| `Content-Type` | 是 | 请求体使用 JSON。 |
| `anthropic-version` | 否 | 指定 Anthropic API 版本。 |

## 请求体

请求体包含以下字段。

字段路径中的 `[]` 表示数组中的每一项。例如，`messages[].role` 表示 `messages` 数组中每一项的 `role` 字段。

| 字段 | 类型 | 是否必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 支持 Anthropic Messages 的模型 ID。 |
| `max_tokens` | integer | 是 | 本次请求允许的最大输出 Token 数。 |
| `messages` | array | 是 | 按对话顺序传入的消息列表。 |
| `messages[].role` | string | 是 | 消息角色，使用 `user` 或 `assistant`。 |
| `messages[].content` | string 或 array | 是 | 文本消息可使用字符串；图文消息使用内容块数组。 |
| `system` | string 或 array | 否 | 系统级指令。 |
| `stream` | boolean | 否 | 设为 `true` 时返回 Anthropic Messages SSE 事件；非流式调用可省略或设为 `false`。 |
| `tools` | array | 否 | 工具定义，仅在当前模型和服务配置支持时使用。 |

## 请求示例

以下示例可使用个人访问令牌或服务账号 API Key：

```bash
curl -X POST "https://token.moi.matrixorigin.cn/v1/messages" \
  -H "Authorization: Bearer $GENESIS_ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'anthropic-version: 2023-06-01' \
  -d '{
    "model": "'"$MODEL_ID"'",
    "max_tokens": 256,
    "stream": false,
    "messages": [
      {
        "role": "user",
        "content": "用一句话解释数据血缘。"
      }
    ]
  }'
```

## 成功响应

```json
{
  "id": "<MESSAGE_ID>",
  "type": "message",
  "role": "assistant",
  "model": "<MODEL_ID>",
  "content": [
    {
      "type": "text",
      "text": "数据血缘描述数据从来源、处理到消费环节的关系。"
    }
  ],
  "stop_reason": "end_turn"
}
```

响应中用于读取生成内容的字段如下。

字段路径中的 `[]` 表示数组中的每一项。例如，`content[].text` 表示 `content` 数组中每一项的 `text` 字段。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `id` | string | 本次 Messages 请求的标识。 |
| `type` | string | 响应对象类型。 |
| `model` | string | 实际处理请求的模型 ID。 |
| `content` | array | 内容块列表。 |
| `content[].type` | string | 内容块类型。响应可以同时包含 `thinking` 和 `text` 等类型。 |
| `content[].text` | string | 内容块类型为 `text` 时的生成文本。 |
| `content[].thinking` | string | 内容块类型为 `thinking` 时的推理内容；仅在响应实际包含时读取。 |
| `stop_reason` | string 或 null | 当前生成结束原因。 |

不要假定 `content[]` 的第一项就是文本。遍历内容块并只拼接 `type` 为 `text` 的 `text` 字段。

## 错误响应

接口不使用 `code`、`msg`、`data` 包络。收到非成功 HTTP 状态时，不要从 `content[]` 读取结果。错误对象由兼容的模型服务返回；除 `error.message` 外的字段可能省略。

### 错误对象字段

```json
{
  "error": {
    "message": "<可读错误信息>",
    "type": "<错误类型，可能省略>",
    "code": "<错误代码，可能省略>"
  }
}
```

错误正文中可能出现的字段如下。

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `error.message` | string | 可读错误信息。 |
| `error.type` | string，可选 | 上游错误类别。 |
| `error.code` | string 或 null，可选 | 上游错误代码。 |

### 常见 HTTP 错误

下表说明收到不同 HTTP 状态时应执行的操作。

```{list-table}
:header-rows: 1
:widths: 12 22 32 34

* - HTTP 状态码
  - 错误代码
  - 常见原因
  - 建议操作
* - `400`
  - —
  - 缺少 `max_tokens`，或消息和可选参数不符合 Messages 形态。
  - 先发送模型、`max_tokens` 和一条文本用户消息。
* - `401`
  - —
  - 凭据无效，或没有模型权限。
  - 检查 Bearer 凭据和目标模型范围。
* - `403`
  - —
  - 凭据无效，或没有模型权限。
  - 检查 Bearer 凭据和目标模型范围。
* - `429`
  - —
  - 当前服务受到限制或暂时不可用。
  - 降低请求频率，或稍后再次提交请求。
* - `5xx`
  - —
  - 当前服务受到限制或暂时不可用。
  - 降低请求频率，或稍后再次提交请求。
```

## 后续操作

- [查询模型列表](models.md)