BIQE API

Integrieren Sie Handschriftenerkennung mit LLM-Korrektur direkt in Ihre eigene Pipeline. REST-basiert, JSON-Antworten, Authentifizierung per API-Schlüssel.

Die BIQE-API ist für den Produktiveinsatz gedacht: Sie reichen Seiten programmatisch ein, verfolgen den Status und rufen das Ergebnis ab — ohne das Portal zu öffnen. Die Verarbeitung durchläuft dieselbe Kette wie im Portal (Layout-Erkennung, Erkennung, LLM-Korrektur, Export nach PageXML/ALTO/PDF).

Authentifizierung

Jede Anfrage authentifiziert sich mit einem API-Schlüssel. Sie können den Schlüssel im X-API-Key-Header oder in einem Authorization: Bearer-Header übergeben — beide werden akzeptiert. Der Verkehr läuft über verschlüsseltes HTTPS.

X-API-Key: biqe_live_xxxxxxxxxxxxxxxxxxxxxxxx

# oder, gleichwertig:
Authorization: Bearer biqe_live_xxxxxxxxxxxxxxxxxxxxxxxx

API-Schlüssel verwalten

Schlüssel erstellen und verwalten Sie selbst im Kundenportal unter Einstellungen ▸ API-Schlüssel ▸ + Neuer API-Schlüssel. Geben Sie dem Schlüssel eine Bezeichnung. Der Wert wird bei der Erstellung einmalig angezeigt — danach kann er nicht erneut angezeigt werden. Das Widerrufen erfolgt auf derselben Seite und wirkt sofort.

Einen Scan einreichen

Reichen Sie Seiten als ZIP-Archiv ein (ein Bild pro Seite), im Multipart-Feld scan_zip. Optional übergeben Sie eine Verarbeitungsstufe, ein Preset und eine Webhook-URL.

curl -X POST https://ocr-handwriting.online/v1/process-scan \
  -H "X-API-Key: $BIQE_API_KEY" \
  -F "scan_zip=@my-pages.zip" \
  -F "llm_tier=balanced" \
  -F "preset=generic_historical" \
  -F "webhook_url=https://your-system.example/biqe-callback"

Antwort — 202 Accepted:

{
  "job_id": "ff6f3db8-ab61-47d0-9f69-1987b5b0f2f0",
  "state": "queued",
  "page_count": 14,
  "created_at": "2026-05-02T11:56:05Z",
  "expires_at": "2026-05-09T11:56:05Z",
  "status_url": ".../v1/process-scan/ff6f3db8-...",
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

Den Auftragsstatus verfolgen

Fragen Sie den Status ab oder warten Sie auf den Webhook-Callback (empfohlen für größere Mengen).

curl https://ocr-handwriting.online/v1/process-scan/<job_id> \
  -H "X-API-Key: $BIQE_API_KEY"

Antwort (Felder je nach Fortschritt):

{
  "job_id": "ff6f3db8-...",
  "state": "done",
  "page_count": 14,
  "current_step": "export",
  "created_at": "2026-05-02T11:56:05Z",
  "started_at": "2026-05-02T11:56:09Z",
  "finished_at": "2026-05-02T11:57:43Z",
  "expires_at": "2026-05-09T11:56:05Z",
  "error_message": null,
  "warning_message": null,
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

Das Ergebnis abrufen

Sobald der Status done ist, laden Sie über diesen Endpunkt (oder die result_url) das Ergebnis-Archiv herunter: PageXML, ALTO und — falls aktiviert — eine durchsuchbare PDF. Der Link bleibt etwa 7 Tage verfügbar (siehe expires_at).

curl -L https://ocr-handwriting.online/v1/process-scan/<job_id>/result \
  -H "X-API-Key: $BIQE_API_KEY" \
  -o result.zip

Einen Auftrag abbrechen

Ein Auftrag, der noch in der Warteschlange steht oder verarbeitet wird, kann abgebrochen werden. Der Status wechselt dann zu cancelled.

curl -X DELETE https://ocr-handwriting.online/v1/process-scan/<job_id> \
  -H "X-API-Key: $BIQE_API_KEY"

Webhook-Callback & Retries

Übergeben Sie eine webhook_url, senden wir einen POST mit JSON, sobald der Auftrag einen Endzustand erreicht (done oder failed). Der Callback enthält diese Header:

Die Payload:

{
  "job_id": "ff6f3db8-...",
  "state": "done",
  "page_count": 14,
  "result_url": ".../v1/process-scan/ff6f3db8-.../result"
}

result_url ist nur vorhanden, wenn state gleich done ist. Fehlgeschlagene Zustellungen werden bis zu fünfmal mit exponentiellem Back-off wiederholt (etwa 1, 5, 25, 125 und 625 Sekunden). Ihr Endpunkt sollte möglichst schnell ein 2xx zurückgeben und über HTTPS erreichbar sein.

Die Webhook-Signatur prüfen

Jeder Callback ist signiert. Die Signatur ist ein HMAC-SHA256 über den rohen Request-Body, mit Ihrem kontospezifischen Webhook-Secret als Schlüssel, als Kleinbuchstaben-Hex im Header X-BIQE-Signature. Das Secret (64 Hex-Zeichen) ist kundenspezifisch; rufen Sie es über das Portal ab.

import hmac, hashlib

secret = "<your-webhook-secret>".encode()
body   = request.get_data()  # raw bytes
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, request.headers["X-BIQE-Signature"]):
    return "forbidden", 403

Auftragsstatus

Parameter von process-scan

Fehlerbehandlung