---
title: Messages 原生对话接口
description: Claude Messages 的请求头、system 与 messages 区别、内容块和结束原因。
---

<aside className="docs-publication" data-pagefind-ignore>文档由 <a href="https://1zheai.com/editorial/#publisher">1折AI</a> 维护。<a href="https://1zheai.com/editorial/">来源、商业关系与纠错说明</a>。发现错误，请向 <a href="mailto:support@1zheai.com">support@1zheai.com</a> 提供页面地址与可核查依据，不要发送密钥或账号资料。</aside>

Claude Code、Anthropic SDK 和希望保留 Claude 原生内容块的应用使用 `POST https://1zheai.com/v1/messages`。SDK Base URL 填 `https://1zheai.com`。

## 最小请求

先设置本站密钥环境变量 `ONEZHE_API_KEY`，再执行：

```bash
curl --fail-with-body --connect-timeout 10 --max-time 120 \
  https://1zheai.com/v1/messages \
  -H "x-api-key: $ONEZHE_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-5-5",
    "max_tokens": 256,
    "system": "请用简短的中文回答。",
    "messages": [{"role": "user", "content": "什么是域名解析？"}]
  }'
```

## 请求结构

| 字段 | 类型 | 使用方式 |
| --- | --- | --- |
| `model` | string | 必填，选择密钥可用的 Claude 模型 |
| `max_tokens` | integer | 必填，输出上限；结合所选模型限制设置 |
| `messages` | array | 必填，按时间顺序发送 `user` 与 `assistant` 消息 |
| `system` | string 或内容块数组 | 可选，系统指令放在顶层，不使用 `role: system` 消息 |
| `stream` | boolean | 可选，流式读取内容块增量 |
| `tools` | array | 可选，声明工具名称、用途及输入 Schema |

`thinking`、缓存控制和 beta 参数依具体模型与上游支持而定。先验证普通文本，再按需添加；不要把所有模型都当成同一组参数。

## 读取内容块

返回的 `content` 是数组，可能同时包含文本、工具请求或其他内容块。不要无条件读取 `content[0].text`。例如使用 Anthropic Python SDK：

```python
for block in message.content:
    if block.type == "text":
        print(block.text)
```

这里的 `message` 来自 [Anthropic SDK 教程](/docs/quickstart-anthropic-sdk/)中的 `client.messages.create(...)`。

| `stop_reason` | 应用如何处理 |
| --- | --- |
| `end_turn` | 本轮回答结束 |
| `max_tokens` | 输出被上限截断，不能当作完整回答 |
| `tool_use` | 检查工具请求，执行允许的工具并回传结果 |
| 其他值 | 保留响应并按所选模型的协议处理，不假设一定是文本完成 |

工具调用循环中，先把完整的 assistant 内容块加入历史，再以 user 内容中的 `tool_result` 回传，`tool_use_id` 必须对应原请求。不要把工具请求直接转换成一段普通文字。

## 多轮与流式

每次发送需要保留的历史，接口本身不替应用存储对话。流式以 `message_stop` 表示消息结束；收到部分文本并不代表请求已经完成。详见[流式输出](/docs/streaming/)。

协议细节参考 [Anthropic Messages 使用说明](https://platform.claude.com/docs/en/build-with-claude/working-with-messages)。本站扩展参数是否可用，以模型目录和实际响应为准。