Message Batches API

1バッチあたり最大100,000件のメッセージを送信でき、結果は24時間以内(小規模バッチの場合は数分程度)に返されます。コストは同等の同期呼び出しの約50%です。

使用場面

• オフライン分類(数百万個のアイテムにラベルを付ける)
• 評価ハーネスの実行(複数のモデルバージョンに対して評価スイートを実行)
• リアルタイムレスポンスが不要なコンテンツ生成パイプライン(ニュースレター記事、商品説明)
• 大規模なデータセットアノテーションまたはRAGドキュメント要約
• 過去データをモデル出力で埋め戻す

以下の場合は使用を避けてください:

• レイテンシが重要(ユーザー向け、エージェントループ)
• 出力を連鎖させる必要がある(1つの呼び出しの結果が次の呼び出しの入力になる)
• バッチが非常に小規模(<10呼び出し) — オーケストレーションのオーバーヘッドが見合わない

動作仕組み

バッチはrequestsのリストで、各リクエストは一意のcustom_idと標準的なparamsオブジェクト(同期messages.create呼び出しと同じ形式)を持ちます。APIはバッチIDを返し、完了をポーリングするか結果をリストできます。

POST /v1/messages/batches
[
  { "custom_id": "doc-001", "params": { "model": "claude-sonnet-4-6", ... } },
  { "custom_id": "doc-002", "params": { "model": "claude-sonnet-4-6", ... } }
]

リクエストごとのparamsには、cache_control、ツール、システムプロンプト、thinkingを含められます — これは同期APIと同じインターフェースです。

例

TypeScript

import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic();

// 1. 作成
const batch = await client.messages.batches.create({
  requests: docs.map((doc, i) => ({
    custom_id: `doc-${i}`,
    params: {
      model: "claude-sonnet-4-6",
      max_tokens: 512,
      system: [{ type: "text", text: SYSTEM_PROMPT, cache_control: { type: "ephemeral" } }],
      messages: [{ role: "user", content: `Summarize:\n${doc}` }],
    },
  })),
});

// 2. ポーリング
let status = batch;
while (status.processing_status !== "ended") {
  await new Promise(r => setTimeout(r, 30_000));
  status = await client.messages.batches.retrieve(batch.id);
}

// 3. 結果をストリーミング(JSONL)
const results = await client.messages.batches.results(batch.id);
for await (const item of results) {
  if (item.result.type === "succeeded") {
    console.log(item.custom_id, item.result.message.content);
  } else {
    console.error(item.custom_id, item.result.error);
  }
}

Python

from anthropic import Anthropic
client = Anthropic()

batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": f"doc-{i}",
            "params": {
                "model": "claude-sonnet-4-6",
                "max_tokens": 512,
                "system": [{"type": "text", "text": SYSTEM_PROMPT, "cache_control": {"type": "ephemeral"}}],
                "messages": [{"role": "user", "content": f"Summarize:\n{doc}"}],
            },
        }
        for i, doc in enumerate(docs)
    ]
)

while batch.processing_status != "ended":
    time.sleep(30)
    batch = client.messages.batches.retrieve(batch.id)

for item in client.messages.batches.results(batch.id):
    if item.result.type == "succeeded":
        print(item.custom_id, item.result.message.content)

よくある落とし穴

• custom_idはバッチごとに一意である必要があります。 部分的な失敗時の再試行時に重複を避けるため、安定した冪等なIDを使用してください。
• リクエストごとのエラーはバッチを失敗させません。 常にitem.result.typeを確認してください — succeeded、errored、expired、canceledが考えられます。
• 24時間のSLA、リアルタイムではありません。 ユーザーフローをこれに基づいて構築しないでください。
• ストリーミングはありません。 トークンバイトークンの出力ではなく、完全な応答のみ取得できます。
• レート制限に注意してください。 バッチは実行時に1分あたりのトークン全体の予算に対してカウントされます。
• キャッシュの相互作用。 バッチリクエスト内のキャッシュ境界は機能しますが、キャッシュは単一の共有キャッシュです — バッチ内の重複でもキャッシュにヒットできます。

SDK リファレンス

• TypeScript: @anthropic-ai/sdk >= 0.30
• Python: anthropic >= 0.40
• Anthropic ドキュメント: Message Batches API