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

  • 需要處理大量數據
  • 不需要立即回應
  • 希望優化成本效益
  • 正在進行大規模評估或分析

訊息批次 API 是我們對這種模式的首次實現。

​
訊息批次 API

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

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

​
訊息批次 API 的工作原理

當您向訊息批次 API 發送請求時：

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

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

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

​
批次限制

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

​
支援的模型

訊息批次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)

​
可以批處理的內容

任何可以向訊息API發送的請求都可以包含在批次中。這包括：

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

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

​
定價

批次API提供顯著的成本節省。所有使用費用按標準API價格的50%收取。

ModelBatch inputBatch output
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$1.50 / MTok$7.50 / MTok
Claude Haiku 3.5$0.40 / MTok$2 / MTok
Claude Opus 3$7.50 / MTok$37.50 / MTok
Claude Haiku 3$0.125 / MTok$0.625 / MTok

​
如何使用訊息批次API

​
準備並創建您的批次

訊息批次由一系列創建訊息的請求組成。每個請求的形式包括：

  • 用於識別訊息請求的唯一custom_id
  • 包含標準訊息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，並包含您用於訊息API調用的標準參數。

使用訊息API測試您的批次請求

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

​
追蹤您的批次

訊息批次的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/'

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

​
檢索批次結果

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

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

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

批次的結果可通過訊息批次上的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對象，代表訊息批次中單個請求的結果。對於每個流式傳輸的結果，您可以根據其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_01FqfsLoHwgeFbguDgpz48m7","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字段。

​
在訊息批次中使用提示快取

訊息批次API支持提示快取，允許您潛在地減少批次請求的成本和處理時間。提示快取和訊息批次的價格折扣可以疊加，當兩個功能一起使用時提供更大的成本節省。然而，由於批次請求是非同步並行處理的，快取命中是按最大努力提供的。用戶通常會經歷30%到98%的快取命中率，取決於其流量模式。

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

  1. 在批次中的每個訊息請求中包含相同的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以增加快取命中的可能性。

​
有效批處理的最佳實踐

要充分利用批次API：

  • 定期監控批次處理狀態，並為失敗的請求實施適當的重試邏輯。
  • 使用有意義的custom_id值，以便輕鬆匹配結果與請求，因為順序不能保證。
  • 考慮將非常大的數據集分成多個批次，以便更好地管理。
  • 使用訊息API對單個請求形式進行乾運行，以避免驗證錯誤。

​
常見問題故障排除

如果遇到意外行為：

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

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

​
批次存儲和隱私

  • 工作區隔離：批次在創建它們的工作區內被隔離。它們只能由與該工作區關聯的API密鑰訪問，或由有權限在控制台中查看工作區批次的用戶訪問。

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

​
常見問題