模型能力

批量处理

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

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

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

支持的模型

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

可以批量处理的内容

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

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

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

由于批次处理时间可能超过 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 的处理状态。

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
}

在消息批处理中使用提示缓存

消息批处理 API 支持提示缓存，可帮助您降低批量请求的成本并缩短处理时间。提示缓存和消息批处理的价格折扣可以叠加，当两个功能同时使用时可获得更大的成本节省。但是，由于批量请求是异步并发处理的，缓存命中是尽力而为的。用户通常会根据其流量模式获得 30% 到 98% 的缓存命中率。

为了最大化批量请求中缓存命中的可能性：

在批次中的每个消息请求中包含相同的 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 的《傲慢与偏见》全文，以提高缓存命中的可能性。

有效批处理的最佳实践

为了充分利用批处理 API：

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

常见问题排查

如果遇到意外行为：

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

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

批次存储与隐私

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

数据保留

批处理会在批次创建后最多 29 天内存储请求和响应数据。您可以在处理完成后随时使用 DELETE /v1/messages/batches/{batch_id} 端点删除消息批次。异步处理需要在服务器端存储输入和输出，直到批次完成并检索结果。

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

常见问题

Was this page helpful?

模型能力

批量处理

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

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

支持的模型

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

可以批量处理的内容

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

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

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

由于批次处理时间可能超过 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 的处理状态。

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
}

在消息批处理中使用提示缓存

为了最大化批量请求中缓存命中的可能性：

在批次中的每个消息请求中包含相同的 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 的《傲慢与偏见》全文，以提高缓存命中的可能性。

有效批处理的最佳实践

为了充分利用批处理 API：

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

常见问题排查

如果遇到意外行为：

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

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

批次存储与隐私

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

数据保留

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

常见问题

Was this page helpful?

Message Batches API

Message Batches API 的工作原理

批次限制

支持的模型

可以批量处理的内容

定价

如何使用 Message Batches API

准备并创建您的批次

跟踪您的批次

轮询 Message Batch 完成状态

列出所有 Message Batches

检索批次结果

取消 Message Batch

在消息批处理中使用提示缓存

有效批处理的最佳实践

常见问题排查

批次存储与隐私

数据保留

常见问题

批次处理需要多长时间？

批处理 API 是否适用于所有模型？

我可以将消息批处理 API 与其他 API 功能一起使用吗？

消息批处理 API 如何影响定价？

我可以在提交批次后更新它吗？

消息批处理 API 是否有速率限制，它们是否与消息 API 速率限制相互影响？

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

消息批处理 API 如何处理隐私和数据分离？

我可以在消息批处理 API 中使用提示缓存吗？

Message Batches API

Message Batches API 的工作原理

批次限制

支持的模型

可以批量处理的内容

定价

如何使用 Message Batches API

准备并创建您的批次

跟踪您的批次

轮询 Message Batch 完成状态

列出所有 Message Batches

检索批次结果

取消 Message Batch

在消息批处理中使用提示缓存

有效批处理的最佳实践

常见问题排查

批次存储与隐私

数据保留

常见问题

批次处理需要多长时间？

批处理 API 是否适用于所有模型？

我可以将消息批处理 API 与其他 API 功能一起使用吗？

消息批处理 API 如何影响定价？

我可以在提交批次后更新它吗？

消息批处理 API 是否有速率限制，它们是否与消息 API 速率限制相互影响？

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

消息批处理 API 如何处理隐私和数据分离？

我可以在消息批处理 API 中使用提示缓存吗？