Ein Key für eine OCR-Schnittstelle ist im Kern nur ein Identitätsnachweis. OCR hat jedoch Besonderheiten: Stapelverarbeitung von Belegen, Ausweisen und Scans, oft im Hintergrund. Geht ein Key verloren, verbrauchen andere Ihr Kontingent, und es können Kundendaten offenliegen. Viele Teams übernehmen außerdem Test-Keys unverändert in die Produktion.
Dieser Artikel folgt dem praktischen Ablauf: zuerst Key-Typen unterscheiden, dann Registrierung und Anlegen, danach Berechtigungen, Kontingente, Umgebungsvariablen, 401-Diagnose und die Wahl zwischen direktem Anbieter und Gateway, schließlich Rotation und Leak-Behandlung.
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, Berechtigungen und Abrechnungsregeln richten sich nach der offiziellen Dokumentation und den Seiten auf dieser Website.
1. Zuerst drei Authentifizierungsarten von OCR unterscheiden
Für OCR-Keys gibt es keinen einheitlichen Standard. Klären Sie vor der Anbindung, zu welcher Kategorie die Zielplattform gehört; sonst entsteht leicht „der Key stimmt, aber es kommt 401“:
- Bearer-Key: Am häufigsten bei OpenAI-kompatiblen Schnittstellen. Header:
Authorization: Bearer sk-...; Chat, Vision und OCR teilen meist dieselbe Authentifizierung. - Access Key + Secret Key: Bei manchen Cloud-Anbietern; Anfragen müssen laut Dokumentation signiert werden, das Secret darf nicht in Frontend oder Logs stehen.
- API Key + Secret Key gegen Token tauschen: Zuerst mit Key und Secret ein kurzfristiges
access_tokenholen, dann OCR damit aufrufen; nach Ablauf neu beziehen.
Auf derselben Plattform können OCR und Chat dasselbe Key-System nutzen. Ob ein Aufruf erlaubt ist, hängt von Kontorechten, Modellfreigabe und Guthaben ab, nicht vom Key-Typ. Prüfen Sie vor dem Anlegen, ob die Konsole Modell-Allowlists oder Unterkontenrechte unterstützt.
2. Registrierung und Key-Anlage
Am Beispiel des ZSQH AI Gateway:
- https://ai.zhongshangqihang.com öffnen oder direkt den Registrierungslink nutzen, mit E-Mail registrieren und bestätigen.
- Nach dem Login die Konsole öffnen und auf der Seite „API-Keys“ vorhandene Keys ansehen.
- Im „Wallet“ das Guthaben prüfen; in der Testphase zunächst einen kleinen Betrag aufladen.
- „Neuen Key anlegen“ wählen, Name, Obergrenze und Ablaufdatum eintragen; falls unterstützt, erlaubte Modelle einschränken.
- Den vollständigen Key sofort nach dem Speichern kopieren. Viele Plattformen zeigen ihn nur einmal; nach dem Schließen erscheint nur eine Maske.
- Mit einem Testbild eine Anfrage ausführen und im „Nutzungslog“ prüfen, ob Modell, Aufrufzahl und Kosten korrekt erfasst sind.
Nutzen Sie die native OCR-Schnittstelle eines Cloud-Anbieters, legen Sie möglichst ein Unterkonto an, das nur OCR-Rechte hat; verwenden Sie nicht den Access Key des Hauptkontos für Tests und Produktion.
3. Was beim Anlegen einzutragen ist: Name, Limit, Ablauf
Der Key-Name sollte auch ein halbes Jahr später die Abrechnung erklären. Bilden Sie „Zweck + Umgebung“, etwa ocr-prod-batch, ocr-staging, ocr-dev-zhang; vermeiden Sie Namen wie „Test1“.
Setzen Sie die Obergrenze zunächst niedrig und erhöhen Sie sie erst nach Feststellung des Verbrauchs einer echten Bildcharge. Das Ablaufdatum richtet sich nach dem Zweck: temporäre Skripte 7 oder 30 Tage, Produktions-Keys mit festem Rotationszyklus. Eine praktikable Zuordnung:
| Szenario | Key-Name | Limit | Speicherort | Rotation |
|---|---|---|---|---|
| Lokale Entwicklung | ocr-dev-Name |
Niedrigste Stufe | Lokale .env |
30 Tage |
| Testumgebung | ocr-staging |
Niedrig | CI/CD-Secret | 60 Tage |
| Produktion Batch | ocr-prod-batch |
Nach Budget | Secrets-Dienst | 90 Tage |
| Produktion Echtzeit | ocr-prod-realtime |
Nach Budget | Secrets-Dienst | 90 Tage |
Unterstützt die Plattform Modellrechte, nur die benötigten OCR- oder Vision-Modelle auswählen. Ist nur Projekttrennung möglich, mindestens Projekt und Kontingent trennen. Derselbe Key darf nicht gleichzeitig für lokale Fehlersuche, Testumgebung und Produktion verwendet werden.
4. Vier Prinzipien der Rechtegestaltung
- Ein Zweck, ein Key: Batch-Erkennung, Echtzeitschnittstelle und Verwaltungsskripte trennen. Bei Anomalien lässt sich der betroffene Key deaktivieren, ohne andere Dienste zu stören.
- Minimale Rechte: Nur OCR freischalten, wenn möglich; Unterkonto statt Hauptkonto-Key; Projektgrenzen statt kontoweiter Rechte.
- Kein Key im Frontend: Keys in Browser, App oder Mini-Programm lassen sich leicht extrahieren. Bildupload und OCR-Anfrage müssen über Ihren eigenen Backend laufen, das den Key hält.
- Produktion und Test trennen: Ein geleakter Test-Key beeinflusst keine Produktionsrechnung und verfälscht die Produktionsstatistik nicht.
OCR betrifft oft Rechnungen, Verträge und Ausweise. Key-Rechte kommen Datenzugriffsrechten nahe. Neben der Frage, wer aufrufen darf, ist zu klären, ob die Plattform Originalbilder speichert, wie lange und ob sie zum Training genutzt werden. In der Produktion IP-Allowlists aktivieren, sofern verfügbar, und Audit-Logs behalten.
5. Key in Umgebungsvariablen ablegen
Nicht im Code hartkodieren und nicht in Git committen. In Python etwa so:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["ZSQH_API_KEY"],
base_url="https://ai.zhongshangqihang.com/v1",
)
resp = client.chat.completions.create(
model=os.environ["OCR_MODEL"], # Modellname mit Bildunterstuetzung aus der Preisseite
messages=[{"role": "user", "content": "Antworte nur mit OK"}],
)
print(resp.choices[0].message.content)
Der Code prüft nur, ob Key, Base URL und Modellname zusammenpassen; nach bestätigter Verbindung auf echte Bildanfragen wechseln.
Bei lokaler .env die Datei in .gitignore aufnehmen und nur .env.example committen. In der Produktion bevorzugt Container-Secrets, Cloud-Secret-Manager oder einen Dienst wie Vault nutzen; Keys nicht in Dockerfile, Image-Schichten, Frontend-Builds oder CI-Logs schreiben. Nach Änderung der Umgebungsvariablen den Prozess neu starten. Viele Fälle von „online 401, lokal okay“ entstehen, weil der Dienst noch die alte Variable liest oder die Plattform sie nicht in die Laufzeitumgebung injiziert.
6. Reihenfolge der 401-Diagnose
Bei HTTP 401 in dieser Reihenfolge prüfen; meist ist die Ursache in Minuten gefunden:
- Header prüfen:
Authorization: Bearer sk-..., genau ein Leerzeichen zwischenBearerund Key. - Key erneut kopieren und auf Leerzeichen, Zeilenumbrüche, Anführungszeichen oder unsichtbare Zeichen prüfen.
- Prüfen, ob der Key gelöscht, deaktiviert oder abgelaufen ist.
- Prüfen, ob Key und Base URL zur selben Plattform gehören; keinen Key von Plattform A an Plattform B senden.
- Im Prozess die Länge der Umgebungsvariable ausgeben (nicht den Inhalt), um zu bestätigen, dass ein Wert und kein leerer String gelesen wird.
- Prüfen, ob Reverse-Proxy, Gateway oder SDK den
Authorization-Header umschreiben; bei Multipart-Formularen geht er besonders leicht verloren. - Scheitern nur einige Anfragen, prüfen, ob der Key im Frontend offengelegt und deshalb von der Risikokontrolle gesperrt wurde.
Auch Fehlertypen unterscheiden: 401 ist ein Identitätsproblem, 403 meist Rechte oder Region, 413 häufig ein zu großes Bild, 429 Rate oder Kontingent. OCR-400 ist oft Bildformat, Base64-Kodierung oder eine beschädigte Datei; nicht alles dem Key zuschreiben.
7. Offizieller Key oder Gateway-Key
Beide Wege funktionieren; Unterschiede liegen bei Einkauf, Netz und Wartung:
- Direkt beim Anbieter: Konto, Abrechnung und Modelle verwaltet der Hersteller. Geeignet für Teams mit passender Zahlungsfähigkeit, die Netz und Compliance selbst tragen. Bei nur einem OCR-Dienst ist der Weg am kürzesten; nachteilig sind unterschiedliche Authentifizierungsarten und mehrere Keys und Rechnungen bei mehreren Anbietern.
- Gateway: eine Base URL, ein Key, mehrere Modelle; Zugriff aus China und RMB-Abrechnung sind einfacher, Logs und Limits zentral. Der Preis ist eine zusätzliche Abhängigkeit; Datenrichtlinie, Verfügbarkeit, Störungsbenachrichtigung und Rechnungsunterstützung des Anbieters prüfen.
Entscheiden Sie nicht nur nach dem Preis. Mindestens klären: Werden Bilder und Ergebnisse gespeichert? Gibt es Rechnungen? Werden Modellabschaltungen angekündigt? Lassen sich Nutzungsdaten exportieren? Wie erreicht man den Support bei Störungen? Modelle und Preise entnehmen Sie den aktuellen Modellpreisen; Preise ändern sich, planen Sie nicht mit Zahlen aus alten Artikeln.
8. Rotation und Leak-Behandlung
Machen Sie Rotation zur Routine, nicht zur Reaktion auf einen Vorfall:
- Beim ursprünglichen Anbieter einen neuen Key mit gleichen Rechten anlegen.
- Umgebungsvariable oder Secrets-Dienst aktualisieren.
- Dienst neu starten oder neu ausrollen und mit einem Testbild bestätigen.
- 24 bis 48 Stunden Nutzungslogs beobachten, um ungewöhnliche Aufrufe zu finden.
- Alten Key deaktivieren und löschen; Zeitpunkt und Verantwortlichen dokumentieren.
Bei Leak-Verdacht ist die Reihenfolge umgekehrt: zuerst den alten Key deaktivieren, dann Nutzungslogs und Aufrufquellen prüfen, Repository-Historie, CI-Logs und Image-Schichten kontrollieren, zuletzt einen neuen Key anlegen. Nur die Zeichenkette im Code zu löschen reicht nicht; der Key kann bereits kopiert sein. Bei vorhandenem Guthaben prüfen, ob das Limit vorübergehend gesenkt werden sollte.
Häufige Fragen
Ist der OCR-Key derselbe wie der Chat-Modell-Key?
Auf OpenAI-kompatiblen Plattformen meist dieselbe Authentifizierung; derselbe Key ruft Chat und bildfähige Vision-Modelle auf. Ob ein Aufruf erlaubt ist, hängt von Kontorechten und Modellfreigabe ab, nicht vom Key-Typ.
Ist der vollständige Key nach dem Anlegen noch sichtbar?
Meist nicht. Der vollständige Key erscheint nur beim Anlegen, danach bleibt eine Maske. Wenn Sie ihn nicht gespeichert haben, löschen und neu anlegen; nicht aus Logs oder Browser-Cache zurückholen.
Warum funktioniert es lokal, der Server liefert aber 401?
Drei Dinge zuerst prüfen: Wurde die Umgebungsvariable injiziert? Behält der Reverse-Proxy den Authorization-Header? Wird online ein gelöschter oder abgelaufener Key verwendet? Danach prüfen, ob die Base URL auf die falsche Plattform zeigt.
Wird OCR pro Bild oder pro Token abgerechnet?
Beides kommt vor. Klassisches OCR rechnet meist pro Bild oder Seite, multimodale Modelle nach Eingabe-Bild-Tokens plus Ausgabe-Tokens. Details stehen in der Plattformdokumentation und den Modellpreisen.
Reicht Löschen nach einem Key-Leak?
Nein. Zuerst den Key deaktivieren, dann Nutzungslogs auf ungewöhnliche Aufrufe prüfen, Repository, CI-Logs und Image-Historie kontrollieren und schließlich alle möglicherweise betroffenen Keys rotieren. Bei Kundenausweisen oder Belegen nach internem Sicherheitsprozess bewerten, ob eine Benachrichtigung nötig ist.
Nächste Schritte
Wenn Sie noch kein Konto haben, beginnen Sie auf der Registrierungsseite, legen einen Key mit niedrigem Limit an und testen die Authentifizierung mit einem Testbild. Danach wählen Sie anhand der Modellpreise das Modell für den Produktivbetrieb. Die Behandlung strukturierter Felder steht im Einrichtungsartikel.
Weiterlesen:
- OCR API einrichten: Bildupload, Erkennung und Felder
- OCR-API über Relay und Proxy: Batch, Abrechnung, Migration
- Modellpreise und Tarife
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, Berechtigungen und Abrechnungsregeln richten sich nach der offiziellen Dokumentation und den Seiten auf dieser Website.
