SovrGPT Docs
API

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" }
  }
}
EOF

Response (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

FieldRequiredMeaning
fieldsyesObject 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 imagesat least onestate: 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.
modelnosovr-extract-1.0 or the alias sovr-extract. Omitted: sovr-extract-1.0. The answer always names the fixed ID.
reference_datenoYYYY-MM-DD. Reference date when a printed date lacks the year.
request_idnoUp 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:

FormExample
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 }
}
KeyTypesMeaning
typealltext, number, date, time, datetime, duration, list, boolean, enum, box, estimate. forecast → 400 unsupported_field_type.
instructionsallWhat to read, ≤ 1,000 characters. Write it without concrete example values, see Good instructions.
null_thresholdallNumber in (0, 1], default 0.5. Above this p_null, value becomes null. No effect on estimate.
locatetext, number, date, time, datetime, durationtrue = also determine the location in the image (one more pass). Needs an image.
unitnumber, duration, estimateUnit, ≤ 32 characters. For number/estimate only a label; for duration one of seconds (default), minutes, hours, days, weeks, months, years.
integernumber, durationtrue = round to an integer.
decimalsnumber, duration, list0–6 decimal places.
itemslist (required)text, number or date.
options / criteriaenum (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, maxestimate (required)Range, min < max.
stepestimateGrid, positive, at most max − min. The value is rounded to it.
scaleestimatelinear (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

FieldMeaning
object, id, status"extraction", ext_…, "completed"
request_idyour value or null
model.idthe fixed version, even if you sent the alias
model.operator, model.countryoperator and country of the runtime
model.runtimeinternal ID of the bound runtime
model.prompt_versionsovr-extract-prompt-1.0
model.viaalways "pinned"
model.available_untilearliest switch-off date of the version, e.g. "2027-02-04"
processing_regionprocessing location, e.g. "eu-de", in every answer; also as the header x-sovrgpt-processing-region
answersone answer per field name (below)
usage.input_tokens, usage.output_tokensacross all passes; image tokens are part of input_tokens
usage.image_tokensalways null: the operator does not report image tokens separately
usage.forward_passestotal passes: one per field, plus one per locate, plus one per guess follow-up
timing_mstotal, inference_max (longest pass), inference_sum (sum)
latency_ms= timing_ms.total

Per field

FieldPresent forMeaning
typeallthe requested type
valueallvalue or null (for list []); estimate always a number
guessall except listbest value, even if value is null
p_nullall; null for estimateprobability of “no value”
confidenceall; always null for box0–1; with value: null it refers to guess, otherwise to value
spantext[start, end) in the state, or null
spanslist with items: "text"one span per entry, or null
boxbox, locate: true{ image, image_name, x1, y1, x2, y2, left, top, right, bottom }; pixels null if the image size could not be read
probabilitiesboolean, enumper real option, without “not determinable”
mean, median, p10, p90, p_below, p_aboveestimatestatistics of the distribution
warningsallmatches_instruction_example, type_mismatch, unparseable_output, truncated, low_label_mass, exif_orientation_ignored
calibrationall{ "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.

StatuscodeMeaning
400invalid_request_error, invalid_jsoninvalid body, including an unknown field, a key that does not apply to the type, or an image that is not JPEG/PNG/WebP
400unsupported_field_typeforecast or another type that is deliberately not offered; the message gives the reason
400images_unsupportedthe runtime has no measured image support. Does not occur with sovr-extract-1.0.
401–key missing, invalid or revoked
402key_spend_limit, user_spend_limit, org_spend_limit, tier_spend_limitspending limit reached, or the free plan's allowance is used up (type: "quota_exceeded"); checked before anything is sent
403missing_scopekey lacks the extractions scope
404model_not_foundunknown version; the message lists the valid ones
413request_too_largebody over 4.4 MB, more than 4 images, an image over 4 MiB, all images over 8 MiB, or state over 16,000 characters
429upstream_rate_limitedthe runtime is throttling (type: "rate_limit_error"). The response carries Retry-After in seconds (the operator's value, otherwise 20). Retry after that.
502upstream_errorthe runtime answered unusably
503runtime_unavailablethe bound runtime is not reachable in this deployment. A different model is never used silently.
504upstream_timeoutthe 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.

Extraction Engine API (POST /v1/extractions)