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

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

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

​
Message Batches API

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

您可以直接探索API参考，以及本指南。

​
Message Batches API 的工作原理

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

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

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

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

​
批次限制

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

​
支持的模型

Message Batches API 目前支持：

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 和 claude-3-5-sonnet-20241022)
  • Claude Haiku 3.5 (claude-3-5-haiku-20241022)
  • Claude Haiku 3 (claude-3-haiku-20240307)
  • Claude Opus 3 (claude-3-opus-20240229)

​
可以批处理的内容

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

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

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

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

​
定价

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

ModelBatch inputBatch output
Claude Opus 4.1$7.50 / MTok$37.50 / MTok
Claude Opus 4$7.50 / MTok$37.50 / MTok
Claude Sonnet 4$1.50 / MTok$7.50 / MTok
Claude Sonnet 3.7$1.50 / MTok$7.50 / MTok
Claude Sonnet 3.5 (deprecated)$1.50 / MTok$7.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-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "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。您可以通过访问控制台或使用检索端点来监控批次状态：

curl https://api.anthropic.com/v1/messages/batches/msgbatch_01HkcTjaV5uDC8jWR4ZsDV8d \
 --header "x-api-key: $ANTHROPIC_API_KEY" \
 --header "anthropic-version: 2023-06-01" \
 | sed -E 's/.*"id":"([^"]+)".*"processing_status":"([^"]+)".*/Batch \1 processing status is \2/'

您可以轮询此端点以了解处理何时结束。

​
检索批次结果

批次处理结束后，批次中的每个 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-20250514","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-20250514","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 Batches 中使用提示缓存

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

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

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

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

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

​
常见问题