Anthropic Messages API 是向 Claude 发送提示词的主要 HTTP 接口。核心端点为 POST /v1/messages：你提供模型、一个类型化消息内容块列表以及一个 token 限制，然后会收到一条包含一个或多个输出块的助手消息。
本指南将 Anthropic API 文档转化为一份实现清单。它涵盖了请求合约、多轮状态、流式传输、视觉、文件 API、工具使用，以及智能体后端需要同时支持 Anthropic 原生和 OpenAI 兼容模型提供商时的选择。
Messages API 端点与必需请求头
Anthropic 的原生 Messages API 使用以下端点：
POST https://api.anthropic.com/v1/messages
直接的 HTTP 请求通常包含以下请求头：
| 请求头 | 用途 |
|---|---|
x-api-key |
认证 Anthropic 账户 |
anthropic-version |
选择文档化的 API 版本合约 |
content-type: application/json |
声明 JSON 请求体 |
API 版本头不是模型版本。它控制 HTTP API 行为，而 model 字段选择用于推理的 Claude 模型。将这两个值放在配置中，而不是分散在应用程序代码中。
请求与响应结构
一个基本请求包含三个字段：
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 1024,
"messages": [
{
"role": "user",
"content": "用两段话解释幂等键。"
}
]
}
响应是一条助手消息，而不是一个简单字符串。其 content 属性是一个类型化块数组，因此生产代码应在读取每个块的字段之前检查其 type。
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "text",
"text": "幂等键是..."
}
],
"stop_reason": "end_turn",
"usage": {
"input_tokens": 18,
"output_tokens": 126
}
}
这种基于块的设计在你添加图像或工具时变得重要。一次助手轮次可以包含文本和工具请求，而一次用户轮次可以包含文本以及图像或文档块。
一个最小的 curl 请求
将凭据存储在环境变量中，并使用当前可用于你 Anthropic 账户的模型 ID：
export ANTHROPIC_API_KEY="your-api-key"
export ANTHROPIC_MODEL="your-claude-model-id"
curl https://api.anthropic.com/v1/messages \
--header "x-api-key: $ANTHROPIC_API_KEY" \
--header "anthropic-version: 2023-06-01" \
--header "content-type: application/json" \
--data '{
"model": "'"$ANTHROPIC_MODEL"'",
"max_tokens": 512,
"messages": [
{
"role": "user",
"content": "列出三种减少 API 延迟的实用方法。"
}
]
}'
不要硬编码从旧教程中复制的模型名称。模型可用性和别名可能会变化，因此部署配置应使用在提供商当前模型文档或控制台中验证过的模型 ID。
使用 Anthropic SDK 的 Python 用法
官方 Python SDK 负责处理认证头，并将响应转换为类型化对象：
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
message = client.messages.create(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=512,
messages=[
{
"role": "user",
"content": "编写一个 Python 函数，用于验证 UUID 字符串。",
}
],
)
for block in message.content:
if block.type == "text":
print(block.text)
遍历内容块比假设 message.content[0] 总是文本更安全。智能体应用程序可能会收到工具使用块，多模态功能也可能向对话中添加其他块类型。
多轮对话与系统提示
Messages API 是无状态的。你的应用程序每次请求时都会重新发送相关的对话历史：
{
"model": "YOUR_CLAUDE_MODEL_ID",
"max_tokens": 512,
"system": "你是一个简洁的 API 文档助手。",
"messages": [
{"role": "user", "content": "HTTP 429 是什么意思？"},
{"role": "assistant", "content": "表示速率限制。"},
{"role": "user", "content": "我的客户端应该如何重试？"}
]
}
Anthropic 将系统指令放在顶层的 system 字段中，而不是放在带有 role: "system" 的消息中。这是将请求从 OpenAI 兼容模式转换时需要处理的重要差异之一。
对于长时间运行的会话，不要重新发送无限的转录。保留最近的轮次，保存仍然影响任务的决策和工具结果，并在提示词接近所选模型上下文限制之前，总结较旧的上下文。
流式响应
当界面需要逐步显示输出时，设置 stream: true：
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with client.messages.stream(
model=os.environ["ANTHROPIC_MODEL"],
max_tokens=1024,
messages=[
{"role": "user", "content": "解释数据库连接池。"}
],
) as stream:
for text in stream.text_stream:
print(text, end="", flush=True)
流式传输改善了感知延迟，但增加了状态管理的工作量。你的应用程序必须处理提前关闭的连接、部分文本、事件顺序以及最终的用量元数据。对于使用工具的智能体，在解析或执行之前，请缓冲完整的工具输入块。
Claude 视觉 API 请求
Claude 视觉 API 使用相同的 Messages 端点。在相关文本问题之前添加一个图像内容块。图像可以作为支持的 base64 数据提供，或者通过当前视觉文档中描述的允许源类型提供。
import base64
import os
from anthropic import Anthropic
client = Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
with open("architecture.png", "rb") as image_file:
image_data = base64.b64encode(image_file.read()).decode("utf-8")
message = client.messages.create(
model=os.environ["ANTHROPIC_VISION_MODEL"],
max_tokens=700,
messages=[
{
"role": "user",
"content": [
{
"type": "image",
"source": {
"type": "base64",
"media_type": "image/png",
"data": image_data,
},
},
{
"type": "text",
"text": "在这个架构图中找出两个可靠性风险。",
},
],
}
],
)
在发送前调整过大的图像。大图像会增加传输时间和 token 使用量，而不一定会改善答案。同时验证 MIME 类型；将 JPEG 数据声明为 PNG 是导致请求被拒绝的常见原因。
Anthropic 文件 API 用法
Anthropic 文件 API 在以下场景中很有用：文件只需上传一次，然后被后续的 Messages API 调用引用，而不是每次都编码和传输。确切的可用性、支持的文件类型和请求字段可能因功能状态而异，因此在生产环境中依赖它之前，请检查当前的文件 API 文档。
典型的集成分两个阶段：
- 上传文件，并将返回的文件标识符与应用程序的文档记录一起持久化。
- 在创建消息时，在支持的内容块中引用该标识符。
将文件 ID 视为提供商特定的资源。记录每个 ID 是由哪个提供商和账户创建的，应用你自己的访问控制，并定义删除策略。不应直接从未受信任的用户那里接受文件标识符，而无需授权检查。
对于偶尔使用的小图像，base64 是直接的。对于跨多个请求使用的文档，提供商文件资源可以减少重复上传。如果你的应用程序必须跨多个提供商工作，请将原始对象保存在自己的存储中，并创建提供商特定的文件 ID 作为缓存。
智能体后端的工具使用
工具允许 Claude 请求一个应用程序定义的函数。你的后端用名称、用途和 JSON Schema 输入合约描述每个工具。然后，模型可以返回一个 tool_use 块，而不是假装执行了操作。
{
"name": "get_order_status",
"description": "查找客户订单的当前状态。",
"input_schema": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "向客户显示的订单标识符。"
}
},
"required": ["order_id"]
}
}
安全的执行循环是：
- 将消息和工具定义发送给模型。
- 检测
tool_use内容块。 - 根据 schema 和你的授权规则验证其输入。
- 在受控环境中执行工具。
- 在下一个用户轮次中返回一个匹配的
tool_result块。 - 继续，直到模型产生正常答案或达到你的循环限制。
绝不要将工具参数作为受信任的 shell、SQL 或文件路径执行。对于编码智能体，在隔离的环境中运行生成的命令，例如 Novita Agent Sandbox，并设置明确的超时、网络、文件系统和资源限制。
Anthropic 原生与 OpenAI 兼容请求
Anthropic 原生和 OpenAI 兼容的 API 解决了相同的一般问题，但它们的线格式并不相同。
| 关注点 | Anthropic Messages API | OpenAI 兼容聊天 API |
|---|---|---|
| 常见端点 | /v1/messages |
/v1/chat/completions |
| 系统指令 | 顶层 system 字段 |
通常是 system 或 developer 消息 |
| 输出表示 | 类型化内容块 | 通常是 choices[].message |
| 工具请求 | tool_use 块 |
通常是 tool_calls |
| 工具结果 | tool_result 内容块 |
通常是 tool 角色消息 |
当你的应用程序已经使用 OpenAI SDK 或需要在不同开源模型之间切换并尽量减少传输更改时，OpenAI 兼容端点很有价值。Novita AI 提供了一个 OpenAI 兼容的 LLM API，因此通过更改基础 URL 和模型配置，相同的客户端结构可以针对多个可用模型。
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["NOVITA_API_KEY"],
base_url="https://api.novita.ai/v3/openai",
)
response = client.chat.completions.create(
model=os.environ["NOVITA_MODEL"],
messages=[
{
"role": "user",
"content": "审查这个针对失败模式的重试策略。",
}
],
)
print(response.choices[0].message.content)
这不是每个 Anthropic 功能的无缝转换。如果你的应用程序依赖于 Anthropic 特定的内容块、工具语义、引用或测试版功能，请保留 Anthropic 原生适配器。对于符合其常见请求模型的工作负载，使用共享的 OpenAI 兼容路径。
构建提供商无关的智能体后端
一个提供商无关的后端应该规范化应用程序概念，而不假装所有提供商都相同。一个实用的设计有四个层次：
- 对话模型：将角色、文本、图像、工具调用和工具结果存储在内部模式中。
- 提供商适配器：将内部模式转换为 Anthropic Messages 或 OpenAI 兼容的有效负载。
- 能力注册表：跟踪所选模型是否支持视觉、工具、结构化输出或其他所需行为。
- 执行层：独立于推理提供商运行工具和代码。
这种分离使团队可以在 Anthropic 原生行为重要的地方使用 Claude，同时将兼容的工作负载通过 Novita AI 路由到开源模型。开源路径可用于成本控制、模型实验、数据位置要求或避免单一提供商依赖。在你自己的任务上测试输出质量和工具可靠性，而不是假设两个模型因为都接受聊天消息就互换。
对于智能体工作负载，执行层同样值得关注。模型切换不能保护你的基础设施免受不安全命令的侵害。使用隔离的沙箱，强制执行工具允许列表，限制迭代次数，并记录每个模型决策和工具结果（移除机密）。
常见错误与调试
400 错误请求
检查 JSON 形状、内容块类型、必填字段以及所选模型是否支持请求的功能。记录提供商的请求 ID 和结构化错误体，但删除凭据和 base64 文件数据。
401 认证错误
确认 API 密钥存在于运行时环境中，并属于预期的提供商。Anthropic 在直接 HTTP 请求中使用 x-api-key；OpenAI 兼容客户端通常会自动发送不记名令牌。
404 模型或资源未找到
对照当前提供商文档或控制台验证模型 ID。对于文件 API 资源，还要验证文件是否属于与请求相同的账户和环境。
429 速率限制
使用指数退避和抖动重试，但限制尝试次数。将后台工作排队，限制每个提供商的并发量，并避免以相同间隔立即重试每个失败的请求。
上下文或 Token 限制错误
减少对话历史、图像大小、文件内容或请求的输出长度。计算整个请求，包括系统指令、工具模式、先前的工具结果和多模态内容。
推荐文章
实现清单
- 将 API 密钥、模型 ID、基础 URL 和 API 版本保留在运行时配置中。
- 解析类型化内容块，而不是假设单个文本字符串。
- 存储足够的对话状态，以便重建每个无状态请求。
- 验证工具输入，并在模型进程之外执行它们。
- 添加超时、重试限制、请求 ID 和脱敏的可观测性。
- 根据模型能力（而不仅仅是价格或名称）来决定提供商路由。
- 在部署前重新检查模型 ID、功能状态、限制和定价。
Messages API 在 HTTP 层是直接的。当应用程序添加流式传输、多模态输入、工具、持久化文件或多个模型提供商时，更困难的工程工作就会出现。将这些关注点放在显式适配器后面，你的智能体后端就可以在不将业务逻辑绑定到一种请求格式的情况下演进。
常见问题
Anthropic Messages API 端点是什么？
原生端点是 POST https://api.anthropic.com/v1/messages。请求需要认证、Anthropic API 版本头、模型 ID、token 限制和消息数组。
Anthropic Messages API 是 OpenAI 兼容的吗？
不是。概念重叠，但系统提示、内容块、响应对象和工具使用消息不同。如果一个应用程序需要支持两种格式，请使用提供商适配器。
Claude 视觉 API 使用单独的端点吗？
不。视觉请求使用 Messages API，包含图像和文本内容块。所选 Claude 模型必须支持图像输入。
我应该何时使用 Anthropic 文件 API？
当支持的文件需要在多个请求中引用，并且重复的 base64 上传会造成浪费时使用。保留你自己的源文件和授权记录，因为提供商文件 ID 是特定于账户的资源。
Claude Code 可以使用自定义 API 后端吗？
Claude Code 集成取决于当前 Claude Code 版本支持的认证和提供商配置。不要假设 OpenAI 兼容端点实现了 Anthropic 的 Messages API。对于自定义智能体，使用提供商无关适配器通常比试图让不同协议看起来相同更清晰。
我应该何时通过 Novita AI 选择开源模型？
当你想要 OpenAI 兼容的模型切换、开源模型实验，或为兼容工作负载提供第二个提供商时，可以考虑。对需要 Claude 特定 API 行为的功能保留 Anthropic 原生请求，并在你自己的提示词和工具上评估两种路径。
