能力

批量处理

批量处理是一种高效处理大量请求的强大方法。

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

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

Message Batches API 是我们对这种模式的首个实现。

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 天内可用。之后，您仍然可以查看批次，但其结果将不再可供下载。
批次的作用域为工作区。您可以查看在您的 API 密钥所属工作区内创建的所有批次及其结果。
速率限制适用于 Batches API HTTP 请求和批次中等待处理的请求数量。请参阅 Message Batches API 速率限制。此外，我们可能会根据当前需求和您的请求量减慢处理速度。在这种情况下，您可能会看到更多请求在 24 小时后过期。
由于高吞吐量和并发处理，批次可能会略微超出您工作区配置的消费限额。

支持的模型

所有活跃模型都支持 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.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。

JSON

{
  "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。您可以通过访问控制台或使用检索端点来监控批次的状态。

轮询 Message Batch 完成状态

要轮询 Message Batch，您需要其 id，该 ID 在创建批次时的响应中提供，或通过列出批次获取。您可以实现一个轮询循环，定期检查批次状态直到处理结束：

import anthropic
import time

client = anthropic.Anthropic()

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

您可以使用列表端点列出工作区中的所有 Message Batches。API 支持分页，根据需要自动获取更多页面：

import anthropic

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 属性处下载，如果组织权限允许，也可在控制台中查看。由于结果可能非常大，建议流式传输结果而不是一次性全部下载。

#!/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" ]; 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，可能包含取消前已处理请求的部分结果。

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

响应将显示批次处于 canceling 状态：

JSON

{
  "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 的《傲慢与偏见》全文，以增加缓存命中的可能性。

有效批处理的最佳实践

为了充分利用 Batches API：

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

常见问题排查

如果遇到意外行为：

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

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

批量存储和隐私

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

常见问题

Was this page helpful?

能力

批量处理

批量处理是一种高效处理大量请求的强大方法。

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

Message Batches API 是我们对这种模式的首个实现。

Message Batches API

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

Message Batches API 的工作原理

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

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

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

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

批次限制

一个 Message Batch 限制为 100,000 个 Message 请求或 256 MB 大小，以先达到的为准。
我们会尽可能快地处理每个批次，大多数批次在 1 小时内完成。当所有消息完成处理或 24 小时后（以先到者为准），您将能够访问批次结果。如果处理未在 24 小时内完成，批次将过期。
批次结果在创建后 29 天内可用。之后，您仍然可以查看批次，但其结果将不再可供下载。
批次的作用域为工作区。您可以查看在您的 API 密钥所属工作区内创建的所有批次及其结果。
速率限制适用于 Batches API HTTP 请求和批次中等待处理的请求数量。请参阅 Message Batches API 速率限制。此外，我们可能会根据当前需求和您的请求量减慢处理速度。在这种情况下，您可能会看到更多请求在 24 小时后过期。
由于高吞吐量和并发处理，批次可能会略微超出您工作区配置的消费限额。

支持的模型

所有活跃模型都支持 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.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。

JSON

{
  "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 anthropic
import time

client = anthropic.Anthropic()

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

您可以使用列表端点列出工作区中的所有 Message Batches。API 支持分页，根据需要自动获取更多页面：

import anthropic

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 查看结果概览，其中显示了达到这四种状态的请求数量。

#!/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" ]; 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

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

响应将显示批次处于 canceling 状态：

JSON

{
  "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 的《傲慢与偏见》全文，以增加缓存命中的可能性。

有效批处理的最佳实践

为了充分利用 Batches API：

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

常见问题排查

如果遇到意外行为：

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

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

批量存储和隐私

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

常见问题

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