SovrGPT Dokumentation
API

Extraction Engine API (POST /v1/extractions)

Extraction Engine API: Text und bis zu vier Fotos mit typisierten Feldern senden, je Feld Wert oder null mit confidence, p_null und guess zurückbekommen.

Die Extraction Engine liest typisierte Felder aus einem Zustand und bis zu vier Fotos. Je Feld rechnet das Modell einen eigenen Durchlauf, alle Felder gleichzeitig; zurück kommen Werte, keine Sätze. Was die Zahlen bedeuten, wie Sie gute Anweisungen schreiben und was gemessen ist, steht auf der Produktseite Extraction Engine.

Base-URL: https://sovrgpt.com/api/v1 · Scope: extractions · Auth: Authorization: Bearer sov_…

Eine Extraction anfragen

IMG=$(base64 -w0 rueckseite.jpg)   # macOS: base64 -i rueckseite.jpg

curl https://sovrgpt.com/api/v1/extractions \
  -H "Authorization: Bearer $SOVR_KEY" -H "content-type: application/json" \
  -d @- <<EOF
{
  "model": "sovr-extract-1.0",
  "images": [{ "name": "back", "data": "$IMG" }],
  "state": "Rückseite eines Gewürz-Sachets, 8 g.",
  "reference_date": "2026-11-06",
  "fields": {
    "batch_code":       { "type": "text", "instructions": "Chargencode in der Zeile mit dem Mindesthaltbarkeitsdatum: der Block nach dem Datum, bis zum ersten Leerzeichen. Datum und alles nach dem ersten Leerzeichen ausschließen." },
    "best_before":      { "type": "date", "instructions": "Mindesthaltbarkeitsdatum neben dem Chargencode" },
    "lot_code_present": { "type": "boolean", "instructions": "Ist auf dem Foto ein gedruckter Chargencode zu sehen?" },
    "code_region":      { "type": "box", "instructions": "Wo der Chargencode gedruckt ist" }
  }
}
EOF

Antwort (gekürzt, Werte zur Veranschaulichung):

{
  "object": "extraction",
  "id": "ext_8a2f…",
  "request_id": null,
  "status": "completed",
  "model": {
    "id": "sovr-extract-1.0", "runtime": "…", "operator": "STACKIT (Schwarz Digital)", "country": "DE",
    "prompt_version": "sovr-extract-prompt-1.0", "via": "pinned", "available_until": "2027-02-04"
  },
  "processing_region": "eu-de",
  "answers": {
    "batch_code": {
      "type": "text", "value": "61234567K1", "guess": "61234567K1",
      "p_null": 0.0003, "confidence": 0.9712, "span": null,
      "warnings": [], "calibration": { "status": "uncalibrated" }
    },
    "best_before": {
      "type": "date", "value": "2027-08-31", "guess": "2027-08-31",
      "p_null": 0.0001, "confidence": 0.9934,
      "warnings": [], "calibration": { "status": "uncalibrated" }
    },
    "lot_code_present": {
      "type": "boolean", "value": true, "guess": true, "p_null": 0.0021,
      "confidence": 0.9996, "probabilities": { "true": 0.9998, "false": 0.0002 },
      "warnings": [], "calibration": { "status": "uncalibrated" }
    },
    "code_region": {
      "type": "box",
      "value": { "image": 0, "image_name": "back", "x1": 309, "y1": 1023, "x2": 891, "y2": 1095,
                 "left": 0.2575, "top": 0.6396, "right": 0.7425, "bottom": 0.6846 },
      "guess": { "…": "wie value" }, "box": { "…": "wie value" },
      "p_null": 0.0009, "confidence": null,
      "warnings": [], "calibration": { "status": "uncalibrated" }
    }
  },
  "usage": { "input_tokens": 8260, "output_tokens": 54, "image_tokens": null, "forward_passes": 4 },
  "timing_ms": { "total": 861, "inference_max": 842, "inference_sum": 2730 },
  "latency_ms": 861
}

span ist hier null, weil der Wert aus dem Bild kommt und nicht im Zustand steht.

Anfrage

FeldPflichtBedeutung
fieldsjaObjekt Feldname → Felddefinition, 1–24 Felder; zusammen mit locate-Fundorten höchstens 16 Durchläufe je Anfrage (sonst 400). Feldnamen: Buchstabe oder _ zuerst, dann Buchstaben, Ziffern, _ . -, höchstens 64 Zeichen.
state und/oder imagesmindestens einesstate: Text oder JSON (≤ 16 000 Zeichen). Ein Objekt wird als JSON-Text gelesen; span bezieht sich dann auf diese Serialisierung. images: 1–4 Bilder, siehe unten.
modelneinsovr-extract-1.0 oder der Alias sovr-extract. Ohne Angabe: sovr-extract-1.0. Die Antwort nennt immer die feste Kennung.
reference_dateneinJJJJ-MM-TT. Bezugsdatum, wenn auf einem Datum das Jahr fehlt.
request_idneinBis 128 Zeichen, wird gespiegelt (Korrelation). Es ist kein Idempotenzschlüssel: Eine Wiederholung wird erneut gerechnet und berechnet.

Unbekannte Felder werden mit 400 abgelehnt, auf jeder Ebene. So sieht ein Tippfehler nie aus, als wirke er.

Bilder

1–4 Bilder, JPEG, PNG oder WebP, je ≤ 4 MiB, zusammen ≤ 8 MiB (dekodiert), Rumpf ≤ 4,4 MB. Nur eingebettet; der Dienst lädt keine fremden URLs. Vier Schreibweisen:

FormBeispiel
Data-URL als Zeichenkette"data:image/jpeg;base64,/9j/…"
data_url{ "data_url": "data:image/png;base64,…" }
data (Typ aus den Bytes), optional name{ "name": "back", "data": "/9j/…" }
content_type + base64{ "content_type": "image/webp", "base64": "UklGR…" }

Je Bild genau eine von data_url, data, base64. name: 1–40 Zeichen (Buchstaben, Ziffern, Leerzeichen, _ . -), je Anfrage eindeutig. Ein angegebener Typ, der nicht zu den Bytes passt, ergibt 400. Warum der Rumpf in der Praxis die Grenze ist, steht unter Bilder.

Felder

{
  "amount":    { "type": "number", "instructions": "Rechnungsbetrag brutto", "unit": "EUR", "decimals": 2 },
  "items":     { "type": "list", "items": "text", "instructions": "Alle Artikelnummern in der Positionstabelle" },
  "packaging": { "type": "enum", "criteria": { "sachet": "Beutel", "box": "Faltschachtel", "jar": "Glas" } },
  "fill_level":{ "type": "estimate", "min": 0, "max": 100, "step": 5, "unit": "%" },
  "issued_on": { "type": "date", "locate": true, "null_threshold": 0.3 }
}
SchlüsselTypenBedeutung
typealletext, number, date, time, datetime, duration, list, boolean, enum, box, estimate. forecast → 400 unsupported_field_type.
instructionsalleWas gelesen werden soll, ≤ 1 000 Zeichen. Ohne konkrete Beispielwerte schreiben, siehe Gute Anweisungen.
null_thresholdalleZahl in (0, 1], Vorgabe 0,5. Über diesem p_null wird value zu null. Ohne Wirkung bei estimate.
locatetext, number, date, time, datetime, durationtrue = zusätzlich den Fundort im Bild bestimmen (ein weiterer Durchlauf). Braucht ein Bild.
unitnumber, duration, estimateEinheit, ≤ 32 Zeichen. Bei number/estimate nur Beschriftung; bei duration eine von seconds (Vorgabe), minutes, hours, days, weeks, months, years.
integernumber, durationtrue = ganzzahlig runden.
decimalsnumber, duration, list0–6 Nachkommastellen.
itemslist (Pflicht)text, number oder date.
options / criteriaenum (eines davon Pflicht)options: Array aus Kennungen ("sachet") oder { "id", "description" }; criteria: Objekt Kennung → Beschreibung. 2–25 Optionen, Kennungen a–z 0–9 _ -, höchstens 40 Zeichen; not_determinable ist reserviert.
min, maxestimate (Pflicht)Bereich, min < max.
stepestimateRaster, positiv, höchstens max − min. Der Wert wird darauf gerundet.
scaleestimatelinear (Vorgabe) oder log (dann min > 0).

box braucht mindestens ein Bild und nimmt außer instructions und null_threshold keine Schlüssel. Ein Schlüssel, der zum Typ nicht passt, ergibt 400.

Antwort

FeldBedeutung
object, id, status"extraction", ext_…, "completed"
request_idIhr Wert oder null
model.iddie feste Version, auch wenn Sie den Alias geschickt haben
model.operator, model.countryBetreiber und Land der Laufzeit
model.runtimeinterne Kennung der gebundenen Laufzeit
model.prompt_versionsovr-extract-prompt-1.0
model.viaimmer "pinned"
model.available_untilfrühestes Abschaltdatum der Version, z. B. "2027-02-04"
processing_regionVerarbeitungsort, z. B. "eu-de", in jeder Antwort; zusätzlich als Kopfzeile x-sovrgpt-processing-region
answersje Feldname eine Antwort (unten)
usage.input_tokens, usage.output_tokensüber alle Durchläufe; Bildtoken stecken in input_tokens
usage.image_tokensimmer null: der Betreiber weist Bildtoken nicht getrennt aus
usage.forward_passesDurchläufe insgesamt: eins je Feld, plus eins je locate, plus eins je guess-Nachlauf
timing_mstotal, inference_max (längster Durchlauf), inference_sum (Summe)
latency_ms= timing_ms.total

Je Feld

FeldVorhanden beiBedeutung
typeallender angefragte Typ
valueallenWert oder null (bei list []); estimate immer eine Zahl
guessallen außer listbester Wert, auch wenn value null ist
p_nullallen; bei estimate nullWahrscheinlichkeit „kein Wert“
confidenceallen; bei box immer null0–1; bei value: null bezogen auf guess, sonst auf value
spantext[start, end) im Zustand oder null
spanslist mit items: "text"je Eintrag eine Spanne oder null
boxbox, locate: true{ image, image_name, x1, y1, x2, y2, left, top, right, bottom }; Pixel null, wenn die Bildmaße nicht lesbar waren
probabilitiesboolean, enumje echter Option, ohne „nicht bestimmbar“
mean, median, p10, p90, p_below, p_aboveestimateKennzahlen der Verteilung
warningsallenmatches_instruction_example, type_mismatch, unparseable_output, truncated, low_label_mass, exif_orientation_ignored
calibrationallen{ "status": "uncalibrated" }

Wie confidence und p_null entstehen und was die Warnungen bedeuten, steht unter Wie confidence und p_null entstehen.

Fehler

Fehlerform wie überall unter /v1: { "error": { "message", "type", "code" } }. Es gibt keine Teilantworten: Scheitert ein Pflichtdurchlauf, scheitert die ganze Anfrage.

StatuscodeBedeutung
400invalid_request_error, invalid_jsonRumpf ungültig, auch ein unbekanntes Feld, ein Schlüssel, der nicht zum Typ passt, oder ein Bild, das nicht JPEG/PNG/WebP ist
400unsupported_field_typeforecast oder ein anderer bewusst nicht angebotener Typ; die Meldung nennt den Grund
400images_unsupportedDie Laufzeit hat keine gemessene Bildunterstützung. Bei sovr-extract-1.0 kommt das nicht vor.
401–Schlüssel fehlt, ungültig oder widerrufen
402key_spend_limit, user_spend_limit, org_spend_limit, tier_spend_limitAusgabenlimit erreicht bzw. kostenloses Kontingent im Tarif Free aufgebraucht (type: "quota_exceeded"); geprüft, bevor etwas gesendet wird
403missing_scopeSchlüssel ohne Scope extractions
404model_not_foundunbekannte Version; die Meldung nennt die gültigen
413request_too_largeRumpf über 4,4 MB, mehr als 4 Bilder, ein Bild über 4 MiB, alle Bilder über 8 MiB oder state über 16 000 Zeichen
429upstream_rate_limitedDie Laufzeit drosselt (type: "rate_limit_error"). Die Antwort trägt Retry-After in Sekunden (die Angabe des Betreibers, sonst 20). Danach wiederholen.
502upstream_errorDie Laufzeit antwortete unbrauchbar.
503runtime_unavailableIn dieser Umgebung ist die gebundene Laufzeit nicht erreichbar. Es wird nie still ein anderes Modell genommen.
504upstream_timeoutDie Laufzeit antwortete nicht rechtzeitig (Deckel 25 s je Durchlauf).

⚠️ Anders als bei der Decision Engine: Scheitert eine Anfrage mit 429, 502 oder 504, werden die Durchläufe berechnet, die die Laufzeit bis dahin schon beantwortet hatte. Bei vielen Feldern lohnt es sich deshalb, vor dem Wiederholen Retry-After abzuwarten.

Grenzen und Kosten

1–24 Felder, höchstens 16 Durchläufe (Felder + locate), höchstens 8 davon gleichzeitig · state ≤ 16 000 Zeichen · instructions ≤ 1 000 Zeichen · Optionsbeschreibung ≤ 512 Zeichen · enum 2–25 Optionen · list höchstens 50 Einträge · 1–4 Bilder, je ≤ 4 MiB, zusammen ≤ 8 MiB · Rumpf ≤ 4,4 MB.

Anbietergrenze: Die Laufzeit von sovr-extract-1.0 erlaubt 45 Anfragen und 350 000 Token je Minute, und jeder Durchlauf ist eine Anfrage. Wer viele Fotos auf einmal auswertet, schickt sie nacheinander oder mit wenigen Feldern je Anfrage. Einen Batch-Endpunkt gibt es nicht.

Kosten: Abgerechnet werden Eingabe- und Ausgabetoken aller beantworteten Durchläufe zum Preis der gebundenen Laufzeit; GET /v1/models nennt ihn unter pricing, sobald die Preisliste veröffentlicht ist. Ein Feld auf einem Foto mit 1600 px kostet rund 2 065 Eingabetoken; locate und der guess-Nachlauf kosten je einen weiteren Durchlauf.

Versionen abfragen

curl https://sovrgpt.com/api/v1/extractions/models -H "Authorization: Bearer $SOVR_KEY"

Gültiger Schlüssel genügt, kein Scope. Je Version: id, alias, display_name, description, default, pinned: true, released, available_until, operator, country, processing_region, images, field_types, unsupported_field_types, measured (on, p50_ms, p95_ms, prompt_tokens_per_field) und status. Dazu limits mit allen Grenzen dieser Seite. status ist heute "available"; vergleichen Sie nicht hart gegen genau einen Wert.

Datenschutz

Bilder, Zustand, Felder und Antworten werden nicht gespeichert; in Ihrem Verbrauch stehen nur Tokenzahlen. Kein Training mit Ihren Daten. Bilder werden nicht nachgeladen, nur eingebettete Daten zählen. Der Verarbeitungsort steht in jeder Antwort (processing_region, model.operator, model.country).

Dieselbe Engine gibt es im MCP-Server als sovrgpt_extract und nach der Anmeldung als Playground unter Einstellungen → Entwickler → Extraction Engine.

Extraction Engine API (POST /v1/extractions)