API-Dokumentation

/v1/balance Liefert das aktuelle scan page Guthaben des authentifizierten Kontos. Verwenden Sie remaining_pages oder total_affordable_pages, um zu entscheiden, wie viele Seiten noch verarbeitet werden konnen.

curl -X GET https://sotaocr.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "entity_code": "scan_page",
  "remaining_pages": 63,
  "total_affordable_pages": 63,
  "monthly_pages": {"total": 40, "allocated": 5, "remaining": 35},
  "lifetime_pages": {"total": 20, "allocated": 2, "remaining": 18},
  "tokens": {"total": 120, "allocated": 20, "remaining": 100, "affordable_pages": 10},
  "token_price": 10
}

/v1/extract Ladt ein PDF oder Bild fur OCR hoch. Bei Erfolg kommt 202 Accepted mit Job-Metadaten wie account_id, upstream_job_id, created_at und updated_at zuruck.

• file: Dokumentdatei (PDF, PNG, JPG).
• page_ranges: (Optional) JSON-String mit einem Array von Seitenbereichen. Beispiel: '[{"start":1,"end":3}]'
• model_profile: Optionales OCR-Modellprofil. Lass das Feld weg, um den Service-Standard zu verwenden, oder sende einen Wert aus model_profiles von GET /api/v1/info.

curl -X POST https://sotaocr.com/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F 'page_ranges=[{"start":1,"end":5}]'

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "pending",
  "page_count": 5,
  "pages_completed": 0,
  "model_profile": "fast",
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:00Z"
}

/v1/jobs/{job_id} Liefert 200 OK mit dem aktuellen Status sowie account_id, upstream_job_id, page_count, pages_completed, created_at und updated_at.

curl -X GET https://sotaocr.com/v1/jobs/job_123456789 \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "id": "job_123456789",
  "account_id": "acct_123456789",
  "status": "completed",
  "page_count": 5,
  "pages_completed": 5,
  "upstream_job_id": "up_job_987654321",
  "created_at": "2026-03-24T12:00:00Z",
  "updated_at": "2026-03-24T12:00:08Z"
}

/v1/jobs/{job_id}/result?format=markdown Gibt 200 OK mit dem extrahierten Inhalt zurueck, wenn der Job completed ist. Fuer format=json koennen Seiten doc_preprocessor_res mit angle und page_preview-Metadaten fuer den BBox-Koordinatenraum enthalten. format=html gibt rekonstruiertes HTML in der JSON-Huelle zurueck und ist derzeit nur FAST; fuer eine eigenstaendige HTML-Datei mit eingebetteten Bildern nutze /result.html. Vorher antwortet der Endpunkt mit 202 Accepted und dem Code result_not_ready.

• format: (Optional) Antwortformat: json, markdown, text oder html. Standard ist json. html ist derzeit nur FAST.

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result?format=markdown" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "job_id": "job_123456789",
  "format": "json",
  "page_count": 1,
  "content": "{\"job_id\":\"job_123456789\",\"page_count\":1,\"pages\":[{\"page_number\":1,\"status\":\"completed\",\"text\":\"Ivan Matveev\",\"doc_preprocessor_res\":{\"angle\":0,\"model_settings\":{\"use_doc_orientation_classify\":true,\"use_doc_unwarping\":false}},\"page_preview\":{\"coordinate_space\":\"doc_preprocessed\",\"content_type\":\"image/png\",\"width\":1192,\"height\":1684},\"raw_result\":{}}]}"
}

/v1/jobs/{job_id}/result.html Gibt eine text/html-Rekonstruktion mit eingebetteten Data-URI-Bildern fuer FAST- und PRO-Jobs zurueck.

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.html" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.html

HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Disposition: inline; filename="job_123456789.html"

(eigenstaendiges HTML mit eingebetteten Data-URI-Bildern)

/v1/jobs/{job_id}/result.docx Gibt eine binaere .docx-Visuelle Rekonstruktion mit eingebetteten Seitenbildern und durchsuchbarem OCR-Text fuer FAST- und PRO-Jobs zurueck.

curl -X GET "https://sotaocr.com/v1/jobs/job_123456789/result.docx" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output result.docx

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="job_123456789.docx"

(binaere DOCX-Bytes)

/v1/jobs/{job_id}/pages/{page_number}/preview Liefert das PNG-Seitenbild nach automatischer Rotation und optionalem Unwarping. Genau dieses Bild solltest du hinter OCR-BBox-Overlays rendern.

curl -X GET https://sotaocr.com/v1/jobs/job_123456789/pages/1/preview \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output page_0001_preview.png

HTTP/1.1 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="page_0001_preview.png"

(binare PNG-Daten im selben Koordinatensystem wie die OCR-BBoxen)

Die meisten Fehlerantworten verwenden {"error":{"code":"...","message":"..."}}. insufficient_balance enthalt zusatzlich entity_code, requested_units und available_units.

• 400 Ungultige Anfrage: Ungueltiges Multipart, fehlendes file, ungueltige page_ranges oder ungueltiges PDF. Code: bad_request.
• 401 Nicht autorisiert: Bearer-Token fehlt oder ist ungueltig. Code: unauthorized.
• 403 Verboten: API-Zugang erforderlich oder Guthaben nicht ausreichend. Codes: api_access_required oder insufficient_balance.
• 404 Nicht gefunden: Unbekannte job_id oder Zugriff auf einen fremden Job. Code: job_not_found.
• 415 Nicht unterstutzter Medientyp: Der hochgeladene Dateityp wird nicht unterstutzt. Code: unsupported_media.
• 502 Upstream nicht verfugbar: OCR-Upstream ist nicht verfugbar oder die Job-Synchronisierung ist fehlgeschlagen. Code: upstream_unavailable.