Claude API 批量請求（Message Batches）怎麼用：custom_id、輪詢、取結果，價格 50% 與 24 小時規則

本文根據 Claude 官方《Batch processing》整理，資料核對於 2026-11-05。配圖為本站整理的示意圖，不是介面截圖。代碼裏的模型名取自官方當天示例，請以官方模型頁為準。本站（bigolab.com）不是 Anthropic 官方網站。API 是按用量計費的獨立服務，與 Claude 訂閱分開計算，Key 的獲取見 /guides/claude-api-key-console。

適用於誰

• 要一次處理幾百、幾萬條文本的人：評測、分類、摘要、批量生成商品描述；
• 對時效不敏感，但很在意成本的人；
• 同步調用經常撞上限流（見 /guides/claude-api-error-429-rate-limit），想換個不佔用實時額度思路的人。

結論先說

1. 批量請求用 messages.batches：每個請求帶唯一的 custom_id 和一份 params，params 就是普通 Messages 請求的參數。
2. 官方寫明費用為標準價格的 50%（2026-11-05 核對），多數批次在 1 小時內完成。
3. 結果不保證按提交順序返回，一定要用 custom_id 對應。
4. 一個批次最多 100,000 個請求或 256 MB，先到為準；24 小時未處理完的請求會過期，結果保留 29 天。
5. 失敗、取消、過期的請求不收費。

圖：本站根據 Claude 官方《Batch processing》 整理的示意圖

一、創建批次

Python：

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

client = anthropic.Anthropic()

batch = client.messages.batches.create(
    requests=[
        Request(
            custom_id="my-first-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",  # 以官方模型頁當天為準
                max_tokens=1024,
                messages=[{"role": "user", "content": "你好，世界"}],
            ),
        ),
        Request(
            custom_id="my-second-request",
            params=MessageCreateParamsNonStreaming(
                model="claude-opus-5-5",
                max_tokens=1024,
                messages=[{"role": "user", "content": "再問一個問題"}],
            ),
        ),
    ]
)
print(batch.id, batch.processing_status)

TypeScript（先安裝 @anthropic-ai/sdk）：

typescript
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const batch = await client.messages.batches.create({
  requests: [
    {
      custom_id: "my-first-request",
      params: {
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "你好，世界" }],
      },
    },
    {
      custom_id: "my-second-request",
      params: {
        model: "claude-opus-5-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "再問一個問題" }],
      },
    },
  ],
});
console.log(batch.id, batch.processing_status);

規則：

• custom_id 必須在批次內唯一，1 到 64 個字符，只能含字母、數字、連字符和下劃線；
• 批次裏的請求可以混合不同類型：視覺、工具調用、系統提示、多輪對話、思考，官方說幾乎都可以；
• 每個請求的 max_tokens 至少為 1；
• 官方列出批次不支持的參數：stream: true（批次結果是一個文件，不是流）、speed、fallbacks，以及 max_tokens: 0。

一個很容易忽略的點：params 的校驗是異步的，寫錯了不會在創建時報錯，而是整批結束後才在結果裏以 errored 返回。所以官方建議先用普通的 Messages 請求把請求形狀驗證一遍，再批量提交。

二、查看進度：輪詢 processing_status

剛創建時 processing_status 是 in_progress，全部請求處理完才變成 ended。request_counts 裏會記錄 processing、succeeded、errored、canceled、expired 各有多少。官方的輪詢示例就是循環查詢，直到狀態變成 ended：

python
import time

while True:
    batch = client.messages.batches.retrieve(batch.id)
    if batch.processing_status == "ended":
        break
    print("仍在處理中……")
    time.sleep(60)

間隔多久查一次自己定，示例裏是 60 秒。批次的列表、詳情也能在 Claude Console 裏看。

三、取結果

批次結束後，每個請求都有結果，四種類型：

結果文件可能很大，官方建議流式讀取，不要一次全下載：

python
for result in client.messages.batches.results(batch.id):
    outcome = result.result
    if outcome.type == "succeeded":
        print(result.custom_id, outcome.message.content[0].text)
    elif outcome.type == "errored":
        if outcome.error.error.type == "invalid_request_error":
            print("請求本身有問題，要修正後重發：", result.custom_id)
        else:
            print("服務端錯誤，可直接重試：", result.custom_id)
    elif outcome.type == "expired":
        print("已過期：", result.custom_id)

TypeScript 裏用 for await (const result of await client.messages.batches.results(id))，判斷 result.result.type 的方式相同。結果文件的網址在批次的 results_url 字段裏。

最重要的提醒：結果的順序不保證與提交一致，官方的示例裏第二個請求的結果就排在第一個前面。永遠用 custom_id 去對應你的原始數據。

四、取消批次

批次正在處理時可以取消：調用 client.messages.batches.cancel(batch_id)。取消後狀態先變成 canceling，用同樣的輪詢等它變成 ended。終態仍是 ended，裏面可能有取消前已經處理好的部分結果，未處理的就是 canceled，不收費。

五、限制與費用

圖：本站根據 Claude 官方《Batch processing》 整理的示意圖

• 數量與體積：一個批次最多 100,000 個請求或 256 MB，先到者為準；
• 時間：多數批次在 1 小時內完成，但要等整批結束或滿 24 小時才能取結果，24 小時未完成的請求過期；
• 保留：結果在創建後 29 天內可下載，之後批次還能查看，結果不能再下載；
• 費用：官方寫明所有用量按標準 API 價格的 50% 計費。各模型的具體單價以官方價格頁當天為準；
• 花費上限：由於並發處理，批次的花費可能略微超過你在控制檯給工作區設定的上限；
• 限流：批次接口本身以及排隊等待處理的請求數量都有速率限制；需求高峰時處理會變慢，更多請求可能在 24 小時後過期；
• 數據保留：官方標明批處理不符合零數據保留資格，因為結果要保留 29 天。

六、和提示詞緩存一起用

批次裏的請求常常共享同一段很長的前綴，比如同一份文檔或同一套指令，這時適合用提示詞緩存。官方提醒：批次可能超過 5 分鐘才處理完，預設的緩存時間可能已經過期，所以共享上下文的批次建議用 1 小時緩存時長以提高命中率。緩存的寫法見 /guides/claude-prompt-caching。

常見問題

Q：能和流式一起用嗎？

不能，批次裏 stream: true 是不支持的。

Q：想批量處理一批 PDF 或圖片？

可以，批次支持視覺等類型的請求，寫法見 /guides/claude-api-pdf-support 與 /guides/claude-api-image-input。

Q：結果缺了一些請求？

先看 request_counts 裏 errored、expired、canceled 各有多少，再逐個看結果類型。expired 通常是批次到期，可以拆小後重新提交。

Q：怎麼知道一批請求大概多少 token？

先用 token 計數接口估算，見 /guides/claude-api-count-tokens。

參考資料

• Claude 官方：Batch processing — https://platform.claude.com/docs/en/build-with-claude/batch-processing
• Claude 官方：TypeScript SDK — https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript
• Claude 官方：Claude API errors — https://platform.claude.com/docs/en/api/errors