OCR API einrichten: Bildupload, Erkennung und Felder (2026)

Auf den ersten Blick besteht die OCR-API-Anbindung nur aus „Bild senden, Text erhalten“. Ob ein Projekt produktionsreif wird, entscheiden jedoch andere Punkte: Bildformat und -größe, synchron oder asynchron, Definition von Koordinaten und Feldern sowie ein Fallback bei instabilen Ergebnissen. In der Demo fallen diese Probleme kaum auf; echte Belege und Scans bringen sie ans Licht.

Dieser Artikel beschreibt am Beispiel OpenAI-kompatibler Schnittstellen und gängiger OCR-Dienste die Kette vom Upload über die Erkennung bis zur strukturierten Ausgabe, ergänzt um Beispiele, Vorverarbeitung, Fehlerdiagnose und eine Migrationsprüfung.

Hinweis: OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud, Baidu und weitere genannte Marken sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeit zu den Anbietern. Schnittstellen, Modelle, Bildlimits und Abrechnungsregeln richten sich nach der offiziellen Dokumentation und den Seiten auf dieser Website.

1. Schnittstelle und Authentifizierung

Für OCR gibt es zwei verbreitete Formen; klären Sie zuerst, welche Sie nutzen:

Spezialisierte OCR-Schnittstelle: eigener Erkennungsendpunkt, Eingabe Bild oder PDF, Ausgabe Textblöcke, Koordinaten und Konfidenz; teilweise mit Vorlagen für Belege, Ausweise und Tabellen.
Multimodale Dialogschnittstelle: läuft über /v1/chat/completions, das Bild wird in die Nachricht gelegt, ein Vision-Modell gibt Text oder JSON aus. Geeignet für komplexe Layouts, Handschrift und verstehendes Arbeiten.

Die Authentifizierung einer OpenAI-kompatiblen Schnittstelle sieht typischerweise so aus:

POST https://ai.zhongshangqihang.com/v1/chat/completions
Authorization: Bearer sk-IhrSchluessel
Content-Type: application/json

Die Base URL endet bei /v1; hängen Sie den Pfad nicht selbst an und übergeben Sie ihn dann dem SDK, sonst entsteht leicht ein 404. Manche Cloud-Anbieter nutzen Access Key plus Secret Key mit Signatur oder tauschen zuerst ein access_token; die Bearer-Schreibweise lässt sich dort nicht direkt übernehmen. Maßgeblich ist die offizielle Dokumentation.

2. Bildübertragung: URL, Base64 und Datei-Upload

Drei Wege sind üblich; die Wahl hängt davon ab, wo das Bild liegt und was die Schnittstelle unterstützt:

Methode	Geeignet für	Beachten
Öffentliche URL	Bild liegt bereits im Objektspeicher oder CDN	Server muss erreichbar sein; Link lange genug gültig; keine sensiblen Bilder öffentlich machen
Base64-Data-URL	Lokale Dateien, Intranetbilder, temporäre Tests	Etwa ein Drittel größer; falsches Präfix oder falsche Kodierung ergibt 400
Multipart-Datei-Upload	Spezialisierte OCR-Schnittstelle eines Anbieters	Feldname, Kodierung und Größe laut Dokumentation

Das Base64-Format lautet meist data:image/jpeg;base64,<kodierter Inhalt>. Häufige Fehler: Präfix fehlt, Zeilenumbrüche geraten in die Zeichenkette, oder URL-sichere Kodierung wird nicht zurückgewandelt.

Bei den Formaten sind JPEG, PNG und WebP am verbreitetsten; GIF, TIFF, BMP und PDF hängen von der Schnittstelle ab. Einzelbilder liegen häufig zwischen wenigen MB und 20 MB; Überschreitungen liefern meist 413 oder 400. Höhere Auflösung ist nicht automatisch besser, große Bilder werden serverseitig oft skaliert. Für Scans sind 200 bis 300 DPI üblich, bei Handyfotos eine lange Kante ab 1600 bis 2400 Pixeln; validieren Sie mit echten Beispielen.

3. Synchron oder asynchron

Synchrone Schnittstellen passen zu Einzelbildern und interaktiven Szenarien: Anfrage senden, auf Ergebnis warten. Das Risiko ist der Timeout, besonders bei großen Bildern, mehrseitigen PDFs oder serverseitiger Warteschlange; die Verbindung kann vorzeitig getrennt werden.

Asynchrone Schnittstellen passen zu Stapeln und mehrseitigen Dokumenten. Der Ablauf ist meist:

Bild oder Datei einreichen und eine Aufgaben-ID erhalten.
Status abfragen oder auf einen Callback warten.
Nach Abschluss das Ergebnis herunterladen oder abfragen.
Ergebnisse haben oft eine Aufbewahrungsfrist; rechtzeitig in die Datenbank übernehmen.

Nicht nur auf die Einfachheit der Schnittstelle achten. Kann eine Anfrage Dutzende Sekunden dauern, blockiert synchron Verbindungen und Threads, und Retries erhöhen den Druck. Asynchron müssen Idempotenz, Doppeleinreichung, Polling-Backoff und Ergebnisablauf behandelt werden. In der Produktion empfiehlt sich eine Tabelle für Aufgaben-IDs mit Status und Ergebnisort.

4. curl-Beispiel

Das folgende Beispiel erkennt ein Bild über eine OpenAI-kompatible Schnittstelle. Der Modellname richtet sich nach den Modellpreisen; wählen Sie ein Modell mit Bild eingabe:

export ZSQH_API_KEY="sk-IhrSchluessel"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "Erkenne den Text im Bild, gib ihn zeilenweise aus, ohne Erklaerung."},
          {"type": "image_url", "image_url": {"url": "https://example.com/invoice.jpg"}}
        ]
      }
    ]
  }'

Bei 401 zuerst Key und Header prüfen; bei 400, ob die Bild-URL erreichbar und das Format unterstützt wird; bei 404, ob Base URL und Pfad doppelt zusammengesetzt sind.

5. Python-Aufruf und strukturierte Ausgabe

Echte Projekte brauchen selten reinen Text, sondern Felder. Lassen Sie das Modell nach einem Schema JSON ausgeben und validieren Sie lokal:

import base64
import json
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

with open("invoice.jpg", "rb") as f:
    image_b64 = base64.b64encode(f.read()).decode()

schema_hint = '{"invoice_no": "", "date": "", "amount": "", "seller": ""}'
resp = client.chat.completions.create(
    model=os.environ["OCR_MODEL"],  # Modellname mit Bildunterstuetzung aus der Preisseite
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": f"Erkenne den Beleg und gib ihn nach diesem JSON aus, fehlende Felder als null: {schema_hint}"},
            {"type": "image_url", "image_url": {"url": f"data:image/jpeg;base64,{image_b64}"}},
        ],
    }],
)
data = json.loads(resp.choices[0].message.content)
print(data)

Der Code läuft, ist aber noch nicht produktionsreif. Die Modellausgabe kann Codeblöcke, Erklärtext oder zusätzliche Felder enthalten; json.loads scheitert dann direkt. In der Praxis: bevorzugt den JSON-Modus oder strukturierte Ausgabe der Plattform nutzen; vor dem Parsen Codeblock-Marker entfernen; Typen mit Pydantic oder jsonschema prüfen; bei Fehlern die Fehlermeldung einmal an das Modell zurückgeben und erneut versuchen, danach an einen Menschen übergeben. Beträge, Daten und Steuernummern zusätzlich kreuzprüfen.

6. Koordinaten, Tabellen und strukturierte Felder

Klassische OCR liefert Inhalt, Koordinaten und Konfidenz von Textblöcken; multimodale Modelle geben nach Prompt aus, Koordinaten sind nicht zwingend verlässlich. Klären Sie zuerst das Koordinatenformat: vierteiliges Polygon, [x1, y1, x2, y2] oder [x, y, w, h]; Einheit Pixel oder auf 0 bis 1000 normalisiert; Ursprung oben links? Nach Rotation und Zuschnitt müssen Koordinaten umgerechnet werden.

Wurde das Bild vor der Erkennung skaliert, müssen Koordinaten proportional auf das Original zurückgerechnet werden, sonst verschieben sich Hervorhebungen. Bei Tabellen Zeilen, Spalten, verbundene Zellen und Leerwertregeln festlegen; für komplexe Tabellen eine spezialisierte Tabellenerkennung nutzen und das Ergebnis vom Modell aufbereiten lassen.

Strukturierte Felder brauchen vorab ein Schema: Feldname, Typ, Pflichtfeld, Leerwertdarstellung, Normalisierung von Datum und Betrag. Bei Belegen kommen Währung, Steuerbetrag und die Abstimmung von Netto, Steuer und Brutto hinzu. Konfidenz lässt sich zur Steuerung nutzen: Felder mit niedriger Konfidenz gehen in die manuelle Prüfung statt direkt verworfen zu werden.

7. Vorverarbeitung: stabilere Erkennung

Viele Erkennungsfehler entstehen vor der Anfrage. Arbeiten Sie in dieser Reihenfolge:

EXIF-Ausrichtung lesen und drehen, damit Bilder nicht quer liegen.
Auf den Dokumentbereich zuschneiden, große Hintergründe und fremde Objekte entfernen.
Leichte Schräglagen korrigieren; bei deutlicher Neigung Kanten erkennen.
Auflösung steuern: Scans 200 bis 300 DPI, Handyfotos ab 1600 bis 2400 Pixeln lange Kante.
Verblasste oder kontrastarme Dokumente in Graustufen wandeln und den Kontrast maßvoll erhöhen.
Mehrseitige PDFs oder lange Screenshots seitenweise teilen, an den Schnittstellen etwas Überlappung lassen.

Unscharfe Bilder lassen sich durch Schärfen nicht retten; niedrig aufgelöster Text gewinnt beim Vergrößern keine Details. Ziel der Vorverarbeitung ist weniger Störung, nicht ein schöneres Bild. Vergleichen Sie nach jeder Parameteränderung die Feldgenauigkeit mit derselben echten Stichprobe.

8. Häufige Fehler und Diagnose

Fehler	Häufige Ursache	Behandlung
`401`	Key falsch, abgelaufen, Header falsch geschrieben	Bearer-Format, Leerzeichen und Umgebungsvariablen prüfen
`403 Forbidden`	Kein Modellrecht, Regionssperre, Unterkonto ohne Recht	Modellfreigabe und Kontorichtlinie prüfen
`400` Bildfehler	Base64-Präfix falsch, Datei beschädigt, Format nicht unterstützt	Dateikopf prüfen, JPEG oder PNG verwenden
`413 Payload Too Large`	Bild oder Request-Body zu groß	Komprimieren, skalieren, zuschneiden oder Datei-Upload/Async nutzen
`429 Too Many Requests`	Frequenz oder Parallelität überschritten	Parallelität senken, exponentielles Backoff
Timeout oder `502`	Großes Bild, langes Dokument, serverseitige Warteschlange	Asynchrone Aufgabe oder kleinere Anfrage
Leeres oder falsch sortiertes Ergebnis	Falsche Ausrichtung, niedrige Auflösung, komplexes Layout	Drehen, Schärfe erhöhen, spaltenweise zuschneiden

Erfassen Sie bei der Diagnose Request-ID, Modellname, Bildgröße und Dauer. Viele Fälle von „schlechter Modellqualität“ sind in Wahrheit ein falsch übertragenes Bild, nicht umgerechnete Koordinaten oder ein inkonsistentes Schema.

9. Migration und Go-live-Prüfung

Ein Wechsel von einem OCR-Dienst zu einem anderen bedeutet meist mehr als base_url und api_key zu ändern. Vor dem Go-live prüfen:

Ist die neue Schnittstelle spezialisiertes OCR oder dialogfähige Vision, und ist der Request-Aufbau kompatibel?
Welche Bildformate, Einzelgrößen, Seitenzahlen und Auflösungslimits gelten?
Synchron oder asynchron, wie lange werden Ergebnisse aufbewahrt, braucht der Callback eine öffentliche Adresse?
Sind Koordinatenformat, Einheit und Ursprung identisch mit dem alten Dienst?
Decken Feldschema, Sprachunterstützung und Belegtypen das bestehende Geschäft ab?
Gibt es einen Canary-Pfad, um zunächst einen Teil des Traffics zu vergleichen?
Gibt es einen Rückweg, und bleiben alter Key und alte Schnittstelle eine Zeit lang erhalten?

Kapseln Sie OCR in einen eigenen Client, etwa recognize(image, schema) -> Result, und bündeln Sie Anbieterunterschiede in einer Adapterschicht. Dann muss beim Dienstwechsel kein Geschäftscode neu geschrieben werden. Modelle, Limits und Preise entnehmen Sie den Modellpreisen.

Häufige Fragen

Unterstützt die OCR-API PDF?

Das hängt von der Schnittstelle ab. Spezialisierte OCR-Dienste unterstützen PDF meist, mehrseitige Dokumente laufen oft asynchron. OpenAI-kompatible Dialogschnittstellen behandeln PDF in der Regel als Bild; Seiten müssen zuerst in Bilder zerlegt oder ein Datei-Endpunkt genutzt werden. Maßgeblich ist die Dokumentation.

Wie groß darf ein Bild sein?

Das ist unterschiedlich; üblich sind wenige MB bis 20 MB pro Bild, dazu Pixel- und Seitenlimits. Komprimieren und skalieren Sie vor dem Upload, um Timeouts und Übertragungskosten zu senken.

Warum ist die Reihenfolge des erkannten Textes durcheinander?

Häufig sind mehrspaltige Layouts, Tabellen und gemischte Bilder. Klassisches OCR sortiert nach Koordinaten, multimodale Modelle erzeugen in Lesereihenfolge; beide können irren. Schneiden Sie spaltenweise, fordern Sie Ausgabe nach Bereichen an oder nutzen Sie eine Schnittstelle mit Layoutanalyse.

Wie werden strukturierte Felder am stabilsten?

Zuerst ein Schema definieren, das Modell JSON ausgeben lassen und lokal Typ, Regex und Geschäftsregeln prüfen. Unterstützt die Plattform strukturierte Ausgabe, bevorzugen Sie diese; sonst einen Retry mit Fehlermeldung, danach manuelle Prüfung.

Was ändert sich beim Wechsel des OCR-Dienstes?

Neben Base URL und Key sind Request-Aufbau, synchron/asynchron, Bildlimits, Koordinatenformat, Schema und Ratenregeln zu prüfen. Erst mit Canary und echten Beispielen die Feldgenauigkeit vergleichen, dann vollständig umstellen.

Nächste Schritte

Für einen ersten lauffähigen Aufruf können Sie auf der Registrierungsseite einen Key mit niedrigem Limit anlegen und mit einem echten Beleg Upload, Erkennung und JSON-Ausgabe testen. Für die Auswahl prüfen Sie anschließend die Modellpreise und vergleichen die Feldgenauigkeit mit einer kleinen annotierten Bildmenge. Preise können sich ändern; maßgeblich sind die Angaben auf der Website.

Weiterlesen:

Hinweis: OpenAI, Google, Microsoft, Alibaba Cloud, Tencent Cloud und Baidu sind Marken ihrer jeweiligen Inhaber. Dieser Artikel dient der technischen Erläuterung; es besteht keine Zugehörigkeit zu den Anbietern. Schnittstellen, Modelle, Bildlimits und Abrechnungsregeln richten sich nach der offiziellen Dokumentation und den Seiten auf dieser Website.