Claude Batch API 怎么用？Message Batches 批处理教程：成本直降 50%（附 Python 代码）

Claude Batch API 怎么用？这篇 Message Batches 批处理教程讲清 Claude Batch API 的价格（标准价 5 折）、单批 10 万条请求的限制和 24 小时处理时间，用 Python 演示创建批次、轮询状态、读取结果和取消批次，并说明批处理与 Prompt 缓存叠加的省钱方法和适用场景。

SupaStore 成本优化实验室 · 2026-11-05

Claude Batch API 怎么用？Message Batches 批处理教程：成本直降 50%（附 Python 代码）

Claude Batch API（Message Batches API）是 Claude 最直接的省钱方式：把大量不需要实时返回的请求打包成一个批次异步提交，所有 Token 按标准价的 50% 计费。给一万条商品打标签、批量生成摘要、跑模型评测集，用批处理比逐条调用便宜一半，吞吐量也更高。

这篇 Claude Batch API 教程讲清批处理的价格、限制和适用场景，用 Python 演示从创建批次到读取结果的完整流程，最后说明怎样和 Prompt 缓存叠加使用。各模型的标准价格见《Claude API 价格是多少？2026 Claude API 收费标准与省钱指南》。

Claude Batch API 是什么

普通的 Messages API 是"发一条、等一条"；Batch API 则是一次提交一批请求，Anthropic 在后台异步处理，处理完你再统一取结果。官方说明大多数批次在 1 小时内完成，最长不超过 24 小时。

什么场景适合用 Claude 批处理

适合	不适合
批量分类、打标签、信息提取	聊天机器人、实时问答
批量生成摘要、翻译、商品文案	需要流式输出的界面
跑评测集、对比不同提示词效果	Claude Code 这类交互式编程
离线数据清洗、内容审核	需要几秒内拿到结果的接口

一句话：结果晚一点拿到也没关系的任务，都应该考虑批处理。

Claude Batch API 价格

批处理的输入、输出 Token 都按标准价的 5 折计费：

模型	标准输入 / 输出	批处理输入 / 输出
Claude Fable 5.1	$10 / $50	$5 / $25
Claude Opus 5.5	$4 / $20	$2 / $10
Claude Sonnet 5.5	$2 / $10	$1 / $5
Claude Haiku 5.5（≤10 万 Token）	$0.1 / $0.5	$0.05 / $0.25

单位为美元 / 百万 Token，以 Anthropic 官方定价页为准。

算一笔账

用 Sonnet 5.5 处理 1 万条请求，每条输入 2,000 Token、输出 500 Token：

逐条调用：2,000 万输入 × $2 / 1M + 500 万输出 × $10 / 1M = $90
批处理：  2,000 万输入 × $1 / 1M + 500 万输出 × $5  / 1M = $45

同样的任务直接省下一半。失败、过期或被取消的请求不收费。Token 的计算方式见《AI Token 是什么？大模型 Token 怎么计算与计费》。

Claude Batch API 的限制

项目	限制
单个批次大小	最多 10 万条请求或 256 MB，先到为准
处理时间	最长 24 小时，超时未处理的请求会过期
结果保存时间	创建后 29 天内可以下载
可见范围	批次按工作区隔离，只能看到本工作区的批次
不支持的参数	`stream: true`、Fast 模式（`speed`）、`fallbacks`、`max_tokens: 0`

批处理支持视觉输入、工具调用（包括网页搜索等服务端工具）、系统提示、多轮对话和思考功能，同一个批次里可以混合不同类型的请求。

用 Python 调用 Claude Batch API

以下代码使用 Anthropic 官方 Python SDK，安装和配置方法见《Claude API 调用教程：Python 接入 Claude API 完整示例》。

第一步：创建批次

每条请求由 custom_id 和 params 组成，params 的写法和普通 messages.create 完全一样：

import anthropic
from anthropic.types.message_create_params import MessageCreateParamsNonStreaming
from anthropic.types.messages.batch_create_params import Request

client = anthropic.Anthropic()

reviews = ["物流很快，包装完好", "用了三天就坏了", "性价比一般"]

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id=f"review-{i}",
            params=MessageCreateParamsNonStreaming(
                model="claude-haiku-5-5",
                max_tokens=1024,
                messages=[{
                    "role": "user",
                    "content": f"判断这条评价是正面、负面还是中性，只回答一个词：{text}",
                }],
            ),
        )
        for i, text in enumerate(reviews)
    ],
)
print(batch.id, batch.processing_status)

custom_id 必须唯一，长度 1～64 个字符，只能包含字母、数字、连字符和下划线。

第二步：轮询批次状态

批次创建后状态为 in_progress，全部处理完变为 ended：

import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print("处理中：", batch.request_counts)
    time.sleep(60)

第三步：读取结果

结果以流的方式逐条返回，顺序和提交顺序不一定相同，必须用 custom_id 对应：

results = {}
for item in client.messages.batches.results(batch.id):
    outcome = item.result
    if outcome.type == "succeeded":
        results[item.custom_id] = next(
            b.text for b in outcome.message.content if b.type == "text"
        )
    elif outcome.type == "errored":
        if outcome.error.error.type == "invalid_request_error":
            print("请求参数有误，需修改后重发：", item.custom_id)
        else:
            print("服务端错误，可直接重试：", item.custom_id)
    elif outcome.type == "expired":
        print("24 小时内未处理，已过期：", item.custom_id)

print(results)

每条结果有四种状态：succeeded（成功）、errored（出错，不收费）、canceled（被取消，不收费）、expired（过期，不收费）。错误类型的含义见《Claude API 报错怎么办？2026 Claude API 错误码大全》。

取消批次

client.messages.batches.cancel(batch.id)

取消后状态先变为 canceling，最终变为 ended，已经处理完的请求仍然可以读取结果。

批处理 + Prompt 缓存：成本再降一截

批处理的 5 折和 Prompt 缓存的折扣可以叠加。如果一批请求共用一段很长的系统提示或参考文档，给这部分加上 cache_control，命中缓存的输入只按缓存价计费。

因为批次处理可能超过 5 分钟，官方建议共享上下文的批处理使用 1 小时缓存：

params = MessageCreateParamsNonStreaming(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    system=[{
        "type": "text",
        "text": long_guideline,  # 每条请求都相同的长说明
        "cache_control": {"type": "ephemeral", "ttl": "1h"},
    }],
    messages=[{"role": "user", "content": item_text}],
)

批处理中的缓存命中是尽力而为的，所以每条请求里的缓存内容必须完全一致。缓存的写法和命中率排查见《Claude Prompt 缓存怎么用？Prompt Caching 教程》。

Claude Batch API 使用建议

先用普通接口测一条：批次里的参数是异步校验的，格式错误要等整个批次结束才会报出来。先用 messages.create 跑通一条，再批量提交。
大任务拆成多个批次：单批上限 10 万条，拆分后也方便出错时只重跑一部分。
按 custom_id 处理结果：结果顺序不固定，用业务 ID 作为 custom_id，方便回写数据库。
只重试该重试的：invalid_request_error 要改请求，服务端错误和过期的请求可以直接重新提交。
选对模型：分类、打标签这类简单任务用 Haiku 5.5，批处理价格低到每百万输入 Token 只要 $0.05。模型选择见《Claude Opus 和 Sonnet 有什么区别？2026 Claude 模型对比与选型指南》。

通过 API中转站调用时，先确认服务商是否支持 /v1/messages/batches 接口，以及批处理是否按 5 折计费；不支持批处理的中转站，可以用较低并发的普通请求代替，并对比两者的实际单价，换算方法见《API中转站倍率是什么意思？》。

常见问题 (FAQ)

Q: Claude Batch API 便宜多少？

答： Claude Batch API 的输入和输出 Token 都按标准价的 50% 计费，例如 Sonnet 5.5 批处理为每百万输入 Token 1 美元、输出 5 美元，还可以与 Prompt 缓存折扣叠加。

Q: Claude 批处理要多久才能拿到结果？

答：官方说明大多数批次在 1 小时内完成，最长处理 24 小时，超过 24 小时仍未处理的请求会过期且不收费，结果在批次创建后 29 天内可以下载。

Q: 一个批次最多能放多少条请求？

答：单个批次最多 10 万条请求或 256 MB，以先达到的为准，更大的任务需要拆分成多个批次提交。

Q: 批处理结果的顺序和提交顺序一致吗？

答：不一定一致，结果可能以任意顺序返回，需要通过每条请求的 custom_id 把结果和原始数据对应起来。

Q: Claude Batch API 支持流式输出吗？

答：不支持，批处理结果以文件形式统一返回，请求中设置 stream 为 true 会报错；Fast 模式和 max_tokens 为 0 的请求同样不能用于批处理。