Batch API
大量のリクエストを 非同期で安く 処理する API です。
メリット
- 50% オフ の料金。
- 1 ジョブで 10,000 件 まで投入可能。
- 24 時間以内に処理完了 (通常はもっと早い)。
使い方
batch = client.messages.batches.create(
requests=[
{
"custom_id": "task-1",
"params": {
"model": "claude-sonnet-4-6",
"max_tokens": 256,
"messages": [{"role": "user", "content": "..." }],
},
},
# ... 大量の request ...
]
)
print(batch.id)
結果の取得
# ポーリング (簡易)
import time
while True:
status = client.messages.batches.retrieve(batch.id)
if status.processing_status == "ended":
break
time.sleep(30)
for r in client.messages.batches.results(batch.id):
print(r.custom_id, r.result)
ユースケース
- データセットのラベル付け
- 大量ドキュメントの要約
- A/B テスト用の生成
- Eval (評価) スイート実行
- バルクのデータ抽出
注意
- リアルタイム応答には向かない (非同期前提)。
- 失敗したリクエストは個別に確認可能。
- レスポンス順は保証されない (
custom_idで紐づける)。 - Prompt Caching と併用すれば追加で 30-50% コスト削減も可能。
Batch + Cache のシナジー
例: 「1 万件のレビューを同じ system プロンプトで分類」 - Batch: 50% オフ - Cache: 残り料金の 90% オフ (システム部分) - 合計: 元の 5-10% に圧縮
失敗時の挙動
for r in client.messages.batches.results(batch.id):
if r.result.type == "succeeded":
...
elif r.result.type == "errored":
print("error:", r.result.error)