跳到主要内容

查找下一个工具

文档/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 工具。

相关指南