批处理(batch processing)是一种高效处理大量请求的强大方法。与逐个处理请求并立即获得响应不同,批处理允许您将多个请求一起提交以进行异步处理。这种模式在以下情况下特别有用:
Message Batches API 是 Anthropic 对这种模式的首次实现。
关于 "zero data retention"(零数据保留),即 ZDR 如何适用于此功能,请参阅 API 与数据保留。
Message Batches API 是一种强大且经济高效的方式,用于异步处理大量 Messages 请求。这种方法非常适合不需要立即响应的任务,大多数批次在不到 1 小时内完成,同时降低 50% 的成本并提高吞吐量。
除了本指南之外,您还可以直接浏览 API 参考。
当您向 Message Batches API 发送请求时:
这对于不需要立即获得结果的批量操作特别有用,例如:
max_tokens 必须至少为 1。批次内不支持 max_tokens: 0(缓存预热),因为在批处理期间写入的临时缓存条目很可能在后续请求运行之前就已过期。所有活跃模型都支持 Message Batches API。
几乎所有您可以向 Messages API 发出的请求都可以包含在批次中。这包括:
由于批次中的每个请求都是独立处理的,您可以在单个批次中混合不同类型的请求。
少数 Messages API 参数在批处理请求中不受支持。包含以下任何参数都会返回验证错误:
| 参数 | 原因 |
|---|---|
stream: true | 批次结果以单个文件形式返回,而不是流。 |
speed(快速模式) | 快速模式调优同步延迟,不适用于异步批处理。 |
store / previous_thread_event_id(Threads) | Threads 是有状态的;批处理请求不是。 |
cache_hint / context_hint | 这些路由提示仅适用于同步请求调度。 |
max_tokens: 0 | 请参阅批次限制。 |
research_preview_2026_02: "active" | 研究预览模式在批处理路径上不可用。 |
由于批次处理可能需要超过 5 分钟,在处理具有共享上下文的批次时,请考虑将1 小时缓存持续时间与提示缓存结合使用,以获得更好的缓存命中率。
Batches API 提供显著的成本节省。所有使用量均按标准 API 价格的 50% 收费。
| 模型 | 批处理输入 | 批处理输出 |
|---|---|---|
| Claude Fable 5 | $5 / MTok | $25 / MTok |
| Claude Mythos 5(有限可用) | $5 / MTok | $25 / MTok |
| Claude Opus 5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.8 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.7 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.6 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.5 | $2.50 / MTok | $12.50 / MTok |
| Claude Opus 4.1(已弃用) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4(已停用,Google Cloud 除外) | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5 截至 2026 年 8 月 31 日 | $1 / MTok | $5 / MTok |
| Claude Sonnet 5 自 2026 年 9 月 1 日起 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.6 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4.5 | $1.50 / MTok | $7.50 / MTok |
| Claude Sonnet 4(已停用,Bedrock 和 Google Cloud 除外) | $1.50 / MTok | $7.50 / MTok |
| Claude Haiku 4.5 | $0.50 / MTok | $2.50 / MTok |
| Claude Haiku 3.5(已停用,Bedrock 和 Google Cloud 除外) | $0.40 / MTok | $2 / MTok |
一个 Message Batch 由一个创建 Message 的请求列表组成。单个请求的结构包括:
custom_id。必须为 1 到 64 个字符,且仅包含字母数字字符、连字符和下划线(匹配 ^[a-zA-Z0-9_-]{1,64}$)。params 对象您可以通过将此列表传入 requests 参数来创建批次:
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hello, world",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=1024,
messages=[
{
"role": "user",
"content": "Hi again, friend",
}
],
),
),
]
)
print(message_batch)在此示例中,两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的 custom_id,并包含您在 Messages API 调用中使用的标准参数。
使用 Messages API 测试您的批处理请求
每个消息请求的 params 对象的验证是异步执行的,验证错误会在整个批次处理结束后返回。您可以先使用 Messages API 验证您的请求结构,以确保您正确构建了输入。
首次创建批次时,响应的处理状态为 in_progress。
{
"id": "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
"type": "message_batch",
"processing_status": "in_progress",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": null,
"results_url": null
}Message Batch 的 processing_status 字段指示批次所处的处理阶段。它以 in_progress 开始,然后在批次中的所有请求都完成处理且结果准备就绪后更新为 ended。您可以通过访问 Console 或使用检索端点来监控批次的状态。
要轮询 Message Batch,您需要其 id,该 id 在创建批次时的响应中提供,或通过列出批次获得。您可以实现一个轮询循环,定期检查批次状态,直到处理结束:
import time
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = None
while True:
message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
if message_batch.processing_status == "ended":
break
print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
time.sleep(60)
print(message_batch)您可以使用列表端点列出您的 Workspace 中的所有 Message Batches。该 API 支持分页,会根据需要自动获取其他页面:
client = anthropic.Anthropic()
# 根据需要自动获取更多页面。
for message_batch in client.messages.batches.list(limit=20):
print(message_batch)批次处理结束后,批次中的每个 Messages 请求都有一个结果。有四种结果类型:
| 结果类型 | 描述 |
|---|---|
succeeded | 请求成功。包含消息结果。 |
errored | 请求遇到错误,未创建消息。可能的错误包括无效请求和内部服务器错误。您不会为这些请求付费。 |
canceled | 用户在此请求发送到模型之前取消了批次。您不会为这些请求付费。 |
expired | 批次在此请求发送到模型之前达到了 24 小时过期时间。您不会为这些请求付费。 |
批次的 request_counts 显示了结果的概览,指示有多少请求达到了这四种状态中的每一种。
批次的结果可通过 Message Batch 上的 results_url 属性下载,如果组织权限允许,也可以在 Console 中下载。由于结果可能非常大,建议流式传输结果,而不是一次性全部下载。
client = anthropic.Anthropic()
# 以内存高效的分块方式流式读取结果文件,逐个处理
for result in client.messages.batches.results(
"msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d",
):
match result.result.type:
case "succeeded":
print(f"Success! {result.custom_id}")
case "errored":
if result.result.error.error.type == "invalid_request_error":
# 重新发送请求前必须修正请求体
print(f"Validation error {result.custom_id}")
else:
# 请求可直接重试
print(f"Server error {result.custom_id}")
case "expired":
print(f"Request expired {result.custom_id}")结果采用 .jsonl 格式,其中每一行都是一个有效的 JSON 对象,表示 Message Batch 中单个请求的结果。对于每个流式传输的结果,您可以根据其 custom_id 和结果类型执行不同的操作。以下是一组示例结果:
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5","content":[{"type":"text","text":"Hello again! It's nice to see you. How can I assist you today? Is there anything specific you'd like to chat about or any questions you have?"}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":11,"output_tokens":36}}}}
{"custom_id":"my-first-request","result":{"type":"succeeded","message":{"id":"msg_01FqfsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-5","content":[{"type":"text","text":"Hello! How can I assist you today? Feel free to ask me any questions or let me know if there's anything you'd like to chat about."}],"stop_reason":"end_turn","stop_sequence":null,"usage":{"input_tokens":10,"output_tokens":34}}}}如果您的结果有错误,其 result.error 将被设置为标准的错误结构。
批次结果可能与输入顺序不匹配
批次结果可以以任何顺序返回,并且可能与创建批次时请求的顺序不匹配。在前面的示例中,第二个批处理请求的结果在第一个之前返回。要正确地将结果与其对应的请求匹配,请始终使用 custom_id 字段。
您可以使用取消端点取消当前正在处理的 Message Batch。取消后,批次的 processing_status 将立即变为 canceling。您可以使用前面描述的相同轮询技术等待取消最终完成。已取消的批次最终状态为 ended,并且可能包含在取消之前已处理的请求的部分结果。
client = anthropic.Anthropic()
MESSAGE_BATCH_ID = "msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d"
message_batch = client.messages.batches.cancel(
MESSAGE_BATCH_ID,
)
print(message_batch)响应显示批次处于 canceling 状态:
{
"id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
"type": "message_batch",
"processing_status": "canceling",
"request_counts": {
"processing": 2,
"succeeded": 0,
"errored": 0,
"canceled": 0,
"expired": 0
},
"ended_at": null,
"created_at": "2024-09-24T18:37:24.100435Z",
"expires_at": "2024-09-25T18:37:24.100435Z",
"cancel_initiated_at": "2024-09-24T18:39:03.114875Z",
"results_url": null
}Message Batches API 支持提示缓存,使您有可能降低批处理请求的成本和处理时间。提示缓存和 Message Batches 的价格折扣可以叠加,当两个功能一起使用时可提供更大的成本节省。但是,由于批处理请求是异步并发处理的,缓存命中是尽力而为提供的。用户通常会体验到 30% 到 98% 的缓存命中率,具体取决于其流量模式。
要最大化批处理请求中缓存命中的可能性:
cache_control 块。在批次中实现提示缓存的示例:
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
requests=[
Request(
custom_id="my-first-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Analyze the major themes in Pride and Prejudice.",
}
],
),
),
Request(
custom_id="my-second-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=1024,
system=[
{
"type": "text",
"text": "You are an AI assistant tasked with analyzing literary works. Your goal is to provide insightful commentary on themes, characters, and writing style.\n",
},
{
"type": "text",
"text": "<the entire contents of Pride and Prejudice>",
"cache_control": {"type": "ephemeral"},
},
],
messages=[
{
"role": "user",
"content": "Write a summary of Pride and Prejudice.",
}
],
),
),
]
)在此示例中,批次中的两个请求都包含相同的系统消息和标记了 cache_control 的《傲慢与偏见》全文,以增加缓存命中的可能性。
所有服务器工具(网络搜索、网络获取、代码执行、MCP 连接器、advisor 和工具搜索)都可以在批处理请求中使用。批处理工作进程运行与同步 Messages API 相同的服务器端代理循环。
由于没有需要维护的开放连接,批处理循环在返回 stop_reason: "pause_turn" 之前,每轮运行的迭代次数比同步请求更多。如果批次结果返回 pause_turn,则该轮次未完成;您可以通过在后续请求(批处理或同步)中提交暂停的助手内容来继续它,具体方式与 pause_turn 继续模式中所示完全相同。
批处理工作进程还会按组织对 web_search 进行节流,以便高并发的批处理不会耗尽您组织的网络搜索速率限制。批处理会自动重试被节流的请求;您无需自己处理这个问题,但非常大的网络搜索批次可能需要更长时间才能完成。
output-300k-2026-03-24 测试版标头将使用 Claude Opus 5、Claude Opus 4.8、Claude Opus 4.7、Claude Opus 4.6、Claude Sonnet 5 或 Claude Sonnet 4.6 的批处理请求的 max_tokens 上限提高到 300,000。包含该标头可在单轮中生成远超标准 128k max_tokens 限制的输出。
扩展输出仅在 Message Batches API 上可用,不适用于同步 Messages API。它在 Claude API 和 AWS 上的 Claude Platform 上受支持,目前在 Amazon Bedrock、Google Cloud 或 Microsoft Foundry 上不可用。
将扩展输出用于长篇生成,例如书籍长度的草稿和技术文档、详尽的结构化数据提取、大型代码生成脚手架以及长推理链。
单次 300k 令牌的生成可能需要一个多小时才能完成,因此请在规划批次提交时考虑 24 小时的处理窗口。适用标准批处理定价(标准 API 价格的 50%)。
from anthropic.types.beta.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.beta.messages.batch_create_params import Request
client = anthropic.Anthropic()
message_batch = client.beta.messages.batches.create(
betas=["output-300k-2026-03-24"],
requests=[
Request(
custom_id="long-form-request",
params=MessageCreateParamsNonStreaming(
model="claude-opus-5",
max_tokens=300_000,
messages=[
{
"role": "user",
"content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices.",
}
],
),
),
],
)
print(message_batch)要充分利用 Batches API:
custom_id 值,以便轻松地将结果与请求匹配,因为顺序无法保证。如果遇到意外行为:
request_too_large 错误。custom_id。created_at(而非处理 ended_at)时间不超过 29 天。如果超过 29 天,结果将不再可查看。请注意,批次中一个请求的失败不会影响其他请求的处理。
Workspace 隔离:批次在创建它们的 Workspace 内隔离。它们只能由与该 Workspace 关联的 API 密钥访问,或由在 Console 中有权查看 Workspace 批次的用户访问。
结果可用性:批次结果在批次创建后 29 天内可用,为检索和处理提供充足的时间。
批处理会在批次创建后最多 29 天内存储请求和响应数据。处理完成后,您可以随时使用 DELETE /v1/messages/batches/{batch_id} 端点删除消息批次。要删除正在进行中的批次,请先取消它。异步处理需要在服务器端存储输入和输出,直到批次完成和结果检索。
有关所有功能的 ZDR 资格,请参阅 API 和数据保留。
Was this page helpful?