模型能力

批量处理

使用 Message Batches API 高效处理大量请求

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

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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 配置的支出限制。

支持的模型

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

可以批处理的内容

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

视觉
工具使用
系统消息
多轮对话
任何测试版功能

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

由于批次处理可能需要超过 5 分钟，请考虑在处理具有共享上下文的批次时使用 1 小时缓存持续时间和提示缓存以获得更好的缓存命中率。

定价

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

Model	Batch input	Batch output
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 Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.50 / MTok
Claude Haiku 3.5	$0.40 / MTok	$2 / MTok
Claude Opus 3 (deprecated)	$7.50 / MTok	$37.50 / MTok
Claude Haiku 3	$0.125 / MTok	$0.625 / MTok

如何使用 Message Batches API

准备并创建您的批次

Message Batch 由创建 Message 的请求列表组成。单个请求的形状包括：

用于标识 Messages 请求的唯一 custom_id
包含标准 Messages API 参数的 params 对象

您可以通过将此列表传递到 requests 参数来创建批次：

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

在此示例中，两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的 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 在创建批次时的响应中提供，或通过列出批次获得。您可以实现一个轮询循环，定期检查批次状态，直到处理完成：

#!/bin/sh
# ...
until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
          --header "x-api-key: $ANTHROPIC_API_KEY" \
          --header "anthropic-version: 2023-06-01" \
          | grep -o '"processing_status":[[:space:]]*"[^"]*"' \
          | cut -d'"' -f4) == "ended" ]]; do
    echo "Batch $MESSAGE_BATCH_ID is still processing..."
# ...
    sleep 60
done

echo "Batch $MESSAGE_BATCH_ID has finished processing"

列出所有 Message Batches

您可以使用列表端点列出 Workspace 中的所有 Message Batches。该 API 支持分页，根据需要自动获取其他页面：

#!/bin/sh

if ! command -v jq &> /dev/null; then
    echo "Error: This script requires jq. Please install it first."
    exit 1
fi

BASE_URL="https://api.anthropic.com/v1/messages/batches"

has_more=true
after_id=""

while [ "$has_more" = true ]; do
    # Construct URL with after_id if it exists
    if [ -n "$after_id" ]; then
        url="${BASE_URL}?limit=20&after_id=${after_id}"
    else
        url="$BASE_URL?limit=20"
    fi

    response=$(curl -s "$url" \
              --header "x-api-key: $ANTHROPIC_API_KEY" \
              --header "anthropic-version: 2023-06-01")

    # Extract values using jq
    has_more=$(echo "$response" | jq -r '.has_more')
    after_id=$(echo "$response" | jq -r '.last_id')

    # Process and print each entry in the data array
    echo "$response" | jq -c '.data[]' | while read -r entry; do
        echo "$entry" | jq '.'
    done
done

检索批处理结果

批处理完成后，批处理中的每个 Messages 请求都有一个结果。有 4 种结果类型：

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

您将看到批处理结果的概览，其中包含批处理的 request_counts，显示有多少请求达到了这四种状态中的每一种。

批处理的结果可在 Message Batch 上的 results_url 属性处下载，如果组织权限允许，也可在 Console 中下载。由于结果的潜在大小，建议流式传输结果而不是一次性下载所有结果。

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request_error" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

结果采用 .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-6","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-6","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，可能包含取消前已处理的请求的部分结果。

#!/bin/sh
# ...
curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01"

响应将显示处于 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 分钟生命周期后过期
构造您的请求以共享尽可能多的缓存内容

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

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "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."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "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 的完整 Pride and Prejudice 文本，以增加缓存命中的可能性。

扩展输出（测试版）

output-300k-2026-03-24 测试版标头将 max_tokens 上限提高到 300,000，用于使用 Claude Opus 4.6 或 Claude Sonnet 4.6 的批量请求。包含该标头以在单个回合中生成远长于标准限制（根据模型为 64k 到 128k）的输出。

扩展输出仅在 Message Batches API 上可用，不在同步 Messages API 上可用。它在 Claude API 上受支持，在 Amazon Bedrock、Vertex AI 或 Microsoft Foundry 上不可用。

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

单个 300k 令牌生成可能需要超过一小时才能完成，因此请根据 24 小时处理窗口计划您的批量提交。标准批量定价（标准 API 价格的 50%）适用。

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: output-300k-2026-03-24" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "long-form-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 300000,
                "messages": [
                    {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
                ]
            }
        }
    ]
}'

有效批处理的最佳实践

为了充分利用 Batches API：

定期监控批处理状态并为失败的请求实现适当的重试逻辑。
使用有意义的 custom_id 值来轻松匹配结果与请求，因为顺序不保证。
考虑将非常大的数据集分解为多个批次以便更好地管理。
使用 Messages API 对单个请求形状进行干运行以避免验证错误。

常见问题故障排除

如果遇到意外行为：

验证总批量请求大小不超过 256 MB。如果请求大小过大，您可能会收到 413 request_too_large 错误。
检查您是否为批量中的所有请求使用支持的模型。
确保批量中的每个请求都有唯一的 custom_id。
确保自批量 created_at（不是处理 ended_at）时间以来已不足 29 天。如果已超过 29 天，结果将不再可查看。
确认批量尚未被取消。

请注意，批量中一个请求的失败不会影响其他请求的处理。

批处理存储和隐私

工作区隔离：批处理在创建它们的工作区内隔离。它们只能由与该工作区关联的 API 密钥或有权限在 Console 中查看工作区批处理的用户访问。
结果可用性：批处理结果在创建批处理后的 29 天内可用，为检索和处理提供充足的时间。

数据保留

批处理存储请求和响应数据长达批处理创建后的 29 天。您可以在处理后的任何时间使用 DELETE /v1/messages/batches/{batch_id} 端点删除消息批处理。要删除正在进行的批处理，请先取消它。异步处理需要服务器端存储输入和输出，直到批处理完成和结果检索。

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

常见问题

Was this page helpful?

模型能力

批量处理

使用 Message Batches API 高效处理大量请求

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

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

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

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 配置的支出限制。

支持的模型

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

可以批处理的内容

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

视觉
工具使用
系统消息
多轮对话
任何测试版功能

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

由于批次处理可能需要超过 5 分钟，请考虑在处理具有共享上下文的批次时使用 1 小时缓存持续时间和提示缓存以获得更好的缓存命中率。

定价

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

Model	Batch input	Batch output
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 Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.50 / MTok
Claude Haiku 3.5	$0.40 / MTok	$2 / MTok
Claude Opus 3 (deprecated)	$7.50 / MTok	$37.50 / MTok
Claude Haiku 3	$0.125 / MTok	$0.625 / MTok

如何使用 Message Batches API

准备并创建您的批次

Message Batch 由创建 Message 的请求列表组成。单个请求的形状包括：

用于标识 Messages 请求的唯一 custom_id
包含标准 Messages API 参数的 params 对象

您可以通过将此列表传递到 requests 参数来创建批次：

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

在此示例中，两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的 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 完成

#!/bin/sh
# ...
until [[ $(curl -s "https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID" \
          --header "x-api-key: $ANTHROPIC_API_KEY" \
          --header "anthropic-version: 2023-06-01" \
          | grep -o '"processing_status":[[:space:]]*"[^"]*"' \
          | cut -d'"' -f4) == "ended" ]]; do
    echo "Batch $MESSAGE_BATCH_ID is still processing..."
# ...
    sleep 60
done

echo "Batch $MESSAGE_BATCH_ID has finished processing"

列出所有 Message Batches

您可以使用列表端点列出 Workspace 中的所有 Message Batches。该 API 支持分页，根据需要自动获取其他页面：

#!/bin/sh

if ! command -v jq &> /dev/null; then
    echo "Error: This script requires jq. Please install it first."
    exit 1
fi

BASE_URL="https://api.anthropic.com/v1/messages/batches"

has_more=true
after_id=""

while [ "$has_more" = true ]; do
    # Construct URL with after_id if it exists
    if [ -n "$after_id" ]; then
        url="${BASE_URL}?limit=20&after_id=${after_id}"
    else
        url="$BASE_URL?limit=20"
    fi

    response=$(curl -s "$url" \
              --header "x-api-key: $ANTHROPIC_API_KEY" \
              --header "anthropic-version: 2023-06-01")

    # Extract values using jq
    has_more=$(echo "$response" | jq -r '.has_more')
    after_id=$(echo "$response" | jq -r '.last_id')

    # Process and print each entry in the data array
    echo "$response" | jq -c '.data[]' | while read -r entry; do
        echo "$entry" | jq '.'
    done
done

检索批处理结果

批处理完成后，批处理中的每个 Messages 请求都有一个结果。有 4 种结果类型：

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

您将看到批处理结果的概览，其中包含批处理的 request_counts，显示有多少请求达到了这四种状态中的每一种。

#!/bin/sh
curl "https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d" \
  --header "anthropic-version: 2023-06-01" \
  --header "x-api-key: $ANTHROPIC_API_KEY" \
  | grep -o '"results_url":[[:space:]]*"[^"]*"' \
  | cut -d'"' -f4 \
  | while read -r url; do
    curl -s "$url" \
      --header "anthropic-version: 2023-06-01" \
      --header "x-api-key: $ANTHROPIC_API_KEY" \
      | sed 's/}{/}\n{/g' \
      | while IFS= read -r line
    do
      result_type=$(echo "$line" | sed -n 's/.*"result":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')
      custom_id=$(echo "$line" | sed -n 's/.*"custom_id":[[:space:]]*"\([^"]*\)".*/\1/p')
      error_type=$(echo "$line" | sed -n 's/.*"error":[[:space:]]*{[[:space:]]*"type":[[:space:]]*"\([^"]*\)".*/\1/p')

      case "$result_type" in
        "succeeded")
          echo "Success! $custom_id"
          ;;
        "errored")
          if [ "$error_type" = "invalid_request_error" ]; then
            # Request body must be fixed before re-sending request
            echo "Validation error: $custom_id"
          else
            # Request can be retried directly
            echo "Server error: $custom_id"
          fi
          ;;
        "expired")
          echo "Expired: $line"
          ;;
      esac
    done
  done

.jsonl file

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

#!/bin/sh
# ...
curl --request POST https://api.anthropic.com/v1/messages/batches/$MESSAGE_BATCH_ID/cancel \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01"

响应将显示处于 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 分钟生命周期后过期
构造您的请求以共享尽可能多的缓存内容

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

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-6",
                "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."}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "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 的完整 Pride and Prejudice 文本，以增加缓存命中的可能性。

扩展输出（测试版）

扩展输出仅在 Message Batches API 上可用，不在同步 Messages API 上可用。它在 Claude API 上受支持，在 Amazon Bedrock、Vertex AI 或 Microsoft Foundry 上不可用。

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

单个 300k 令牌生成可能需要超过一小时才能完成，因此请根据 24 小时处理窗口计划您的批量提交。标准批量定价（标准 API 价格的 50%）适用。

curl https://api.anthropic.com/v1/messages/batches \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "anthropic-beta: output-300k-2026-03-24" \
     --header "content-type: application/json" \
     --data \
'{
    "requests": [
        {
            "custom_id": "long-form-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 300000,
                "messages": [
                    {"role": "user", "content": "Write a comprehensive technical guide to building distributed systems, covering architecture patterns, consistency models, fault tolerance, and operational best practices."}
                ]
            }
        }
    ]
}'

有效批处理的最佳实践

为了充分利用 Batches API：

定期监控批处理状态并为失败的请求实现适当的重试逻辑。
使用有意义的 custom_id 值来轻松匹配结果与请求，因为顺序不保证。
考虑将非常大的数据集分解为多个批次以便更好地管理。
使用 Messages API 对单个请求形状进行干运行以避免验证错误。

常见问题故障排除

如果遇到意外行为：

验证总批量请求大小不超过 256 MB。如果请求大小过大，您可能会收到 413 request_too_large 错误。
检查您是否为批量中的所有请求使用支持的模型。
确保批量中的每个请求都有唯一的 custom_id。
确保自批量 created_at（不是处理 ended_at）时间以来已不足 29 天。如果已超过 29 天，结果将不再可查看。
确认批量尚未被取消。

请注意，批量中一个请求的失败不会影响其他请求的处理。

批处理存储和隐私

工作区隔离：批处理在创建它们的工作区内隔离。它们只能由与该工作区关联的 API 密钥或有权限在 Console 中查看工作区批处理的用户访问。
结果可用性：批处理结果在创建批处理后的 29 天内可用，为检索和处理提供充足的时间。

数据保留

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

常见问题

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 中使用提示词缓存吗？