Skip to main content
POST
Returns a calibrated probability for each question about state, and a typed value for each field to extract. For the concepts, see System One. To migrate a client, see TypeSafe SDK Compatibility. Authentication is optional: see Authentication and Rate Limits.

Request body

An unknown top-level field is a 422.

Question object

A request takes at most 16 questions, of which at most 8 are box. A box needs an image in the request, from assets, an image_url part, or a PDF. A field’s id is the name the model writes its value under, so it is one line with no :.

Content parts

content is a flat list: media first, then state. There are no roles and no history.
Images or one document, never both. A PDF’s first document_max_pages pages (16 by default), or the pages document_pages selects, are rasterised at document_dpi (96 by default) and read as the request’s images. Sending both is a 422.
One high or auto part sets every image and page in the request to 280 tokens.

Assets

assets maps a reference string to an image. The reference is replaced by the image wherever it appears inside a string of state, a question’s instructions, or its criteria. Object keys are never replaced. An asset that nothing references is a 422. Assets count toward the same 8 images per request, 5 MB each. A reference is at most 1 KB. To upload instead of inlining, send multipart/form-data. Put the JSON body in a part named request and each image in the file part its asset names in part. Every file part must be claimed by one asset. Over plain JSON, part is a 422.

Response

The x-typesafe-request-id header matches the Gateway x-request-id. A decision is billed per read, and a rejected request bills nothing. See Pricing.

Answer shapes

confidence is 1 - H(p) / ln(K): 1 puts all mass on one label, and 0 is uniform. A box reports the mean over its four edges, each read to within a tenth of the image. Each box is one more read, counted in usage.reads. A field’s confidence is the probability of its value as written, and p_null is the probability that the state does not give it. Both are the model’s own. A value with a high p_null is a guess, and its confidence is low.

Errors

See Error Codes for the Gateway-wide envelope.

System One

Question types, images, boxes, confidence, and cost levers.

TypeSafe SDK Compatibility

Compatibility matrix and migration steps.

List Models

The current TypeSafe-compatible models on the /typesafe route.

Chat Completions

OCR, VQA, and document inference when you need generated text.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

The body of POST /typesafe/v1/systemone.

state
required
model
string
required
questions
Questions · object
required

Typed questions to answer, keyed by caller id. At most 16 per decision.

assets
Assets · object | null

Images for this request, keyed by the reference that stands for each one. A reference is replaced by its image wherever it appears in the state, in a question's instructions or in its criteria; an asset nothing references is a 422.

content
(TextPart · object | ImageUrlPart · object | FilePart · object | DocumentUrlPart · object)[] | null

Media for this request, as OpenAI content parts: image_url (max 8, data:image/…;base64 or http(s), ≤5 MB each), or one file or document_url PDF whose first document_max_pages (≤16) pages are read as images. Text is read after the state.

{"type": "text", "text": ...} — appended after the state.

document_max_pages
integer | null

Pages of the document to read, from the first. Default and maximum 16.

Required range: 1 <= x <= 16
document_pages
(integer | object)[] | null

Which pages to read, 0-indexed: page indices or half-open [start, stop] ranges, negative counting from the end, read in the order given. Unset reads from the first page. document_max_pages caps the selection.

Minimum array length: 1
document_dpi
integer | null

Resolution the document's pages are rendered at. Default 96; raise it for small or faint print.

Required range: 72 <= x <= 400
reasoning_effort
enum<string> | null
Available options:
none,
minimal,
low,
medium,
high
steps
integer | null

Denoise steps per read; Jev's contract is 1.

Required range: 1 <= x <= 8
samples
integer | null

Fixed number of noise draws to average. Unset: one read, re-read on high entropy.

Required range: 1 <= x <= 32

Response

Successful Response

model
string
required
answers
Answers · object
required
usage
Usage · object
required

Jev's two counters, plus what the gateway bills for them.

cost is this gateway's addition. TypeSafe's decoder ignores a field it does not model, so the official SDK still parses the response; a client that reads the raw JSON (the vlmrun CLI) can show the price of a read.

id
string