批处理是一种高效处理大量请求的强大方法。与逐个处理请求并立即获得响应不同,批处理允许您将多个请求一起提交以进行异步处理。这种模式在以下情况下特别有用:
Message Batches API 是 Anthropic 对这种模式的首个实现。
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" | 研究预览模式在批处理路径上不可用。 |
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(已停用,Bedrock 和 Google Cloud 除外) | $7.50 / MTok | $37.50 / MTok |
| Claude Opus 4(已停用,Google Cloud 除外) | $7.50 / MTok | $37.50 / MTok |
| Claude Sonnet 5 | $1 / MTok | $5 / 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 调用中会使用的标准参数。
首次创建批次时,响应的处理状态为 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 将被设置为标准的错误结构。
您可以使用取消端点取消当前正在处理的 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 beta 标头可将使用 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 限制的输出。
扩展输出适用于长篇生成,例如书籍长度的草稿和技术文档、详尽的结构化数据提取、大型代码生成脚手架以及长推理链。
单次 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?