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" }
}
}
EOFAntwort (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
| Feld | Pflicht | Bedeutung |
|---|---|---|
fields | ja | Objekt 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 images | mindestens eines | state: 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. |
model | nein | sovr-extract-1.0 oder der Alias sovr-extract. Ohne Angabe: sovr-extract-1.0. Die Antwort nennt immer die feste Kennung. |
reference_date | nein | JJJJ-MM-TT. Bezugsdatum, wenn auf einem Datum das Jahr fehlt. |
request_id | nein | Bis 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:
| Form | Beispiel |
|---|---|
| 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üssel | Typen | Bedeutung |
|---|---|---|
type | alle | text, number, date, time, datetime, duration, list, boolean, enum, box, estimate. forecast → 400 unsupported_field_type. |
instructions | alle | Was gelesen werden soll, ≤ 1 000 Zeichen. Ohne konkrete Beispielwerte schreiben, siehe Gute Anweisungen. |
null_threshold | alle | Zahl in (0, 1], Vorgabe 0,5. Über diesem p_null wird value zu null. Ohne Wirkung bei estimate. |
locate | text, number, date, time, datetime, duration | true = zusätzlich den Fundort im Bild bestimmen (ein weiterer Durchlauf). Braucht ein Bild. |
unit | number, duration, estimate | Einheit, ≤ 32 Zeichen. Bei number/estimate nur Beschriftung; bei duration eine von seconds (Vorgabe), minutes, hours, days, weeks, months, years. |
integer | number, duration | true = ganzzahlig runden. |
decimals | number, duration, list | 0–6 Nachkommastellen. |
items | list (Pflicht) | text, number oder date. |
options / criteria | enum (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, max | estimate (Pflicht) | Bereich, min < max. |
step | estimate | Raster, positiv, höchstens max − min. Der Wert wird darauf gerundet. |
scale | estimate | linear (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
| Feld | Bedeutung |
|---|---|
object, id, status | "extraction", ext_…, "completed" |
request_id | Ihr Wert oder null |
model.id | die feste Version, auch wenn Sie den Alias geschickt haben |
model.operator, model.country | Betreiber und Land der Laufzeit |
model.runtime | interne Kennung der gebundenen Laufzeit |
model.prompt_version | sovr-extract-prompt-1.0 |
model.via | immer "pinned" |
model.available_until | frühestes Abschaltdatum der Version, z. B. "2027-02-04" |
processing_region | Verarbeitungsort, z. B. "eu-de", in jeder Antwort; zusätzlich als Kopfzeile x-sovrgpt-processing-region |
answers | je Feldname eine Antwort (unten) |
usage.input_tokens, usage.output_tokens | über alle Durchläufe; Bildtoken stecken in input_tokens |
usage.image_tokens | immer null: der Betreiber weist Bildtoken nicht getrennt aus |
usage.forward_passes | Durchläufe insgesamt: eins je Feld, plus eins je locate, plus eins je guess-Nachlauf |
timing_ms | total, inference_max (längster Durchlauf), inference_sum (Summe) |
latency_ms | = timing_ms.total |
Je Feld
| Feld | Vorhanden bei | Bedeutung |
|---|---|---|
type | allen | der angefragte Typ |
value | allen | Wert oder null (bei list []); estimate immer eine Zahl |
guess | allen außer list | bester Wert, auch wenn value null ist |
p_null | allen; bei estimate null | Wahrscheinlichkeit „kein Wert“ |
confidence | allen; bei box immer null | 0–1; bei value: null bezogen auf guess, sonst auf value |
span | text | [start, end) im Zustand oder null |
spans | list mit items: "text" | je Eintrag eine Spanne oder null |
box | box, locate: true | { image, image_name, x1, y1, x2, y2, left, top, right, bottom }; Pixel null, wenn die Bildmaße nicht lesbar waren |
probabilities | boolean, enum | je echter Option, ohne „nicht bestimmbar“ |
mean, median, p10, p90, p_below, p_above | estimate | Kennzahlen der Verteilung |
warnings | allen | matches_instruction_example, type_mismatch, unparseable_output, truncated, low_label_mass, exif_orientation_ignored |
calibration | allen | { "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.
| Status | code | Bedeutung |
|---|---|---|
| 400 | invalid_request_error, invalid_json | Rumpf ungültig, auch ein unbekanntes Feld, ein Schlüssel, der nicht zum Typ passt, oder ein Bild, das nicht JPEG/PNG/WebP ist |
| 400 | unsupported_field_type | forecast oder ein anderer bewusst nicht angebotener Typ; die Meldung nennt den Grund |
| 400 | images_unsupported | Die Laufzeit hat keine gemessene Bildunterstützung. Bei sovr-extract-1.0 kommt das nicht vor. |
| 401 | – | Schlüssel fehlt, ungültig oder widerrufen |
| 402 | key_spend_limit, user_spend_limit, org_spend_limit, tier_spend_limit | Ausgabenlimit erreicht bzw. kostenloses Kontingent im Tarif Free aufgebraucht (type: "quota_exceeded"); geprüft, bevor etwas gesendet wird |
| 403 | missing_scope | Schlüssel ohne Scope extractions |
| 404 | model_not_found | unbekannte Version; die Meldung nennt die gültigen |
| 413 | request_too_large | Rumpf über 4,4 MB, mehr als 4 Bilder, ein Bild über 4 MiB, alle Bilder über 8 MiB oder state über 16 000 Zeichen |
| 429 | upstream_rate_limited | Die Laufzeit drosselt (type: "rate_limit_error"). Die Antwort trägt Retry-After in Sekunden (die Angabe des Betreibers, sonst 20). Danach wiederholen. |
| 502 | upstream_error | Die Laufzeit antwortete unbrauchbar. |
| 503 | runtime_unavailable | In dieser Umgebung ist die gebundene Laufzeit nicht erreichbar. Es wird nie still ein anderes Modell genommen. |
| 504 | upstream_timeout | Die 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.