myocr.app API-Dokumentation

Überblick

Die myocr.app-API wandelt Dokumentdateien (PDF, JPG, PNG) in strukturiertes Excel, CSV, Text oder JSON um. Sie senden eine Datei und einen Modellnamen; wir führen OCR und Layoutanalyse durch und liefern ein sauberes Ergebnis zurück.

Jede Anfrage wird mit einem API-Schlüssel authentifiziert, der im X-API-Key-Header übergeben wird. Antworten verwenden eine vorhersehbare JSON-Struktur, und jeder Aufruf liefert eine request_id zurück, die Sie für Support und Debugging nutzen können.

Verwenden Sie den synchronen Endpunkt für kleine Dateien, die Sie sofort beantwortet brauchen, und den asynchronen Jobs-Endpunkt (mit optionalem Webhook) für größere Dateien oder hohes Volumen.

Authentifizierung

Authentifizieren Sie jede Anfrage mit dem X-API-Key-Header. Erstellen und verwalten Sie Schlüssel in Ihrem Dashboard unter /account/api. Zur Ausstellung eines Schlüssels ist eine verifizierte Zahlungskarte erforderlich (Missbrauchsschutz).

Es gibt zwei Schlüsseltypen: Test-Schlüssel (Präfix sk_test_) laufen gegen dieselbe Pipeline, ohne wo zutreffend kostenpflichtiges Kontingent zu verbrauchen, und Live-Schlüssel (Präfix sk_live_) für die Produktion. Halten Sie Schlüssel geheim und serverseitig — betten Sie sie niemals in clientseitigen Code ein.

Die Endpunkte zur Schlüsselverwaltung (/v1/keys) nutzen Ihre angemeldete Web-Sitzung, nicht den API-Schlüssel selbst.

curl https://api.myocr.app/v1/status \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx"

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
print(client.status())

const res = await fetch("https://api.myocr.app/v1/status", {
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" }
});
console.log(await res.json());

Schnellstart

Wandeln Sie Ihr erstes Dokument in unter einer Minute um. Holen Sie sich einen Schlüssel aus dem Dashboard und senden Sie dann eine Multipart-Anfrage mit Ihrer Datei und dem gewünschten Modell.

Das folgende Beispiel wandelt ein beliebiges PDF oder Bild mit Tabellen in eine .xlsx-Tabelle um und speichert sie als out.xlsx.

curl -X POST https://api.myocr.app/v1/convert \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@invoice.pdf" \
  -F "model=tables" \
  -o out.xlsx

from myocr_client import MyOCRClient

client = MyOCRClient(api_key="sk_live_xxxxxxxxxxxx")
result = client.convert("invoice.pdf", model="tables")
result.save("out.xlsx")

import fs from "node:fs";

const form = new FormData();
form.append("file", new Blob([fs.readFileSync("invoice.pdf")]), "invoice.pdf");
form.append("model", "tables");

const res = await fetch("https://api.myocr.app/v1/convert", {
  method: "POST",
  headers: { "X-API-Key": "sk_live_xxxxxxxxxxxx" },
  body: form,
});
fs.writeFileSync("out.xlsx", Buffer.from(await res.arrayBuffer()));

Synchrone Umwandlung

POST /v1/convert akzeptiert eine einzelne Datei (max. 5 MB, max. 10 Seiten) und gibt die Ergebnisdatei direkt im Antworttext zurück — standardmäßig ein .xlsx oder Text/JSON/CSV, wenn Sie den output-Parameter setzen.

Dieser Endpunkt eignet sich am besten, wenn Sie die Antwort sofort brauchen. Für größere Dateien oder Batches verwenden Sie stattdessen asynchrone Jobs.

Parameter

Asynchrone Jobs

Für Dateien bis 50 MB (und PDFs bis 500 Seiten) oder höheren Durchsatz erstellen Sie einen Job mit POST /v1/jobs. Der Aufruf liefert sofort eine request_id zurück; die Datei wird im Hintergrund verarbeitet. PDFs über dem Seitenlimit werden vorab mit TOO_MANY_PAGES abgelehnt — teilen Sie das Dokument auf.

Fragen Sie GET /v1/jobs/{request_id} für den Status ab (pending → processing → done/failed) und laden Sie das Ergebnis dann von GET /v1/jobs/{request_id}/result herunter. Geben Sie eine webhook_url an, um automatisch benachrichtigt zu werden, wenn der Job fertig ist, statt zu pollen.

# 1. create the job
curl -X POST https://api.myocr.app/v1/jobs \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "file=@statement.pdf" -F "model=bank_statement"
# → {"success": true, "data": {"request_id": "abcd1234"}}

# 2. poll status, then download the result
curl https://api.myocr.app/v1/jobs/abcd1234 -H "X-API-Key: sk_live_xxxxxxxxxxxx"
curl https://api.myocr.app/v1/jobs/abcd1234/result -H "X-API-Key: sk_live_xxxxxxxxxxxx" -o out.xlsx

job = client.create_job("statement.pdf", model="bank_statement")
job.wait()                     # polls with backoff until done
job.result().save("out.xlsx")

Batch-Umwandlung

POST /v1/batch akzeptiert 1–20 Dateien in einer einzigen Multipart-Anfrage, alle mit demselben Modell verarbeitet. Jede Datei wird unabhängig gemeldet; Fehler pro Datei werden in einem errors-Array zurückgegeben, ohne den gesamten Batch fehlschlagen zu lassen.

curl -X POST https://api.myocr.app/v1/batch \
  -H "X-API-Key: sk_live_xxxxxxxxxxxx" \
  -F "files=@a.pdf" -F "files=@b.pdf" -F "files=@c.jpg" \
  -F "model=invoice"

Modelle

Übergeben Sie einen dieser model-Werte. tables und text laufen auf unserer OCR-Engine; die spezialisierten Modelle liefern domänenspezifische Felder zurück.

Ausgabeformate

Setzen Sie den output-Parameter, um das Antwortformat zu wählen: xlsx (Standard, strukturierte Tabelle), txt (Klartext), json (extrahierte Felder als JSON) oder csv. Das Modell text liefert immer txt zurück.

Für model=bank_statement können Sie output auch auf csv_quickbooks (4-spaltige CSV für den Bankimport), csv_xero (Xero-Importvorlage) oder ofx (Standard-OFX-Datei für die meisten Buchhaltungsprogramme) setzen. Mit output=json enthält die Antwort zusätzlich ein reconciliation-Objekt: Anfangs-/Endsaldo, Summe der Gut- und Lastschriften, die berechnete Differenz und ok=true, wenn die extrahierten Transaktionen mit den Salden des Auszugs übereinstimmen.

Antworten & Header

JSON-Antworten folgen einer festen Struktur: einem success-Boolean, einem data-Objekt (oder einem error-Objekt) und einer request_id. Datei-Antworten geben die Binärdaten direkt mit dem passenden Content-Type zurück.

Jede Antwort enthält den Header X-MyOCR-Request-Id. Datei-Antworten enthalten zusätzlich X-MyOCR-Pages-Used (abgerechnete Seiten) und X-MyOCR-Model (das verwendete Modell).

{
  "success": true,
  "data": { "request_id": "abcd1234" },
  "request_id": "abcd1234"
}

Fehler

Fehler geben success: false mit einem error.code und einer menschenlesbaren error.message sowie der request_id zurück. Nutzen Sie den code (stabil) für Verzweigungen, die message (kann sich ändern) für Menschen.

Rate-Limits & Kontingent

Rate-Limits werden pro API-Schlüssel (nicht pro IP) durchgesetzt, sodass Clients hinter einem gemeinsamen Proxy sich kein Limit teilen: /v1/convert 60 Anf./Min., /v1/jobs 120 Anf./Min., /v1/batch 30 Anf./Min.

Abrechnung pro Seite, nicht pro Aufruf. Pläne: Free 10 Seiten gesamt (einmalig, Karte erforderlich), Starter 29 €/Monat (2.500), Pro 99 €/Monat (10.000), Scale 190 €/Monat (20.000). Der Dienst wird nie unterbrochen: Sind die Seiten des Monats aufgebraucht, benachrichtigen wir Sie per E-Mail und buchen ein Zusatzpaket zum Seitenpreis Ihres Plans ab — Starter 500 zu 0,0116 €, Pro 2.000 zu 0,0099 €, Scale 4.000 zu 0,0095 € — bis zu einem monatlichen Auto-Aufladelimit, das Sie festlegen (und deaktivieren können). Ist das Limit erreicht, gibt die API 402 mit einer upgrade_url zurück. Prüfen Sie die Nutzung mit GET /v1/usage.

Webhooks

Wenn Sie /v1/jobs eine webhook_url übergeben, senden wir per POST eine JSON-Payload an diese URL, sobald der Job done oder failed erreicht. Zustellungen werden bei Fehlern mit Backoff wiederholt.

Jede Zustellung ist signiert: Überprüfen Sie den Signatur-Header mit Ihrem Webhook-Signing-Secret (im Dashboard angezeigt), um zu bestätigen, dass die Anfrage wirklich von myocr.app stammt. Das Python-SDK enthält einen verify_webhook_signature-Helfer.

SDKs

Das offizielle Python-SDK (myocr-client) kapselt jeden Endpunkt mit typisierten Methoden und Ausnahmen, automatischem Job.wait()-Polling mit Backoff und Webhook-Signaturprüfung.

Lieber rohes HTTP? Jeder HTTP-Client funktioniert — siehe die cURL- und Node-Beispiele in diesem Leitfaden und die vollständige interaktive Referenz.

pip install myocr-client

OpenAPI-Spezifikation