批处理是高效处理大量请求的强大方法。与逐个处理请求并立即响应不同,批处理允许您将多个请求一起提交进行异步处理。这种模式在以下情况下特别有用:
消息批处理API是我们对这种模式的首次实现。
消息批处理API是一种强大且经济高效的方式,可以异步处理大量消息请求。这种方法非常适合不需要立即响应的任务,大多数批处理在1小时内完成,同时降低50%的成本并提高吞吐量。
除了本指南外,您还可以直接探索API参考。
当您向消息批处理API发送请求时:
这对于不需要立即结果的批量操作特别有用,例如:
所有活跃模型都支持消息批处理API。
任何您可以向消息API发出的请求都可以包含在批处理中。这包括:
由于批处理中的每个请求都是独立处理的,您可以在单个批处理中混合不同类型的请求。
由于批处理可能需要超过5分钟的处理时间,在处理具有共享上下文的批处理时,考虑使用1小时缓存持续时间与提示缓存以获得更好的缓存命中率。
批处理API提供显著的成本节省。所有使用按标准API价格的50%收费。
| Model | Batch input | Batch output |
|---|---|---|
| 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 () |
消息批处理由创建消息的请求列表组成。单个请求的结构包括:
custom_idparams对象您可以通过将此列表传递到requests参数中来创建批处理:
在此示例中,两个单独的请求被批处理在一起进行异步处理。每个请求都有一个唯一的custom_id,并包含您用于消息API调用的标准参数。
使用消息API测试您的批处理请求
每个消息请求的params对象的验证是异步执行的,验证错误在整个批处理处理结束时返回。您可以通过首先使用消息API验证您的请求结构来确保正确构建输入。
首次创建批处理时,响应的处理状态为in_progress。
{
"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。您可以通过访问控制台或使用检索端点来监控批处理的状态:
您可以轮询此端点以了解处理何时结束。
批处理处理结束后,批处理中的每个消息请求都将有一个结果。有4种结果类型:
| 结果类型 | 描述 |
|---|---|
succeeded | 请求成功。包含消息结果。 |
errored | 请求遇到错误,未创建消息。可能的错误包括无效请求和内部服务器错误。您不会为这些请求付费。 |
canceled | 用户在此请求发送到模型之前取消了批处理。您不会为这些请求付费。 |
expired | 批处理在此请求发送到模型之前达到了24小时过期时间。您不会为这些请求付费。 |
您将通过批处理的request_counts看到结果概览,显示有多少请求达到了这四种状态中的每一种。
批处理的结果可在消息批处理的results_url属性处下载,如果组织权限允许,也可在控制台中下载。由于结果的潜在大小,建议流式传输结果而不是一次性下载所有结果。
结果将采用.jsonl格式,其中每行是一个有效的JSON对象,表示消息批处理中单个请求的结果。对于每个流式传输的结果,您可以根据其custom_id和结果类型执行不同的操作。以下是一组示例结果:
{"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%的缓存命中率,具体取决于他们的流量模式。
要最大化批处理请求中缓存命中的可能性:
cache_control块在批处理中实现提示缓存的示例:
在此示例中,批处理中的两个请求都包含相同的系统消息和标有cache_control的《傲慢与偏见》全文,以增加缓存命中的可能性。
要充分利用批处理API:
custom_id值来轻松匹配结果与请求,因为不保证顺序。如果遇到意外行为:
request_too_large错误。custom_id。created_at(不是处理ended_at)时间起不到29天。如果超过29天,结果将不再可查看。请注意,批处理中一个请求的失败不会影响其他请求的处理。
工作区隔离:批处理在创建它们的工作区内隔离。它们只能由与该工作区关联的API密钥或在控制台中有权查看工作区批处理的用户访问。
结果可用性:批处理结果在批处理创建后29天内可用,为检索和处理提供充足的时间。
| $7.50 / MTok |
| $37.50 / MTok |
| Claude Haiku 3 | $0.125 / MTok | $0.625 / MTok |
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"}
]
}
}
]
}'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/'#!/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
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."}
]
}
}
]
}'