快速答案：claude 走 anthropic messages 端点是什么？

张梅2026-07-26约 8 分钟主编

直接调用 Anthropic Messages API 与 Claude 模型通信，而不是通过 SDK 或第三方封装。Messages 端点是 Anthropic 官方推荐的 RESTful 接口，支持 Claude 3 和 Claude 3.5 系列模型。你需要手工构造 HTTP 请求（JSON 格式）、处理认证、流式响应和错误码，不依赖现成的 Python/Node.js 库。

这么做能让你完全控制请求行为——定制超时、自定义重试策略、精确管理 Token 消耗，还能在 SDK 不适用的环境（如 Go、Rust 或纯脚本）中工作。下面从最基础的操作开始，讲清每一步怎么做、在哪容易卡住。

开始之前

必备条件

项目	说明
API Key	从 Anthropic Console 获取，需绑定付费计划
端点 URL	`https://api.anthropic.com/v1/messages`
HTTP 客户端	curl（命令行）、Postman、或编程语言的 fetch/requests 库
模型 ID	如 `claude-sonnet-4-20250514` 或 `claude-3-5-haiku-20241022`

版本与边界提醒

API 版本头：anthropic-version: 2023-06-01 是当前稳定版。不传或传旧版本可能导致响应格式变化。
模型可用性：不是所有模型都同时可用。新模型发布后旧模型可能逐步下线，建议查阅 Anthropic 官方文档确认当前最新模型 ID。
Token 限制：每个请求的 max_tokens 受模型限制（如 Claude Sonnet 4 最大 8192 输出 Token）。超出会返回错误。

操作步骤

步骤 1：构造基础请求体

Messages 端点使用统一的请求格式。最简结构如下：

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "用一句话解释什么是 REST API"}
  ]
}

model：必填，指定模型 ID。
max_tokens：必填，生成的最大 Token 数。
messages：必填，对话历史数组，每个元素有 role（user 或 assistant）和 content。

新手容易犯的错误：忘记包含 max_tokens。这个字段不是可选的，不传会收到 400 错误。

步骤 2：添加认证头

每次请求都需要两个 HTTP 头：

x-api-key: sk-ant-xxxxxxxxxx
anthropic-version: 2023-06-01
content-type: application/json

x-api-key：你的 API Key，从 Anthropic Console 复制。
anthropic-version：指定 API 版本。如果不传，日后的 API 更新可能导致代码出现意外行为。

步骤 3：发送请求并处理响应

使用 curl 测试

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: sk-ant-xxxxxxxxxx" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话解释什么是 REST API"}]
  }'

成功响应会返回类似：

{
  "id": "msg_01ABC123xyz",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "REST API 是一种基于 HTTP 协议的接口设计风格，通过 GET、POST、PUT、DELETE 等标准方法操作资源，每个资源由唯一的 URL 标识。"
    }
  ],
  "model": "claude-sonnet-4-20250514",
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 24,
    "output_tokens": 52
  }
}

使用 Python（无 SDK）

import requests
import json

url = "https://api.anthropic.com/v1/messages"
headers = {
    "x-api-key": "sk-ant-xxxxxxxxxx",
    "anthropic-version": "2023-06-01",
    "content-type": "application/json"
}
payload = {
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "用一句话解释什么是 REST API"}]
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

# 提取回复文本
reply_text = data["content"][0]["text"]
print(reply_text)

步骤 4：流式响应（streaming）

对于长时间生成，使用流式响应可以逐块接收结果，提升用户体验。

请求体增加 "stream": true：

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "stream": true,
  "messages": [{"role": "user", "content": "详细列出 Python 中处理 JSON 的三种方法"}]
}

流式响应的每条数据以 data: 开头，格式为 Server-Sent Events (SSE)：

data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "第一"}}
data: {"type": "content_block_delta", "delta": {"type": "text_delta", "text": "种方法"}}
data: {"type": "message_stop"}

你需要在客户端逐行解析，合并 delta.text 来重建完整回复。

注意：不要自己拼接 data: 行的 JSON——一些库会帮你解析；手动解析时小心换行符。

步骤 5：发送多轮对话

将之前的所有消息传给 messages 数组：

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "推荐一本 Python 入门书"},
    {"role": "assistant", "content": "推荐《Python编程：从入门到实践》。"},
    {"role": "user", "content": "它适合完全没有编程经验的人吗？"}
  ]
}

每次请求都包含完整历史。如果历史太长（超过模型上下文窗口），需要手动截断或摘要——API 不会自动为你做摘要。

常见错误排查

错误现象	可能原因	检查方法
401 Unauthorized	API Key 无效或过期	在 Console 验证 Key 是否仍有效
400 Bad Request: missing `max_tokens`	请求体缺少必需字段	检查 JSON 结构
413 Payload Too Large	消息历史超过模型上下文窗口	减少消息轮次或截断早期内容
429 Too Many Requests	速率限制被触发	检查 Usage 页面查看当前配额
500 Internal Server Error	Anthropic 服务端临时问题	等待几秒重试，最多重试 3 次后放弃

返回 JSON 而不是人类可读文本

检查响应 JSON 中的 type 字段。正常响应是 type: "message"，其 content 是包含 text 的数组。如果你得到 type: "error"，则看 error.type（如 overloaded_error）来定位问题。

完整示例：从 JSON 中提取并格式化数据

假设你要批量对多个主体生成简短的摘要，下面的示例展示了完整工作流：

输入数据（5 条记录）：

书名	作者
深入理解计算机系统	Randal E. Bryant
算法导论	Thomas H. Cormen
代码大全	Steve McConnell
重构：改善既有代码的设计	Martin Fowler
人月神话	Frederick Brooks

请求：

{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 1500,
  "messages": [
    {
      "role": "user",
      "content": "为以下每本书写一句话简介，用中文：\n1. 深入理解计算机系统 - Randal E. Bryant\n2. 算法导论 - Thomas H. Cormen\n3. 代码大全 - Steve McConnell"
    }
  ]
}