以 API 批次處理文件
轉換、壓縮或 OCR 數百個檔案:在批次工作與工作流程批次執行之間選擇,控制在方案限額內,只重試失敗的部分。
簡要回答
若每次呼叫要對最多 20 個檔案做一步轉換,請使用附 "jobs" 陣列的 POST /api/v1/jobs/batch/,並以 GET /api/v1/jobs/batch/{batchId}/ 追蹤。若每個檔案需要多個步驟,請建立工作流程,並以 "mode": "each" 在每次呼叫最多 100 份文件上啟動它。為每次呼叫提供固定的 Idempotency-Key,讓重試只會啟動缺少的部分。
選擇合適的方式
在 Free 方案中,每次處理呼叫都計為每天 10 次要求中的一次,因此批次處理需要付費方案或購買的點數。
| 工作 | 使用 | 每次呼叫 |
|---|---|---|
| 對許多檔案做同一種轉換(DOCX → PDF) | POST /jobs/batch/ | 1–20 個檔案,每批 2 點 |
| 每個檔案多個步驟(轉換、壓縮、旋轉) | 工作流程 + 以 mode "each" 執行 | 1–100 份文件,每次執行 3 點 |
| 把許多檔案合成一個(合併) | 工作流程 + 以 mode "together" 執行 | 一次執行最多 100 份文件 |
| 影片和音訊 | 每個檔案一個 /media/process/ 工作 | 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),再於一次呼叫中為每份文件啟動一次執行。執行會排入佇列,並在共用 Worker 上依序處理,所以 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 增加後再傳送下一百個
常見問題
佇列中的執行數量有上限嗎?
每次呼叫最多啟動 100 次執行。佇列本身沒有另外的上限,但執行會與其他客戶共用 Worker,因此非常大量的積壓會完成得較慢。請以數百個為一批傳送。
能把所有結果打包成一個 ZIP 嗎?
API 目前尚不支援。請從各自的文件下載每個輸出,或使用網站上的 ZIP 工具。