API로 문서 일괄 처리
수백 개 파일을 변환, 압축 또는 OCR 처리하십시오. 배치 작업과 워크플로 일괄 실행 중에서 선택하고, 플랜 한도 안에서 실패한 것만 다시 시도합니다.
핵심 답변
호출당 최대 20개 파일을 한 단계로 변환하려면 "jobs" 배열과 함께 POST /api/v1/jobs/batch/를 사용하고 GET /api/v1/jobs/batch/{batchId}/로 추적하십시오. 파일마다 여러 단계가 필요하면 워크플로를 만들고 "mode": "each"로 호출당 최대 100개 문서에 실행하십시오. 호출마다 고정된 Idempotency-Key를 주면 재시도할 때 빠진 것만 시작됩니다.
알맞은 방법 고르기
Free 플랜에서는 처리 호출마다 하루 10건의 요청 중 1건으로 계산되므로, 일괄 작업에는 유료 플랜이나 구매한 크레딧이 필요합니다.
| 작업 | 사용할 것 | 호출당 |
|---|---|---|
| 많은 파일에 같은 변환(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가 반환됨), 호출 한 번으로 문서마다 실행을 하나씩 시작하십시오. 실행은 대기열에 들어가 공유 워커에서 순서대로 처리되므로 Office 파일 100개는 몇 초가 아니라 몇 분이 걸립니다. 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개입니다. 대기열 자체의 한도는 없지만 실행은 다른 고객과 워커를 공유하므로 아주 많은 작업은 더 늦게 끝납니다. 작업을 수백 개 단위로 나눠 보내십시오.
모든 결과를 ZIP 하나로 받을 수 있나요?
API에서는 아직 지원하지 않습니다. 각 출력을 해당 문서에서 다운로드하거나 웹사이트의 ZIP 도구를 사용하십시오.