工作流 API:创建并运行多步骤工作流
一次 API 调用即可创建多步骤文档工作流,在一个或数百个文件上运行,跟踪每次运行并下载结果。
简要回答
发送 POST https://maxscanner.app/api/v1/workflows/ 并附上步骤列表,例如 [{"step":"word-to-pdf"},{"step":"compress-pdf"}]。MaxScanner 会检查该链能否在云端运行,保存后连接到你的 API 密钥,并返回 automationId。用 POST /api/v1/automations/{automationId}/runs/ 和 Idempotency-Key 启动它,通过 GET /api/v1/automation-runs/{runId}/ 跟踪进度,再从 /api/v1/documents/{documentId}/download/ 下载每个输出。
快速入门
- 1用 GET /api/v1/workflow-steps/ 查看步骤、每一步接受和输出的格式以及设置。
- 2发送 POST /api/v1/workflows/,附上名称和 1–10 个步骤。保存响应中的 workflow.automationId。
- 3导入或上传文件,然后附上它们的 documentId 和 Idempotency-Key 发送 POST /api/v1/automations/{automationId}/runs/。
- 4轮询 GET /api/v1/automation-runs/{runId}/ 直到状态为 completed,或列出该自动化的所有运行。
- 5用 GET /api/v1/documents/{documentId}/download/ 下载 run.outputs 中的每一项。
为什么用工作流而不是分别调用
工作流把整条链留在 MaxScanner 这边:每一步的输出直接进入下一步,不必返回你的服务器;每次运行都会重试并记录;结果保存到“我的文档”。你可以在 控制台 → 工作流 中打开通过 API 创建的工作流进行检查;以后要更改链条,只需新建工作流并替换 automation id,无需重新部署代码。
可用的步骤
这些步骤在 MaxScanner 的云端 Worker 上运行,因此由它们组成的工作流无需浏览器即可运行。
| step | 输入 → 输出 | 设置 |
|---|---|---|
| word-to-pdf, excel-to-pdf, pptx-to-pdf, ppt-to-pdf, rtf-to-pdf | Office 文件 → PDF | — |
| merge-pdf | 2 个或更多 PDF → 一个 PDF(仅限第一步) | — |
| compress-pdf | PDF → 更小的 PDF | — |
| rotate-pdf | PDF → PDF | degrees:90、180 或 270 |
| extract-pages | PDF → PDF | pages: "1,3-5"(从 1 开始计数) |
| image-transform | JPG、PNG 或 WebP → JPG、PNG、WebP 或 AVIF | format, quality, maxWidth, maxHeight, width, height, targetBytes |
| image-ocr | JPG、PNG 或 WebP → 文本(英文) | — |
创建工作流
步骤按你列出的顺序运行,每一步都必须接受上一步的输出;不匹配时返回 422 workflow_not_runnable 并说明原因。请发送 Idempotency-Key,这样重试的请求会返回同一个工作流。创建工作流消耗一次请求(付费套餐为一积分),每个密钥最多可拥有 25 个启用的工作流。
curl -X POST 'https://maxscanner.app/api/v1/workflows/' \
-H "Authorization: Bearer $MAXSCANNER_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: create-contract-flow-v1' \
-d '{
"name": "Contracts to small PDF",
"steps": [
{ "step": "word-to-pdf" },
{ "step": "compress-pdf" }
]
}'在一个或多个文件上运行
输入是账户中已有的文档:API 导入、通过 /extension/upload/complete/ 完成的上传、之前的输出以及 Android 扫描件。每次运行都需要 Idempotency-Key;重复使用同一密钥绝不会启动第二次运行。当文件应放在同一次运行中时(例如 merge-pdf 需要的多个 PDF),使用 "mode": "together"(默认)。使用 "mode": "each" 为每个文件各启动一次运行,一次调用最多 100 个文件。付费套餐每次运行消耗 3 积分,Free 套餐消耗一次请求;如果中途达到套餐上限,响应会列出未启动的文件数量。
const res = await fetch(`https://maxscanner.app/api/v1/automations/${automationId}/runs/`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.MAXSCANNER_API_KEY}`,
'Content-Type': 'application/json',
'Idempotency-Key': 'contracts-2026-11-11',
},
body: JSON.stringify({
mode: 'each', // one run per document
inputs: documentIds.map((documentId) => ({ kind: 'document', documentId })),
}),
});
const { runs, replayedCount, notStarted } = await res.json();跟踪运行并下载结果
GET /api/v1/automation-runs/{runId}/ 返回状态(reserved、executing、suspended、completed、failed 或 cancelled),完成后还会返回 outputs 列表,包含每个已保存文件的 documentId、文件名、类型和大小。GET /api/v1/automations/{automationId}/runs/ 列出最近 100 次运行及各状态的数量,是跟踪批量调用最快的方法。读取状态免费。
curl 'https://maxscanner.app/api/v1/automation-runs/$RUN_ID/' -H "Authorization: Bearer $MAXSCANNER_API_KEY"
# then, for each output:
curl "https://maxscanner.app/api/v1/documents/$DOCUMENT_ID/download/" -H "Authorization: Bearer $MAXSCANNER_API_KEY"管理工作流
在可视化编辑器中创建的工作流也能通过 API 运行:打开 控制台 → 工作流 → 版本 → 从 API 运行 并选择密钥。编辑器还提供需要人工参与的步骤,例如签名、等待和审批;这些步骤不会出现在通过 API 创建的工作流中。
- GET /api/v1/workflows/ 列出此密钥可以启动的所有工作流及其步骤
- GET /api/v1/workflows/{workflowId}/ 返回其中一个
- DELETE /api/v1/workflows/{workflowId}/ 断开它与密钥的连接;通过 API 创建的工作流会被归档,已启动的运行会继续完成
- 要更改步骤,请新建工作流并在代码中改用它的 automationId
常见问题
一定要使用可视化编辑器吗?
不需要。POST /api/v1/workflows/ 会根据 JSON 创建工作流。编辑器是可选的,用于检查工作流或使用 API 中没有的步骤。
"together" 和 "each" 有什么区别?
"together" 启动一次接收所有输入的运行,merge-pdf 需要这种方式。"each" 为每个输入各启动一次运行,因此一个有问题的文件不会影响其他文件,每个文件完成后就会返回结果。
密钥需要什么权限?
创建和运行工作流需要“运行已保存的工作流”(workflows:run 和 workflows:read),导入输入文件需要“保存文档”,下载输出需要“读取文档”。
工作流运行结束时会发送 webhook 吗?
暂时不会。请轮询运行或运行列表;webhook 会针对直接通过 /jobs、/pipeline、/pdf-job 和 /media/process 启动的处理任务发送。