消息模型能力

批处理

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

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

Message Batches API 是 Anthropic 对此模式的首个实现。

此功能不符合零数据保留（ZDR）的条件。数据将根据该功能的标准保留策略进行保留。

Message Batches API

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

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

Message Batches API 的工作原理

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

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

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

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

批处理限制

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

支持的模型

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

可批处理的内容

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

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

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

少数 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 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（已停用，Vertex AI 除外）	$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（已停用，Bedrock 和 Vertex AI 除外）	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.50 / MTok
Claude Haiku 3.5（已停用，Bedrock 和 Vertex AI 除外）	$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-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

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

使用 Messages API 测试您的批处理请求

每个消息请求的 params 对象的验证是异步执行的，验证错误会在整个批次处理结束后返回。您可以先通过 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 请求都会有一个结果。共有 4 种结果类型：

结果类型	描述
`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 和结果类型执行不同的操作。以下是一组结果示例：

.jsonl file

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

您可以使用取消端点取消当前正在处理的 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% 的缓存命中率。

要最大限度地提高批处理请求中的缓存命中率：

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

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

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-4-8",
                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-4-8",
                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 4.8、Claude Opus 4.7、Claude Opus 4.6 或 Claude Sonnet 4.6 的批处理请求的 max_tokens 上限提高到 300,000。包含此标头可在单轮中生成远超标准限制（根据模型不同为 64k 到 128k）的输出。

扩展输出仅在 Message Batches API 上可用，不适用于同步 Messages API。它在 Claude API 和 AWS 上的 Claude Platform 上受支持，目前在 Amazon Bedrock、Vertex AI 或 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-4-8",
                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?

消息模型能力

批处理

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

Message Batches API 是 Anthropic 对此模式的首个实现。

此功能不符合零数据保留（ZDR）的条件。数据将根据该功能的标准保留策略进行保留。

Message Batches API

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

Message Batches API 的工作原理

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

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

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

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

批处理限制

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

支持的模型

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

可批处理的内容

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

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

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

少数 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 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（已停用，Vertex AI 除外）	$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（已停用，Bedrock 和 Vertex AI 除外）	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.50 / MTok
Claude Haiku 3.5（已停用，Bedrock 和 Vertex AI 除外）	$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-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hello, world",
                    }
                ],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-4-8",
                max_tokens=1024,
                messages=[
                    {
                        "role": "user",
                        "content": "Hi again, friend",
                    }
                ],
            ),
        ),
    ]
)

print(message_batch)

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

使用 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 完成状态

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 请求都会有一个结果。共有 4 种结果类型：

结果类型	描述
`succeeded`	请求成功。包含消息结果。
`errored`	请求遇到错误，未创建消息。可能的错误包括无效请求和内部服务器错误。这些请求不会向您收费。
`canceled`	用户在此请求发送到模型之前取消了批次。这些请求不会向您收费。
`expired`	批次在此请求发送到模型之前已达到 24 小时过期时间。这些请求不会向您收费。

您可以通过批次的 request_counts 查看结果概览，其中显示了达到这四种状态的请求数量。

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 file

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

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 请求中包含相同的 cache_control 块
保持稳定的请求流，以防止缓存条目在其 5 分钟生命周期后过期
构建您的请求以尽可能多地共享缓存内容

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

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-4-8",
                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-4-8",
                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 的《傲慢与偏见》全文，以提高缓存命中的可能性。

服务器工具和智能体循环

扩展输出（测试版）

扩展输出适用于长篇内容生成，例如书籍长度的草稿和技术文档、详尽的结构化数据提取、大型代码生成脚手架以及长推理链。

单次 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-4-8",
                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 天内可用，为检索和处理提供充足的时间。

数据保留

有关所有功能的 ZDR 资格，请参阅 API 和数据保留。

常见问题

后续步骤

搜索结果

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

提示缓存

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

Was this page helpful?

Message Batches API

Message Batches API 的工作原理

批处理限制

支持的模型

可批处理的内容

定价

如何使用 Message Batches API

准备并创建批次

跟踪批次

轮询 Message Batch 完成状态

列出所有 Message Batches

检索批次结果

取消 Message Batch

在 Message Batches 中使用提示缓存

服务器工具和智能体循环

扩展输出（测试版）

有效批处理的最佳实践

常见问题排查

批次存储和隐私

数据保留

常见问题

批次处理需要多长时间？

Batches API 是否适用于所有模型？

我可以将 Message Batches API 与其他 API 功能一起使用吗？

Message Batches API 如何影响定价？

提交批次后可以更新吗？

Message Batches API 是否有速率限制？它们是否与 Messages API 速率限制相互影响？

如何处理批处理请求中的错误？

Message Batches API 如何处理隐私和数据隔离？

我可以在 Message Batches API 中使用提示缓存吗？

后续步骤

Message Batches API

Message Batches API 的工作原理

批处理限制

支持的模型

可批处理的内容

定价

如何使用 Message Batches API

准备并创建批次

跟踪批次

轮询 Message Batch 完成状态

列出所有 Message Batches

检索批次结果

取消 Message Batch

在 Message Batches 中使用提示缓存

服务器工具和智能体循环

扩展输出（测试版）

有效批处理的最佳实践

常见问题排查

批次存储和隐私

数据保留

常见问题

批次处理需要多长时间？

Batches API 是否适用于所有模型？

我可以将 Message Batches API 与其他 API 功能一起使用吗？

Message Batches API 如何影响定价？

提交批次后可以更新吗？

Message Batches API 是否有速率限制？它们是否与 Messages API 速率限制相互影响？

如何处理批处理请求中的错误？

Message Batches API 如何处理隐私和数据隔离？

我可以在 Message Batches API 中使用提示缓存吗？

后续步骤

Message Batches API

Message Batches API 的工作原理

批处理限制

支持的模型

可批处理的内容

定价

如何使用 Message Batches API

准备并创建批次

跟踪批次

轮询 Message Batch 完成状态

列出所有 Message Batches

检索批次结果

取消 Message Batch

在 Message Batches 中使用提示缓存

服务器工具和智能体循环

扩展输出（测试版）

有效批处理的最佳实践

常见问题排查

批次存储和隐私

数据保留

常见问题

后续步骤

Message Batches API

Message Batches API 的工作原理

批处理限制

支持的模型

可批处理的内容

定价

如何使用 Message Batches API

准备并创建批次

跟踪批次

轮询 Message Batch 完成状态

列出所有 Message Batches

检索批次结果

取消 Message Batch

在 Message Batches 中使用提示缓存

服务器工具和智能体循环

扩展输出（测试版）

有效批处理的最佳实践

常见问题排查

批次存储和隐私

数据保留

常见问题

后续步骤