Extraction Engine API (POST /v1/extractions)
Extraction Engine API: send text and up to four photos with typed fields, get a value or null per field with confidence, p_null and guess.
The Extraction Engine reads typed fields from a state and up to four photos. The model runs a separate pass per field, all fields at the same time; what comes back are values, not sentences. What the numbers mean, how to write good instructions and what has been measured is on the product page Extraction Engine.
Base URL: https://sovrgpt.com/api/v1 · Scope: extractions · Auth: Authorization: Bearer sov_…
Request an extraction
IMG=$(base64 -w0 back.jpg) # macOS: base64 -i back.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": "Back of a seasoning sachet, 8 g.",
"reference_date": "2026-11-06",
"fields": {
"batch_code": { "type": "text", "instructions": "Batch code on the line with the best-before date: the block after the date, up to the first space. Exclude the date and anything after the first space." },
"best_before": { "type": "date", "instructions": "Best-before date printed next to the batch code" },
"lot_code_present": { "type": "boolean", "instructions": "Is a printed batch code visible on the photo?" },
"code_region": { "type": "box", "instructions": "Where the batch code is printed" }
}
}
EOFResponse (abridged, values for illustration):
{
"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": { "…": "same as value" }, "box": { "…": "same as 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 is null here because the value comes from the image and does not appear in the state.
Request
| Field | Required | Meaning |
|---|---|---|
fields | yes | Object field name → field definition, 1–24 fields; together with locate passes at most 16 passes per request (otherwise 400). Field names: a letter or _ first, then letters, digits, _ . -, at most 64 characters. |
state and/or images | at least one | state: text or JSON (≤ 16,000 characters). An object is read as JSON text; span then refers to that serialisation. images: 1–4 images, see below. |
model | no | sovr-extract-1.0 or the alias sovr-extract. Omitted: sovr-extract-1.0. The answer always names the fixed ID. |
reference_date | no | YYYY-MM-DD. Reference date when a printed date lacks the year. |
request_id | no | Up to 128 characters, echoed back (correlation). It is not an idempotency key: a repeat is computed and billed again. |
Unknown fields are rejected with 400 at every level, so a typo never looks as if it had an
effect.
Images
1–4 images, JPEG, PNG or WebP, ≤ 4 MiB each, ≤ 8 MiB together (decoded), body ≤ 4.4 MB. Embedded only; the service never fetches remote URLs. Four notations:
| Form | Example |
|---|---|
| data URL as a string | "data:image/jpeg;base64,/9j/…" |
data_url | { "data_url": "data:image/png;base64,…" } |
data (type from the bytes), optional name | { "name": "back", "data": "/9j/…" } |
content_type + base64 | { "content_type": "image/webp", "base64": "UklGR…" } |
Exactly one of data_url, data, base64 per image. name: 1–40 characters (letters,
digits, space, _ . -), unique per request. A declared type that does not match the bytes
gives 400. Why the body is the limit in practice is explained under
Images.
Fields
{
"amount": { "type": "number", "instructions": "Invoice total incl. VAT", "unit": "EUR", "decimals": 2 },
"items": { "type": "list", "items": "text", "instructions": "All article numbers in the line-item table" },
"packaging": { "type": "enum", "criteria": { "sachet": "pouch", "box": "folding carton", "jar": "glass jar" } },
"fill_level":{ "type": "estimate", "min": 0, "max": 100, "step": 5, "unit": "%" },
"issued_on": { "type": "date", "locate": true, "null_threshold": 0.3 }
}| Key | Types | Meaning |
|---|---|---|
type | all | text, number, date, time, datetime, duration, list, boolean, enum, box, estimate. forecast → 400 unsupported_field_type. |
instructions | all | What to read, ≤ 1,000 characters. Write it without concrete example values, see Good instructions. |
null_threshold | all | Number in (0, 1], default 0.5. Above this p_null, value becomes null. No effect on estimate. |
locate | text, number, date, time, datetime, duration | true = also determine the location in the image (one more pass). Needs an image. |
unit | number, duration, estimate | Unit, ≤ 32 characters. For number/estimate only a label; for duration one of seconds (default), minutes, hours, days, weeks, months, years. |
integer | number, duration | true = round to an integer. |
decimals | number, duration, list | 0–6 decimal places. |
items | list (required) | text, number or date. |
options / criteria | enum (one of them required) | options: array of ids ("sachet") or { "id", "description" }; criteria: object id → description. 2–25 options, ids a–z 0–9 _ -, at most 40 characters; not_determinable is reserved. |
min, max | estimate (required) | Range, min < max. |
step | estimate | Grid, positive, at most max − min. The value is rounded to it. |
scale | estimate | linear (default) or log (then min > 0). |
box needs at least one image and takes no keys besides instructions and null_threshold.
A key that does not apply to the type gives 400.
Response
| Field | Meaning |
|---|---|
object, id, status | "extraction", ext_…, "completed" |
request_id | your value or null |
model.id | the fixed version, even if you sent the alias |
model.operator, model.country | operator and country of the runtime |
model.runtime | internal ID of the bound runtime |
model.prompt_version | sovr-extract-prompt-1.0 |
model.via | always "pinned" |
model.available_until | earliest switch-off date of the version, e.g. "2027-02-04" |
processing_region | processing location, e.g. "eu-de", in every answer; also as the header x-sovrgpt-processing-region |
answers | one answer per field name (below) |
usage.input_tokens, usage.output_tokens | across all passes; image tokens are part of input_tokens |
usage.image_tokens | always null: the operator does not report image tokens separately |
usage.forward_passes | total passes: one per field, plus one per locate, plus one per guess follow-up |
timing_ms | total, inference_max (longest pass), inference_sum (sum) |
latency_ms | = timing_ms.total |
Per field
| Field | Present for | Meaning |
|---|---|---|
type | all | the requested type |
value | all | value or null (for list []); estimate always a number |
guess | all except list | best value, even if value is null |
p_null | all; null for estimate | probability of “no value” |
confidence | all; always null for box | 0–1; with value: null it refers to guess, otherwise to value |
span | text | [start, end) in the state, or null |
spans | list with items: "text" | one span per entry, or null |
box | box, locate: true | { image, image_name, x1, y1, x2, y2, left, top, right, bottom }; pixels null if the image size could not be read |
probabilities | boolean, enum | per real option, without “not determinable” |
mean, median, p10, p90, p_below, p_above | estimate | statistics of the distribution |
warnings | all | matches_instruction_example, type_mismatch, unparseable_output, truncated, low_label_mass, exif_orientation_ignored |
calibration | all | { "status": "uncalibrated" } |
How confidence and p_null are derived and what the warnings mean is explained under
How confidence and p_null are derived.
Errors
Error format as everywhere under /v1: { "error": { "message", "type", "code" } }. There are
no partial answers: if a required pass fails, the whole request fails.
| Status | code | Meaning |
|---|---|---|
| 400 | invalid_request_error, invalid_json | invalid body, including an unknown field, a key that does not apply to the type, or an image that is not JPEG/PNG/WebP |
| 400 | unsupported_field_type | forecast or another type that is deliberately not offered; the message gives the reason |
| 400 | images_unsupported | the runtime has no measured image support. Does not occur with sovr-extract-1.0. |
| 401 | – | key missing, invalid or revoked |
| 402 | key_spend_limit, user_spend_limit, org_spend_limit, tier_spend_limit | spending limit reached, or the free plan's allowance is used up (type: "quota_exceeded"); checked before anything is sent |
| 403 | missing_scope | key lacks the extractions scope |
| 404 | model_not_found | unknown version; the message lists the valid ones |
| 413 | request_too_large | body over 4.4 MB, more than 4 images, an image over 4 MiB, all images over 8 MiB, or state over 16,000 characters |
| 429 | upstream_rate_limited | the runtime is throttling (type: "rate_limit_error"). The response carries Retry-After in seconds (the operator's value, otherwise 20). Retry after that. |
| 502 | upstream_error | the runtime answered unusably |
| 503 | runtime_unavailable | the bound runtime is not reachable in this deployment. A different model is never used silently. |
| 504 | upstream_timeout | the runtime did not answer in time (cap 25 s per pass) |
⚠️ Unlike the Decision Engine: if a request fails with 429, 502 or 504, the passes the
runtime had already answered are billed. With many fields it pays to wait for Retry-After
before retrying.
Limits and cost
1–24 fields, at most 16 passes (fields + locate), at most 8 of them at once · state ≤ 16,000 characters · instructions ≤ 1,000 characters · option
description ≤ 512 characters · enum 2–25 options · list at most 50 entries · 1–4 images,
≤ 4 MiB each, ≤ 8 MiB together · body ≤ 4.4 MB.
Provider limit: the runtime of sovr-extract-1.0 allows 45 requests and 350,000 tokens per
minute, and every pass is a request. If you evaluate many photos at once, send them one after
another or with few fields per request. There is no batch endpoint.
Cost: billing counts input and output tokens of all answered passes at the price of the
bound runtime; GET /v1/models lists it under pricing once the price list is published. One
field on one photo with 1600 px costs about 2,065 input tokens; locate and the guess
follow-up each cost one more pass.
Listing versions
curl https://sovrgpt.com/api/v1/extractions/models -H "Authorization: Bearer $SOVR_KEY"A valid key is enough, no scope. Per 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) and status. Plus limits with every limit on
this page. status is "available" today; do not compare hard against exactly one value.
Privacy
Images, state, fields and answers are not stored; your usage records only token counts. No
training on your data. Images are never fetched, only embedded data counts. The processing
location is part of every answer (processing_region, model.operator, model.country).
The same engine is available in the MCP server as sovrgpt_extract and, after
signing in, as a playground under Einstellungen → Entwickler → Extraction Engine.