API による文書の一括処理
数百のファイルを変換・圧縮・OCR できます。バッチジョブとワークフローの一括実行から選び、プランの上限内に収め、失敗したものだけを再試行します。
要点
1 回の呼び出しで最大 20 ファイルを 1 ステップで変換するなら、"jobs" 配列を付けた POST /api/v1/jobs/batch/ を使い、GET /api/v1/jobs/batch/{batchId}/ で追跡します。ファイルごとに複数のステップが必要なら、ワークフローを作成し、"mode": "each" で 1 回の呼び出しにつき最大 100 ドキュメントに実行します。各呼び出しに固定の Idempotency-Key を付ければ、再試行時は足りない分だけが開始されます。
適切な方法を選ぶ
Free プランでは処理の呼び出しごとに 1 日 10 リクエストのうち 1 つを消費するため、一括処理には有料プランか購入したクレジットが必要です。
| 用途 | 使うもの | 1 回の呼び出しあたり |
|---|---|---|
| 多数のファイルに同じ変換 (DOCX → PDF) | POST /jobs/batch/ | 1–20 ファイル、1 バッチにつき 2 クレジット |
| ファイルごとに複数のステップ (変換、圧縮、回転) | ワークフロー + mode "each" での実行 | 1–100 ドキュメント、1 回の実行につき 3 クレジット |
| 多数のファイルを 1 つにまとめる (結合) | ワークフロー + mode "together" での実行 | 1 回の実行で最大 100 ドキュメント |
| 動画と音声 | ファイルごとに /media/process/ ジョブを 1 つ | 1 ファイル、1 クレジット |
一括変換
各項目は POST /jobs/ と同じフィールド (url または sourceKey、filename、format、任意で inputFormat) を受け付けます。バッチは全体で検証され (最初の不正な項目のインデックスがレスポンスに示されます)、各項目が個別のジョブになります。
curl -X POST 'https://maxscanner.app/api/v1/jobs/batch/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-d '{ "jobs": [
{ "url": "https://example.com/a.docx", "filename": "a.docx", "format": "pdf" },
{ "url": "https://example.com/b.xlsx", "filename": "b.xlsx", "format": "pdf" }
] }'
curl 'https://maxscanner.app/api/v1/jobs/batch/$BATCH_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"ワークフローの一括実行
まずファイルをインポートまたはアップロードし (インポートごとに documentId が返されます)、1 回の呼び出しでドキュメントごとに実行を開始します。実行はキューに入り、共有ワーカーで順に処理されるため、100 個の Office ファイルには秒単位ではなく分単位の時間がかかります。15–30 秒ごとに GET /api/v1/automations/{automationId}/runs/ をポーリングし、ステータスごとの件数を確認してください。
import os, requests
KEY = os.environ["MAXSCANNER_API_KEY"]
H = {"Authorization": f"Bearer {KEY}"}
BASE = "https://maxscanner.app/api/v1"
doc_ids = [requests.post(f"{BASE}/documents/import/", headers=H, json={"url": u, "filename": u.rsplit("/", 1)[-1]}, timeout=60).json()["documentId"] for u in urls]
r = requests.post(f"{BASE}/automations/{automation_id}/runs/", headers={**H, "Idempotency-Key": "invoices-2026-11"},
json={"mode": "each", "inputs": [{"kind": "document", "documentId": d} for d in doc_ids]}, timeout=60)
print(r.status_code, r.json().get("notStarted"))安全に再試行する
- 同じ Idempotency-Key で一括実行の呼び出しを繰り返すと、既存の実行はスキップされ (replayedCount)、足りない実行だけが開始されます
- notStarted がある場合はプランの上限で呼び出しが止まっています。クレジットを追加するかリセットを待ち、同じリクエストを繰り返してください
- 失敗した実行は他に影響しません。そのドキュメントについて新しい Idempotency-Key で新しい実行を開始してください
- 同時に処理中の実行は数百件までにし、counts.completed が増えてから次の百件を送ってください
よくある質問
キューに入れられる実行数に上限はありますか?
1 回の呼び出しで開始できる実行は最大 100 件です。キュー自体の上限はありませんが、実行はワーカーを他の顧客と共有するため、非常に大量の処理は完了まで時間がかかります。数百件ずつに分けて送ってください。
すべての結果を 1 つの ZIP で受け取れますか?
API ではまだできません。各出力をそれぞれのドキュメントからダウンロードするか、ウェブサイトの ZIP ツールを使ってください。