批次處理是一種高效處理大量請求的強大方法。與逐一處理請求並立即回應不同，批次處理允許您將多個請求一起提交進行非同步處理。這種模式在以下情況下特別有用：

  • 您需要處理大量資料
  • 不需要立即回應
  • 您希望優化成本效率
  • 您正在執行大規模評估或分析

Message Batches API 是我們對這種模式的首次實現。

​
Message Batches API

Message Batches API 是一種強大且具成本效益的方式，可非同步處理大量的 Messages 請求。這種方法非常適合不需要立即回應的任務，大多數批次會在 1 小時內完成，同時降低 50% 的成本並提高吞吐量。

除了本指南外，您還可以直接探索 API 參考。

​
Message Batches API 的運作方式

當您向 Message Batches API 發送請求時：

  1. 系統會使用提供的 Messages 請求建立一個新的 Message Batch。
  2. 然後批次會被非同步處理，每個請求都會獨立處理。
  3. 您可以輪詢批次的狀態，並在所有請求處理完成後檢索結果。

這對於不需要立即結果的批量操作特別有用，例如：

  • 大規模評估：高效處理數千個測試案例。
  • 內容審核：非同步分析大量使用者生成的內容。
  • 資料分析：為大型資料集生成洞察或摘要。
  • 批量內容生成：為各種目的創建大量文字（例如產品描述、文章摘要）。

​
批次限制

  • Message Batch 限制為 100,000 個 Message 請求或 256 MB 大小，以先達到者為準。
  • 我們會盡快處理每個批次，大多數批次會在 1 小時內完成。當所有訊息都完成或 24 小時後（以先到者為準），您將能夠存取批次結果。如果處理未在 24 小時內完成，批次將過期。
  • 批次結果在建立後 29 天內可用。之後，您仍可檢視批次，但其結果將不再可供下載。
  • 批次的範圍限定在工作區內。您可以檢視在您的 API 金鑰所屬工作區內建立的所有批次及其結果。
  • 速率限制適用於 Batches API HTTP 請求和批次內等待處理的請求數量。請參閱 Message Batches API 速率限制。此外，我們可能會根據當前需求和您的請求量放慢處理速度。在這種情況下，您可能會看到更多請求在 24 小時後過期。
  • 由於高吞吐量和並發處理，批次可能會略微超過您工作區配置的支出限制。

​
支援的模型

Message Batches API 目前支援：

  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 (claude-3-5-sonnet-20240620 和 claude-3-5-sonnet-20241022)
  • Claude Haiku 3.5 (claude-3-5-haiku-20241022)
  • Claude Haiku 3 (claude-3-haiku-20240307)
  • Claude Opus 3 (claude-3-opus-20240229)

​
可以批次處理的內容

任何您可以向 Messages API 發出的請求都可以包含在批次中。這包括：

  • 視覺
  • 工具使用
  • 系統訊息
  • 多輪對話
  • 任何測試版功能

由於批次中的每個請求都是獨立處理的，您可以在單一批次中混合不同類型的請求。

由於批次處理可能需要超過 5 分鐘，在處理具有共享上下文的批次時，考慮使用1 小時快取持續時間與提示快取以獲得更好的快取命中率。

​
定價

Batches 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$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 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

​
如何使用 Message Batches API

​
準備並建立您的批次

Message Batch 由建立 Message 的請求清單組成。單個請求的結構包括：

  • 用於識別 Messages 請求的唯一 custom_id
  • 包含標準 Messages 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-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-20250514",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

在此範例中，兩個獨立的請求被批次處理在一起進行非同步處理。每個請求都有一個唯一的 custom_id 並包含您用於 Messages API 呼叫的標準參數。

使用 Messages API 測試您的批次請求

每個訊息請求的 params 物件驗證是非同步執行的，驗證錯誤會在整個批次處理結束時返回。您可以通過首先使用 Messages 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
}

​
追蹤您的批次

Message Batch 的 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/'

您可以輪詢此端點以了解處理何時結束。

​
檢索批次結果

一旦批次處理結束，批次中的每個 Messages 請求都會有一個結果。有 4 種結果類型：

結果類型描述
succeeded請求成功。包含訊息結果。
errored請求遇到錯誤，未建立訊息。可能的錯誤包括無效請求和內部伺服器錯誤。您不會為這些請求付費。
canceled使用者在此請求發送到模型之前取消了批次。您不會為這些請求付費。
expired批次在此請求發送到模型之前達到了 24 小時過期時間。您不會為這些請求付費。

您將通過批次的 request_counts 看到結果概覽，它顯示有多少請求達到了這四種狀態中的每一種。

批次的結果可在 Message Batch 的 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 物件，代表 Message Batch 中單個請求的結果。對於每個串流結果，您可以根據其 custom_id 和結果類型執行不同的操作。以下是一組範例結果：

.jsonl file
{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-20250514","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_01Fq fsLoHwgeFbguDgpz48m7","type":"message","role":"assistant","model":"claude-opus-4-20250514","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 欄位。

​
在 Message Batches 中使用提示快取

Message Batches API 支援提示快取，允許您可能降低批次請求的成本和處理時間。提示快取和 Message Batches 的定價折扣可以疊加，當兩個功能一起使用時提供更大的成本節省。但是，由於批次請求是非同步和並發處理的，快取命中是基於盡力而為的基礎提供的。使用者通常會體驗到 30% 到 98% 的快取命中率，這取決於他們的流量模式。

要最大化批次請求中快取命中的可能性：

  1. 在批次內的每個 Message 請求中包含相同的 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-opus-4-20250514",
                "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-opus-4-20250514",
                "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 的《傲慢與偏見》全文，以增加快取命中的可能性。

​
有效批次處理的最佳實踐

要充分利用 Batches API：

  • 定期監控批次處理狀態並為失敗的請求實現適當的重試邏輯。
  • 使用有意義的 custom_id 值來輕鬆匹配結果與請求，因為順序不被保證。
  • 考慮將非常大的資料集分解為多個批次以獲得更好的可管理性。
  • 使用 Messages API 對單個請求形狀進行試運行以避免驗證錯誤。

​
常見問題疑難排解

如果遇到意外行為：

  • 驗證批次請求總大小不超過 256 MB。如果請求大小太大，您可能會收到 413 request_too_large 錯誤。
  • 檢查您是否為批次中的所有請求使用支援的模型。
  • 確保批次中的每個請求都有唯一的 custom_id。
  • 確保自批次 created_at（不是處理 ended_at）時間起不到 29 天。如果超過 29 天，結果將不再可檢視。
  • 確認批次尚未被取消。

請注意，批次中一個請求的失敗不會影響其他請求的處理。

​
批次儲存和隱私

  • 工作區隔離：批次在建立它們的工作區內被隔離。它們只能由與該工作區關聯的 API 金鑰或在控制台中有權限檢視工作區批次的使用者存取。

  • 結果可用性：批次結果在批次建立後 29 天內可用，為檢索和處理提供充足的時間。

​
常見問題