Claude 批处理 API（Message Batches）参考

本文是对 Anthropic 官方参考页 Message Batches API（批处理）的中文整理，完整与最新内容以原文为准：https://platform.claude.com/docs/en/build-with-claude/batch-processing

概述

Message Batches API 用于异步、低成本地处理大批量 Messages 请求，适合不需要即时响应的场景。

工作原理

1. 提交请求后系统创建一个新的 Message Batch。
2. 批次进入异步处理，其中每个请求独立处理。
3. 可轮询批次状态，处理结束后取回结果。

查询批次的端点（retrieve）是幂等的，可直接用于轮询批次是否完成；完成后通过响应中的 results_url 字段获取结果文件。

API 端点一览

请求需带标准鉴权头：anthropic-version（如 2023-06-01）与 X-Api-Key；可选头 anthropic-user-profile-id（需配合 user-profiles beta 头）用于按用户画像归因。

创建批处理（POST /v1/messages/batches）

请求体

requests 数组中每一项结构：

params 沿用 Messages API 全部参数，例如：

示例请求

{
  "requests": [
    {
      "custom_id": "request-1",
      "params": {
        "model": "claude-opus-4-5",
        "max_tokens": 1024,
        "messages": [{"role": "user", "content": "Hello, Claude"}]
      }
    }
  ]
}

Message Batch 对象字段

创建/查询/列出/取消四个端点返回同一个 MessageBatch 对象：

request_counts 字段

所有请求初始状态均为 processing，只有在整个批次结束后才会分流到其余四个终态，且各字段之和恒等于批次总请求数。

获取结果（GET .../results）

结果以 .jsonl 文件流式返回，每行是一个 MessageBatchIndividualResponse 对象，顺序不保证与提交顺序一致，须用 custom_id 匹配。

result.type 取值

errored 结果中的 error.error.type 取值

取消批处理（POST .../cancel）

• 可在处理结束前的任意时间取消。
• 取消发起后批次进入 canceling 状态，系统可能先完成部分不可中断的进行中请求，再最终完成取消。
• 实际被取消的请求数体现在 request_counts.canceled 中；若请求均不可中断，取消操作也可能不产生任何 canceled 结果。

删除批处理（DELETE .../{id}）

• 仅能删除已结束处理的批次；若要删除进行中的批次，须先调用 cancel。
• 返回 DeletedMessageBatch 对象：{ id, type: "message_batch_deleted" }。

限流（Message Batches API 专属）

批处理限流与 Messages API 的按模型限流相互独立，所有模型共享同一套批处理限流；其中「batch request」指一个批次中的一条子请求。

「处理队列中的 batch request」指尚未被模型成功处理完成的子请求；单个批次内的请求数量存在 100,000 条上限（与 Create 端点文档中「单个请求内 messages 数组上限 100,000 条」是两个不同的限制，不要混淆）。

定价

Batch API 相比标准价固定提供 50% 折扣（输入、输出 token 同折）。示例（节选官方定价表）：

补充说明：

• Batch 折扣可与 Prompt Caching 的缓存写入/命中倍率叠加。
• Fast mode 不支持 Batch API（二者互斥）。
• Batch API 折扣不适用于 Claude Managed Agents（该产品为有状态交互式会话，无批处理模式）。

关键注意事项