Zum Hauptinhalt springen

Nächstes Tool finden

Dokumentation/API/Massenverarbeitung von Dokumenten mit der API
API

Massenverarbeitung von Dokumenten mit der API

Konvertieren, komprimieren oder per OCR erfassen Sie Hunderte Dateien: Wählen Sie zwischen Batch-Jobs und Massenläufen von Workflows, bleiben Sie in den Tariflimits und wiederholen Sie nur, was fehlgeschlagen ist.

Kurze Antwort

Für eine einstufige Konvertierung von bis zu 20 Dateien pro Aufruf verwenden Sie POST /api/v1/jobs/batch/ mit einem "jobs"-Array und verfolgen sie mit GET /api/v1/jobs/batch/{batchId}/. Für mehrere Schritte pro Datei erstellen Sie einen Workflow und starten ihn mit "mode": "each" für bis zu 100 Dokumente pro Aufruf. Geben Sie jedem Aufruf einen stabilen Idempotency-Key, damit eine Wiederholung nur das Fehlende startet.

Das passende Werkzeug wählen

Im Free-Tarif zählt jeder Verarbeitungsaufruf als eine der 10 täglichen Anfragen; Massenverarbeitung erfordert daher einen bezahlten Tarif oder gekaufte Credits.

AufgabeVerwendenPro Aufruf
Dieselbe Konvertierung für viele Dateien (DOCX → PDF)POST /jobs/batch/1–20 Dateien, 2 Credits pro Batch
Mehrere Schritte pro Datei (konvertieren, komprimieren, drehen)Workflow + Läufe mit mode "each"1–100 Dokumente, 3 Credits pro Lauf
Viele Dateien zu einer zusammenführen (Merge)Workflow + Läufe mit mode "together"bis zu 100 Dokumente in einem Lauf
Video und AudioEin /media/process/-Job pro Datei1 Datei, 1 Credit

Batch-Konvertierungen

Jedes Element nimmt dieselben Felder wie POST /jobs/: url oder sourceKey, filename, format und optional inputFormat. Der Batch wird als Ganzes geprüft (die Antwort nennt den Index des ersten fehlerhaften Elements), und jedes Element wird zu einem eigenen Job.

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"

Massenläufe von Workflows

Importieren oder laden Sie zuerst die Dateien hoch (jeder Import liefert eine documentId) und starten Sie dann in einem Aufruf einen Lauf pro Dokument. Die Läufe werden eingereiht und nacheinander auf gemeinsam genutzten Workern verarbeitet, daher dauern 100 Office-Dateien Minuten, nicht Sekunden; fragen Sie GET /api/v1/automations/{automationId}/runs/ alle 15–30 Sekunden ab und lesen Sie die Anzahl pro Status.

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"))

Sicher wiederholen

  • Wiederholen Sie einen Massenlauf-Aufruf mit demselben Idempotency-Key: Bereits vorhandene Läufe werden übersprungen (replayedCount), und nur fehlende starten
  • Ist notStarted vorhanden, hat das Tariflimit den Aufruf gestoppt; fügen Sie Credits hinzu oder warten Sie auf das Zurücksetzen und wiederholen Sie dieselbe Anfrage
  • Ein fehlgeschlagener Lauf beeinflusst die anderen nicht; starten Sie für dieses Dokument einen neuen Lauf mit einem neuen Idempotency-Key
  • Halten Sie höchstens einige Hundert Läufe gleichzeitig offen; warten Sie, bis counts.completed steigt, bevor Sie die nächsten Hundert senden

Häufige Fragen

Gibt es ein Limit für Läufe in der Warteschlange?

Jeder Aufruf startet höchstens 100 Läufe. Ein eigenes Warteschlangenlimit gibt es nicht, aber die Läufe teilen sich Worker mit anderen Kunden, sodass sehr große Rückstände langsamer fertig werden. Senden Sie die Arbeit in Paketen von einigen Hundert.

Kann ich alle Ergebnisse als ein ZIP erhalten?

Über die API noch nicht. Laden Sie jedes Ergebnis aus seinem Dokument herunter oder nutzen Sie die ZIP-Werkzeuge der Website.

Verwandte Anleitungen