批处理是高效处理大量请求的强大方法。与逐个处理请求并立即响应不同，批处理允许您将多个请求一起提交进行异步处理。这种模式在以下情况下特别有用：
  • 您需要处理大量数据
  • 不需要立即响应
  • 您希望优化成本效率
  • 您正在运行大规模评估或分析
消息批处理API是我们对这种模式的首次实现。

​
消息批处理API

消息批处理API是一种强大且经济高效的方式，可以异步处理大量消息请求。这种方法非常适合不需要立即响应的任务，大多数批处理在1小时内完成，同时降低50%的成本并提高吞吐量。 除了本指南外，您还可以直接探索API参考。

​
消息批处理API的工作原理

当您向消息批处理API发送请求时：
  1. 系统使用提供的消息请求创建一个新的消息批处理。
  2. 然后异步处理批处理，每个请求独立处理。
  3. 您可以轮询批处理的状态，并在所有请求处理结束时检索结果。
这对于不需要立即结果的批量操作特别有用，例如：
  • 大规模评估：高效处理数千个测试用例。
  • 内容审核：异步分析大量用户生成的内容。
  • 数据分析：为大型数据集生成洞察或摘要。
  • 批量内容生成：为各种目的创建大量文本（例如，产品描述、文章摘要）。

​
批处理限制

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

​
支持的模型

所有活跃模型都支持消息批处理API。

​
可以批处理的内容

任何您可以向消息API发出的请求都可以包含在批处理中。这包括：
  • 视觉
  • 工具使用
  • 系统消息
  • 多轮对话
  • 任何测试版功能
由于批处理中的每个请求都是独立处理的，您可以在单个批处理中混合不同类型的请求。
由于批处理可能需要超过5分钟的处理时间，在处理具有共享上下文的批处理时，考虑使用1小时缓存持续时间与提示缓存以获得更好的缓存命中率。

​
定价

批处理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.5$1.50 / MTok$7.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 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

​
如何使用消息批处理API

​
准备并创建您的批处理

消息批处理由创建消息的请求列表组成。单个请求的结构包括：
  • 用于识别消息请求的唯一custom_id
  • 包含标准消息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-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-sonnet-4-5",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'
在此示例中，两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的custom_id，并包含您用于消息API调用的标准参数。
使用消息API测试您的批处理请求每个消息请求的params对象的验证是异步执行的，验证错误在整个批处理处理结束时返回。您可以通过首先使用消息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
}

​
跟踪您的批处理

消息批处理的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/'
您可以轮询此端点以了解处理何时结束。

​
检索批处理结果

批处理处理结束后，批处理中的每个消息请求都将有一个结果。有4种结果类型：
结果类型描述
succeeded请求成功。包含消息结果。
errored请求遇到错误，未创建消息。可能的错误包括无效请求和内部服务器错误。您不会为这些请求付费。
canceled用户在此请求发送到模型之前取消了批处理。您不会为这些请求付费。
expired批处理在此请求发送到模型之前达到了24小时过期时间。您不会为这些请求付费。
您将通过批处理的request_counts看到结果概览，显示有多少请求达到了这四种状态中的每一种。 批处理的结果可在消息批处理的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对象，表示消息批处理中单个请求的结果。对于每个流式传输的结果，您可以根据其custom_id和结果类型执行不同的操作。以下是一组示例结果：
.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-sonnet-4-5-20250929","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-sonnet-4-5-20250929","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字段。

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

消息批处理API支持提示缓存，允许您可能降低批处理请求的成本和处理时间。提示缓存和消息批处理的定价折扣可以叠加，当两个功能一起使用时提供更大的成本节省。但是，由于批处理请求是异步和并发处理的，缓存命中是基于尽力而为的基础提供的。用户通常体验到30%到98%的缓存命中率，具体取决于他们的流量模式。 要最大化批处理请求中缓存命中的可能性：
  1. 在批处理内的每个消息请求中包含相同的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-sonnet-4-5",
                "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-sonnet-4-5",
                "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天内可用，为检索和处理提供充足的时间。

​
常见问题

批处理可能需要长达24小时的处理时间，但许多会更快完成。实际处理时间取决于批处理的大小、当前需求和您的请求量。批处理可能会过期并在24小时内未完成。
请参阅上面的支持模型列表。
是的，消息批处理API支持消息API中可用的所有功能，包括测试版功能。但是，批处理请求不支持流式传输。
消息批处理API与标准API价格相比提供50%的折扣。这适用于输入令牌、输出令牌和任何特殊令牌。有关定价的更多信息，请访问我们的定价页面。
不可以，一旦提交批处理，就无法修改。如果您需要进行更改，应该取消当前批处理并提交新的批处理。请注意，取消可能不会立即生效。
消息批处理API除了对需要处理的请求数量的限制外，还有基于HTTP请求的速率限制。请参阅消息批处理API速率限制。批处理API的使用不会影响消息API中的速率限制。
当您检索结果时，每个请求都将有一个result字段，指示它是否succeeded、errored、被canceled或expired。对于errored结果，将提供额外的错误信息。在API参考中查看错误响应对象。
消息批处理API设计有强大的隐私和数据分离措施：
  1. 批处理及其结果在创建它们的工作区内隔离。这意味着它们只能由来自同一工作区的API密钥访问。
  2. 批处理内的每个请求都是独立处理的，请求之间没有数据泄漏。
  3. 结果仅在有限时间内可用（29天），并遵循我们的数据保留政策。
  4. 在控制台中下载批处理结果可以在组织级别或按工作区基础上禁用。
是的，可以在消息批处理API中使用提示缓存。但是，由于异步批处理请求可以并发和以任何顺序处理，缓存命中是基于尽力而为的基础提供的。