模型能力

批次處理

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

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

Message Batches API 是 Anthropic 對此模式的首個實作。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Message Batches API

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

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

Message Batches API 的運作方式

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

系統會使用提供的 Messages 請求建立新的 Message Batch。
批次隨後以非同步方式處理，每個請求獨立處理。
您可以輪詢批次狀態，並在所有請求的處理結束後擷取結果。

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

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

批次限制

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

支援的模型

所有現行模型均支援 Message Batches API。

可批次處理的內容

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

視覺
工具使用
系統訊息
多輪對話
任何 beta 功能

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

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

定價

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

Model	Batch input	Batch output
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4.5	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.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-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "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。您可以透過造訪主控台或使用擷取端點來監控批次的狀態。

輪詢 Message Batch 完成狀態

要輪詢 Message Batch，您需要其 id，該 id 在建立批次時的回應中提供，或透過列出批次取得。您可以實作一個輪詢迴圈，定期檢查批次狀態，直到處理結束：

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

列出所有 Message Batch

您可以使用列表端點列出工作區中的所有 Message Batch。API 支援分頁，根據需要自動擷取額外頁面：

import anthropic

client = anthropic.Anthropic()

# 根據需要自動擷取更多頁面。
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

擷取批次結果

批次處理結束後，批次中的每個 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-6","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-6","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 Batch

您可以使用取消端點取消目前正在處理的 Message Batch。取消後立即，批次的 processing_status 將為 canceling。您可以使用上述相同的輪詢技術等待取消完成。已取消的批次最終狀態為 ended，可能包含取消前已處理的請求的部分結果。

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

回應將顯示批次處於 canceling 狀態：

JSON

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "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": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

在 Message Batches 中使用提示快取

Message Batches API 支援提示快取，讓您可以潛在地降低批次請求的成本和處理時間。提示快取和 Message Batches 的定價折扣可以疊加，當兩個功能同時使用時可提供更大的成本節省。然而，由於批次請求是非同步且並行處理的，快取命中是以盡力而為的方式提供的。使用者通常會根據其流量模式體驗到 30% 至 98% 的快取命中率。

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

在批次中的每個 Message 請求中包含相同的 cache_control 區塊
維持穩定的請求流，以防止快取條目在 5 分鐘的生命週期後過期
構建您的請求以盡可能共享快取內容

在批次中實作提示快取的範例：

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-6",
                "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-6",
                "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 金鑰存取，或由在 Console 中具有查看工作區批次權限的使用者存取。
結果可用性：批次結果在批次建立後 29 天內可用，提供充足的時間進行擷取和處理。

資料保留

批次處理在批次建立後最多儲存請求和回應資料 29 天。您可以在處理完成後隨時使用 DELETE /v1/messages/batches/{batch_id} 端點刪除訊息批次。非同步處理需要在伺服器端儲存輸入和輸出，直到批次完成並擷取結果。

有關所有功能的 ZDR 資格，請參閱 API 和資料保留。

常見問題

Was this page helpful?

模型能力

批次處理

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

Message Batches API 是 Anthropic 對此模式的首個實作。

This feature is not eligible for Zero Data Retention (ZDR). Data is retained according to the feature's standard retention policy.

Message Batches API

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

Message Batches API 的運作方式

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

系統會使用提供的 Messages 請求建立新的 Message Batch。
批次隨後以非同步方式處理，每個請求獨立處理。
您可以輪詢批次狀態，並在所有請求的處理結束後擷取結果。

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

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

批次限制

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

支援的模型

所有現行模型均支援 Message Batches API。

可批次處理的內容

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

視覺
工具使用
系統訊息
多輪對話
任何 beta 功能

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

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

定價

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

Model	Batch input	Batch output
Claude Opus 4.6	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.5	$2.50 / MTok	$12.50 / MTok
Claude Opus 4.1	$7.50 / MTok	$37.50 / MTok
Claude Opus 4	$7.50 / MTok	$37.50 / MTok
Claude Sonnet 4.6	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4.5	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 4	$1.50 / MTok	$7.50 / MTok
Claude Sonnet 3.7 (deprecated)	$1.50 / MTok	$7.50 / MTok
Claude Haiku 4.5	$0.50 / MTok	$2.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-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hello, world"}
                ]
            }
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-6",
                "max_tokens": 1024,
                "messages": [
                    {"role": "user", "content": "Hi again, friend"}
                ]
            }
        }
    ]
}'

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

使用 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 完成狀態

import anthropic
import time

client = anthropic.Anthropic()

message_batch = None
while True:
    message_batch = client.messages.batches.retrieve(MESSAGE_BATCH_ID)
    if message_batch.processing_status == "ended":
        break

    print(f"Batch {MESSAGE_BATCH_ID} is still processing...")
    time.sleep(60)
print(message_batch)

列出所有 Message Batch

您可以使用列表端點列出工作區中的所有 Message Batch。API 支援分頁，根據需要自動擷取額外頁面：

import anthropic

client = anthropic.Anthropic()

# 根據需要自動擷取更多頁面。
for message_batch in client.messages.batches.list(limit=20):
    print(message_batch)

擷取批次結果

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

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

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

#!/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 file

{"custom_id":"my-second-request","result":{"type":"succeeded","message":{"id":"msg_014VwiXbi91y3JMjcpyGBHX5","type":"message","role":"assistant","model":"claude-opus-4-6","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-6","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 將設定為標準錯誤形狀。

批次結果可能與輸入順序不符

取消 Message Batch

import anthropic

client = anthropic.Anthropic()

message_batch = client.messages.batches.cancel(
    MESSAGE_BATCH_ID,
)
print(message_batch)

回應將顯示批次處於 canceling 狀態：

JSON

{
  "id": "msgbatch_013Zva2CMHLNnXjNJJKqJ2EF",
  "type": "message_batch",
  "processing_status": "canceling",
  "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": "2024-09-24T18:39:03.114875Z",
  "results_url": null
}

在 Message Batches 中使用提示快取

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

在批次中的每個 Message 請求中包含相同的 cache_control 區塊
維持穩定的請求流，以防止快取條目在 5 分鐘的生命週期後過期
構建您的請求以盡可能共享快取內容

在批次中實作提示快取的範例：

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-6",
                "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-6",
                "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 金鑰存取，或由在 Console 中具有查看工作區批次權限的使用者存取。
結果可用性：批次結果在批次建立後 29 天內可用，提供充足的時間進行擷取和處理。

資料保留

有關所有功能的 ZDR 資格，請參閱 API 和資料保留。

常見問題

Was this page helpful?

Message Batches API

Message Batches API 的運作方式

批次限制

支援的模型

可批次處理的內容

定價

如何使用 Message Batches API

準備並建立您的批次

追蹤您的批次

輪詢 Message Batch 完成狀態

列出所有 Message Batch

擷取批次結果

取消 Message Batch

在 Message Batches 中使用提示快取

有效批次處理的最佳實踐

常見問題疑難排解

批次儲存與隱私

資料保留

常見問題

批次處理需要多長時間？

Batches API 是否適用於所有模型？

我可以將 Message Batches API 與其他 API 功能一起使用嗎？

Message Batches API 如何影響定價？

我可以在提交批次後更新它嗎？

Message Batches API 是否有速率限制，它們是否與 Messages API 速率限制互動？

如何處理批次請求中的錯誤？

Message Batches API 如何處理隱私和資料分離？

我可以在 Message Batches API 中使用提示快取嗎？

Message Batches API

Message Batches API 的運作方式

批次限制

支援的模型

可批次處理的內容

定價

如何使用 Message Batches API

準備並建立您的批次

追蹤您的批次

輪詢 Message Batch 完成狀態

列出所有 Message Batch

擷取批次結果

取消 Message Batch

在 Message Batches 中使用提示快取

有效批次處理的最佳實踐

常見問題疑難排解

批次儲存與隱私

資料保留

常見問題

批次處理需要多長時間？

Batches API 是否適用於所有模型？

我可以將 Message Batches API 與其他 API 功能一起使用嗎？

Message Batches API 如何影響定價？

我可以在提交批次後更新它嗎？

Message Batches API 是否有速率限制，它們是否與 Messages API 速率限制互動？

如何處理批次請求中的錯誤？

Message Batches API 如何處理隱私和資料分離？

我可以在 Message Batches API 中使用提示快取嗎？