跳至主要內容

尋找下一個工具

說明文件/API/以 API 批次處理文件
API

以 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 工具。

相關指南