Claude Platform Docs
Messages模型能力

批处理

使用 Message Batches API 异步处理大量 Messages 请求，将成本降低 50% 并提高吞吐量。

"Batch processing"（批处理）是一种高效处理大量请求的强大方法。与逐个处理请求并立即返回响应不同，批处理允许您将多个请求一起提交以进行异步处理。这种模式在以下情况下特别有用：

  • 您需要处理大量数据
  • 不需要立即响应
  • 您希望优化成本效率
  • 您正在运行大规模评估或分析

Message Batches API 是 Anthropic 对这种模式的首次实现。

Message Batches API

Message Batches API 是一种强大且经济高效的方式，用于异步处理大量 Messages 请求。这种方法非常适合不需要立即响应的任务，大多数批次在 1 小时内完成，同时将成本降低 50% 并提高吞吐量。

除本指南外，您还可以直接浏览 API 参考文档。

Message Batches API 的工作原理

当您向 Message Batches API 发送请求时：

  1. 系统会使用所提供的 Messages 请求创建一个新的 Message Batch。
  2. 然后该批次会被异步处理，每个请求独立处理。
  3. 您可以轮询批次的状态，并在所有请求处理结束后检索结果。

这对于不需要立即获得结果的批量操作特别有用，例如：

  • 大规模评估：高效处理数千个测试用例。
  • 内容审核：异步分析大量用户生成的内容。
  • 数据分析：为大型数据集生成洞察或摘要。
  • 批量内容生成：为各种目的创建大量文本（例如，产品描述、文章摘要）。

批次限制

  • 一个 Message Batch 限制为 100,000 个 Message 请求或 256 MB 大小，以先达到者为准。
  • 系统会尽可能快地处理每个批次，大多数批次在 1 小时内完成。您可以在所有消息完成后或 24 小时后（以先到者为准）访问批次结果。如果处理未在 24 小时内完成，批次将过期。
  • 批次结果在创建后 29 天内可用。之后，您仍然可以查看该批次，但其结果将不再可供下载。
  • 批次的作用域限定在一个 Workspace 内。您可以查看在您的请求所运行的 Workspace 中创建的所有批次（及其结果）。
  • "Rate limit"（速率限制）同时适用于 Batches API HTTP 请求和批次中等待处理的请求数量。请参阅 Message Batches API 速率限制。此外，处理速度可能会根据当前需求和您的请求量而减慢。在这种情况下，您可能会看到更多请求在 24 小时后过期。
  • 由于高吞吐量和并发处理，批次可能会略微超出您的 Workspace 配置的支出限额。
  • 每个批处理请求的 max_tokens 必须至少为 1。批次内不支持 max_tokens: 0（缓存预热），因为在批处理期间写入的临时缓存条目很可能在后续请求运行之前就已过期。

支持的模型

所有活跃模型都支持 Message Batches API。

可以批处理的内容

几乎任何您可以向 Messages API 发出的请求都可以包含在批次中。这包括：

  • 视觉
  • 工具使用，包括所有服务器工具（网页搜索、网页抓取、代码执行、MCP 连接器、advisor 和工具搜索）
  • 系统消息
  • 多轮对话
  • 扩展思考
  • 大多数 beta 功能

由于批次中的每个请求都是独立处理的，您可以在单个批次中混合不同类型的请求。

少数 Messages API 参数在批处理请求中不受支持。包含其中任何一个都会返回验证错误：

参数原因
stream: true批处理结果以单个文件形式返回，而不是流。
speed（快速模式）快速模式用于优化同步延迟，不适用于异步批处理。
max_tokens: 0请参阅批处理限制。

定价

Batches API 提供显著的成本节省。所有使用量均按标准 API 价格的 50% 收费。

ModelBatch tokens
NameInputOutput
Claude Fable 5.1For demanding reasoning and long-horizon agentic work
$5 /
$25 / MTok
Claude Opus 5.5For long-running agentic coding and knowledge work
$2 / MTok
$10 / MTok
Claude Sonnet 5The best combination of speed and intelligence
$1 / MTok
$5 / MTok
Claude Haiku 4.5The fastest model with near-frontier intelligence
$0.50 / MTok
$2.50 / MTok
Claude Mythos 5.1
$5 / MTok
$25 / MTok
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
$7.50 / MTok
$37.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
$1.50 / MTok
$7.50 / MTok
Claude Haiku 3.5
$0.40 / MTok
$2 / MTok

如何使用 Message Batches API

准备并创建您的批次

一个 Message Batch 由一组创建 Message 的请求列表组成。单个请求的结构包括：

  • 用于标识 Messages 请求的唯一 custom_id。必须为 1 到 64 个字符，且只能包含字母数字字符、连字符和下划线（匹配 ^[a-zA-Z0-9_-]{1,64}$）。
  • 一个包含标准 Messages API 参数的 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-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

在此示例中，两个独立的请求被一起批处理以进行异步处理。每个请求都有一个唯一的 custom_id，并包含您在 Messages API 调用中会使用的标准参数。

当批次首次创建时，响应的处理状态为 in_progress。

Output
{
  "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 完成状态

要轮询 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)

列出所有 Message Batches

您可以使用列表端点列出您 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",
):
    outcome = result.result
    match outcome.type:
        case "succeeded":
            print(f"Success! {result.custom_id}")
        case "errored":
            if outcome.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 和结果类型执行不同的操作。以下是一组示例结果：

.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-5-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-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

您可以使用取消端点取消当前正在处理的 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 状态：

Output
{
  "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 中使用提示缓存

Message Batches API 支持提示缓存，使您有可能降低批处理请求的成本和处理时间。提示缓存和 Message Batches 的定价折扣可以叠加，当两种功能一起使用时可提供更大的成本节省。但是，由于批处理请求是异步并发处理的，缓存命中是尽力而为提供的。用户通常会体验到 30% 到 98% 的缓存命中率，具体取决于其流量模式。

要最大化批处理请求中缓存命中的可能性：

  1. 在批次中的每个 Message 请求中包含相同的 cache_control 块。
  2. 保持稳定的请求流，以防止缓存条目在其 5 分钟生命周期后过期。
  3. 构建您的请求以共享尽可能多的缓存内容。

在批次中实现提示缓存的示例：

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-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-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 进行限流，以便高并发的批处理不会耗尽您组织的网页搜索速率限制。批次会自动重试被限流的请求；您无需自行处理，但非常大的网页搜索批次可能需要更长时间才能完成。

扩展输出（beta）

output-300k-2026-03-24 beta 标头可将使用 Claude Opus 5.5、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-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 值以便轻松地将结果与请求匹配，因为顺序无法保证。
  • 考虑将非常大的数据集拆分为多个批次，以便更好地管理。
  • 使用 Messages API 对单个请求结构进行试运行，以避免验证错误。

常见问题排查

如果遇到意外行为：

  • 验证批处理请求的总大小不超过 256 MB。如果请求大小过大，您可能会收到 413 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 和数据保留。

常见问题

后续步骤

搜索结果

通过提供带有来源归属的搜索结果，为 RAG 应用启用自然引用。

提示缓存

通过缓存批次中各请求共享的提示前缀来降低成本和延迟。

Was this page helpful?