본문으로 건너뛰기

다음 도구 찾기

문서/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건의 요청 중 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 도구를 사용하십시오.

관련 가이드