System One

Chat models are strong at text and weak at automation. Code that branches on a model needs a label it can trust. A chat model returns a string that you must parse and validate, states its confidence loosely, and generates one token at a time. That is too slow and too loose for a request path. TypeSafe introduced System One models, starting with Jev, for this gap. You send a block of state and a set of typed questions. The model answers all of them in parallel as typed values, each with a calibrated probability. Classify, route, score, and guard become if statements over probabilities. The state that drives automation is often pixels: a scanned page, a camera frame, a product photo. Today an image decision goes through a VLM that writes a sentence, and you parse it. Jev was released for text and structured state. The Gateway applies the same contract to images. POST /typesafe/v1/systemone answers typed questions about a state (text, JSON, or images) in one forward pass. Each answer is one of your labels with a calibrated probability. Nothing is generated or parsed, so an answer cannot be off-schema. Over a socket the measured p50 is ~44 ms. Edit criteria to change the question. The route is wire-compatible with TypeSafe’s Jev API. Point the typesafe-sdk client at https://gateway.vlm.run/typesafe. It works unchanged. See TypeSafe SDK Compatibility. The VLM Run SDKs also wrap the route as client.gateway.systemone, with friendly question specs and media helpers: see the Python and Node.js references.

Quickstart

Set detail to high for small print.

import base64, pathlib
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient(
    api_key="<VLMRUN_API_KEY>",
    base_url="https://gateway.vlm.run/typesafe",
    compression=False,
)

page = base64.b64encode(pathlib.Path("invoice-page.jpg").read_bytes()).decode()

result = client.system_one(
    state="Answer about the attached page.",
    questions={
        "kind": Choice(
            instructions="What kind of document is this page from?",
            criteria={"invoice": None, "receipt": None, "contract": None, "other": None},
        ),
        "has_total": Noul(instructions="Is a total amount due visible on the page?"),
        "legibility": Score(
            instructions="How legible is the text?",
            criteria=["unreadable", "partly legible", "clear"],
        ),
    },
    extra_body={
        "content": [
            {
                "type": "image_url",
                "image_url": {
                    "url": f"data:image/jpeg;base64,{page}",
                    "detail": "high",
                },
            }
        ]
    },
    model="google/diffusiongemma-26b-a4b-it",
)

print(result.choices["kind"].choice, result.nouls["has_total"].noul)

import { readFileSync } from "node:fs";
import { choice, noul, score, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.VLMRUN_API_KEY,
  baseURL: "https://gateway.vlm.run/typesafe",
  defaultModel: "google/diffusiongemma-26b-a4b-it",
  compression: false,
});

const page = readFileSync("invoice-page.jpg").toString("base64");

// Extra fields such as `content` are forwarded from a request variable.
// An inline object literal would trip TypeScript's excess-property check.
const request = {
  state: "Answer about the attached page.",
  questions: {
    kind: choice("What kind of document is this page from?", {
      invoice: null,
      receipt: null,
      contract: null,
      other: null,
    }),
    has_total: noul("Is a total amount due visible on the page?"),
    legibility: score("How legible is the text?", [
      "unreadable",
      "partly legible",
      "clear",
    ]),
  },
  content: [
    { type: "image_url",
      image_url: { url: `data:image/jpeg;base64,${page}`, detail: "high" } },
  ],
};

const { answers } = await client.systemOne(request);
console.log(answers.kind.choice, answers.has_total.noul);

vlmrun gw s1 -s "Answer about the attached page." invoice-page.jpg --detail high \
  -m google/diffusiongemma-26b-a4b-it \
  --choice kind="invoice|receipt|contract|other" \
  --noul has_total="Is a total amount due visible on the page?" \
  --score legibility="unreadable|partly legible|clear"

IMAGE=$(base64 -w0 invoice-page.jpg)

curl https://gateway.vlm.run/typesafe/v1/systemone \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "model": "google/diffusiongemma-26b-a4b-it",
  "state": "Answer about the attached page.",
  "content": [
    {"type": "image_url",
     "image_url": {"url": "data:image/jpeg;base64,$IMAGE", "detail": "high"}}
  ],
  "questions": {
    "kind": {
      "type": "choice",
      "instructions": "What kind of document is this page from?",
      "criteria": {"invoice": null, "receipt": null, "contract": null, "other": null}
    },
    "has_total": {"type": "noul", "instructions": "Is a total amount due visible on the page?"},
    "legibility": {
      "type": "score",
      "instructions": "How legible is the text?",
      "criteria": ["unreadable", "partly legible", "clear"]
    }
  }
}
JSON

Response

{
  "id": "sysone-da6b13ba5c154898acc5f2ef0a83d",
  "model": "google/diffusiongemma-26b-a4b-it",
  "answers": {
    "kind": {
      "type": "choice",
      "choice": "receipt",
      "probabilities": {
        "invoice": 0.0012777051171866563,
        "receipt": 0.9953490010884637,
        "contract": 0.0005516407460048453,
        "other": 0.002821653048344803
      },
      "confidence": 0.9755779215329374
    },
    "has_total": { "type": "noul", "noul": 0.9880775186094307 },
    "legibility": {
      "type": "score",
      "score": 1.970138484786883,
      "legend": { "0": "unreadable", "1": "partly legible", "2": "clear" },
      "probabilities": { "0": 0.000883016397488224, "1": 0.028095482418140645, "2": 0.9710215011843711 },
      "confidence": 0.8770037389763032
    }
  },
  "usage": {
    "input_tokens": 417,
    "output_tokens": 0,
    "input_tokens_details": { "cached_tokens": 32, "image_tokens": 280, "text_tokens": 137 },
    "reads": 1,
    "cost": 0.001
  }
}

Models

Name the model on the request. The response reports the id that answered. See Models.

When to use a read

Ask	Use	Why
”Is this scanned page an invoice?”	System One	One calibrated probability, never off-schema.
”Which of these 6 kinds is this scan?”	System One	Full distribution over labels, plus a confidence.
”Should I run the expensive extraction pass?”	System One	Cheap gate ahead of OCR or structured extraction.
”Where is the total on this receipt?”	System One `box`	Four edges in one extra read. Preview quality.
”What are the invoice number, date, and total?”	System One fields	Typed values, all decoded at once, each with a confidence.
”Transcribe this page to markdown”	Chat Completions	The answer is free-form text, not a label.
”Summarize this video”	Chat Completions	Generation, not a decision.

A read costs the prompt prefill plus one forward pass. Generating the same answer pays a full decode plus parsing. The parse can still fail.

Question types

`type`	Ask it when	You get back
`noul`	The answer is yes or no.	A probability that the answer is yes.
`choice`	The answer is one label from a fixed set.	The winning label, a probability for every label, and a confidence.
`score`	The answer is a level on an ordered scale.	The expected level, a legend, per-level probabilities, and a confidence.
`box`	You need where something is in an image.	Four edges, each from 0 to 1 of the image, and a confidence. See Locate with a box.
`text`, `number`, `date`, `list`	You need a value from the state.	The value as its type or `null`, its confidence, and the probability that it is absent. See Extract fields.

A score is the expected level. A 3-level question returns a number from 0 to 2. For the exact criteria and limits, see the request reference.

Confidence

confidence runs from 1 (all mass on one label) to 0 (uniform). Threshold it to route the case to a human or a larger model. Document Classification is a full routing example.

Probabilities are the model’s own at temperature 1. They are not a parsed guess. They are model-specific. Revalidate your thresholds when you change models.

Inputs

Send media one of two ways:

content: OpenAI content parts, as below. Use it when your code already sends chat completions.
assets: images keyed by a reference you write into state or a question. Use it with the typesafe-sdk Image type. See Images as assets.

Media goes in one or the other. Images or a document in content together with assets is a 422. text parts work with either. content is a list of content parts. Each part names its type. One list can carry images, a document, and text.

Content part	Limit	Notes
`image_url`	8 per request, 5 MB each	JPEG, PNG, WebP, or GIF, as a `data:` or `http(s)` URL.
`file` or `document_url`	1 document per request	A PDF. Its first 16 pages are rasterised for you at 96 DPI. Set `document_max_pages` to read fewer, `document_pages` to pick pages, and `document_dpi` for small print.
`text`	any	Read after the `state`.

Put media parts first and the state after them. A bare string in content counts as one text part.

Send images or one document, never both: A document’s pages become the read’s images. Sending both is a 422.

A read has no roles and no message array. It denoises a single canvas over a single state, so there is no turn to address and no history to carry.

The detail field sets how closely the model reads each image.

Default auto: 280 vision tokens.
"detail": "low": 70 vision tokens. 4x fewer billed image tokens. Same latency. Usually enough for classifying or routing.
The cap applies per request. One high or auto part lifts the whole read.

For accepted part shapes and the full detail table, see the request reference.

Classify a PDF

Set file_data to a base64 data URL or an http(s) URL.

import base64, pathlib
from typesafe_sdk import Choice, Noul, TypeSafeClient

client = TypeSafeClient(
    api_key="<VLMRUN_API_KEY>",
    base_url="https://gateway.vlm.run/typesafe",
    compression=False,
)

pdf = base64.b64encode(pathlib.Path("invoice.pdf").read_bytes()).decode()

result = client.system_one(
    state="Answer about the document.",
    questions={
        "kind": Choice(
            instructions="What kind of document is this?",
            criteria={"invoice": None, "contract": None, "report": None, "other": None},
        ),
        "has_total": Noul(instructions="Is a total amount due visible?"),
    },
    extra_body={
        "content": [
            {
                "type": "file",
                "file": {
                    "filename": "invoice.pdf",
                    "file_data": f"data:application/pdf;base64,{pdf}",
                    "detail": "high",
                },
            }
        ]
    },
    model="google/diffusiongemma-26b-a4b-it",
)

print(result.choices["kind"].choice)

import { readFileSync } from "node:fs";
import { choice, noul, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.VLMRUN_API_KEY,
  baseURL: "https://gateway.vlm.run/typesafe",
  defaultModel: "google/diffusiongemma-26b-a4b-it",
  compression: false,
});

const pdf = readFileSync("invoice.pdf").toString("base64");

const request = {
  state: "Answer about the document.",
  questions: {
    kind: choice("What kind of document is this?", {
      invoice: null,
      contract: null,
      report: null,
      other: null,
    }),
    has_total: noul("Is a total amount due visible?"),
  },
  content: [
    { type: "file",
      file: { filename: "invoice.pdf",
              file_data: `data:application/pdf;base64,${pdf}`,
              detail: "high" } },
  ],
};

const { answers } = await client.systemOne(request);
console.log(answers.kind.choice);

vlmrun gw s1 -s "Answer about the document." invoice.pdf --detail high \
  -m google/diffusiongemma-26b-a4b-it \
  --choice kind="invoice|contract|report|other" \
  --noul has_total="Is a total amount due visible?"

PDF=$(base64 -w0 invoice.pdf)

curl https://gateway.vlm.run/typesafe/v1/systemone \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "model": "google/diffusiongemma-26b-a4b-it",
  "state": "Answer about the document.",
  "content": [
    {"type": "file",
     "file": {"filename": "invoice.pdf",
              "file_data": "data:application/pdf;base64,$PDF",
              "detail": "high"}}
  ],
  "questions": {
    "kind": {
      "type": "choice",
      "instructions": "What kind of document is this?",
      "criteria": {"invoice": null, "contract": null, "report": null, "other": null}
    },
    "has_total": {"type": "noul", "instructions": "Is a total amount due visible?"}
  }
}
JSON

A PDF longer than 16 pages is answered from its opening pages. That covers classifying or routing. Reading every page of a long document uses the Gateway’s per-page document pipeline.

Images as assets

assets is TypeSafe’s image format. List each image once, keyed by a reference string. Write the reference where the image belongs: in state, in a question’s instructions, or in its criteria. The model sees [image N] at that place.

Rule	Behavior
Placement	A reference is replaced inside any string of `state`, `instructions`, or `criteria`. Object keys (question ids, `choice` labels) stay text.
Criteria	A `choice` label, a `score` level, or a `noul` `true` / `false` can be described by an image.
Reuse	An image is sent once, however often its reference appears.
References	Use a unique string per request, for example `<image:uuid>`. A short reference can match inside a longer word.
Inline	`data_base64` plus `format` (`png`, `jpg`, or `jpeg`). `format` is required with `data_base64`.
Upload	`multipart/form-data`: the JSON body in a part named `request`, each image in the part its asset names in `part`. The `typesafe-sdk` `Image` type does this for you.
`detail`	Per asset. Same values and budgets as an `image_url` part.
Limits	8 images per request, 5 MB each. A reference is at most 1 KB.

Unused assets and bad image data are 422s. TypeSafe answers some of these with 400 or 413.

Locate with a box

A box question asks where something is. The answer is four edges as fractions of the image: top and bottom of its height, left and right of its width, from the top-left corner.

import pathlib
from typesafe_sdk import Box, Image, Noul, TypeSafeClient

client = TypeSafeClient(
    api_key="<VLMRUN_API_KEY>",
    base_url="https://gateway.vlm.run/typesafe",
    compression=False,
)

receipt = Image(pathlib.Path("receipt.jpg"))

result = client.system_one(
    state={"receipt": receipt},
    questions={
        "has_total": Noul(instructions="Is a total amount visible on the receipt?"),
        "total": Box(instructions="The TOTAL line on the receipt"),
    },
    model="qwen/qwen3.8-27b",
)

total = result.boxes["total"]
print(result.nouls["has_total"].noul, total.box, total.confidence)

import { openAsBlob } from "node:fs";
import { box, image, noul, TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.VLMRUN_API_KEY,
  baseURL: "https://gateway.vlm.run/typesafe",
  defaultModel: "qwen/qwen3.8-27b",
  compression: false,
});

const receipt = image(await openAsBlob("receipt.jpg"));

const { answers } = await client.systemOne({
  state: { receipt },
  questions: {
    has_total: noul("Is a total amount visible on the receipt?"),
    total: box("The TOTAL line on the receipt"),
  },
});

const { top, bottom, left, right } = answers.total.box;
console.log(answers.has_total.noul, top, bottom, left, right, answers.total.confidence);

IMAGE=$(base64 -w0 receipt.jpg)

curl https://gateway.vlm.run/typesafe/v1/systemone \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- <<JSON
{
  "model": "qwen/qwen3.8-27b",
  "state": {"receipt": "<image:receipt-1>"},
  "assets": {
    "<image:receipt-1>": {"type": "image", "format": "jpeg", "data_base64": "$IMAGE"}
  },
  "questions": {
    "has_total": {"type": "noul", "instructions": "Is a total amount visible on the receipt?"},
    "total": {"type": "box", "instructions": "The TOTAL line on the receipt"}
  }
}
JSON

Response

{
  "id": "sysone-434135e7ceeb4609a8f15b366f65c",
  "model": "qwen/qwen3.8-27b",
  "answers": {
    "has_total": { "type": "noul", "noul": 0.999948557767968 },
    "total": {
      "type": "box",
      "box": { "top": 0.3415, "bottom": 0.3711, "left": 0.4948, "right": 0.8353 },
      "confidence": 0.9257974413506623
    }
  },
  "usage": {
    "input_tokens": 6319,
    "output_tokens": 18,
    "input_tokens_details": { "cached_tokens": 0, "image_tokens": 560, "text_tokens": 5759 },
    "reads": 2,
    "cost": 0.002258
  }
}

The samples set compression to false. The Gateway does not decode zstd request bodies yet. Both SDKs send zstd by default on Python 3.14+ (or the zstd extra) and Node.js 22.15+, for bodies over 1 KB.

To convert to pixels, multiply top and bottom by the image height, and left and right by the image width.


Image	The request’s image, from `assets`, an `image_url` part, or a PDF’s pages. A box with no image is a `422`.
`instructions`	Optional. Name the target. It can hold an asset reference (“the person matching this badge: `<ref>`”). Without it, the read locates the image’s subject.
`criteria`	Not accepted. Sending it is a `422`.
Edges	Expected values, so a read split between two positions answers between them. `top` < `bottom` and `left` < `right`, always.
`confidence`	From 0 to 1. How sure the model is of each edge to within a tenth of the image.
Cost	Each box is one more read that carries the request’s images. `usage.reads` counts it.
Limit	8 boxes per request, within the 16-question limit.

Box answers are a preview. Localization quality is not yet benchmarked. In spot checks, edges are often accurate but one edge can miss, even at high confidence. Check boxes on your own images before you branch on them.

Pair a box with labelled questions as needed: a noul for “is it there at all”, or a choice of none, one, and several. A box needs no other question beside it.

Extract fields

A question of type text, number, date, or list is a field to extract. The answer is a typed value with the probability that it is right and the probability that the state does not give it. You never parse a string. All fields are decoded at once. They share one prompt, which the engine reads once. Each field then writes only its own value. A request takes about as long as its longest value. A JSON completion writes every key, quote, and value in order. See Field Extraction for measured numbers and a text, image, and PDF walkthrough.

import httpx

invoice = """INVOICE INV-2291
Northwind Traders, 12 Market Street
Issued: 3 March 2026
Item      Qty    Amount
Widget      2   $400.00
Gasket      5   $804.50
Total due: $1,204.50"""

answers = httpx.post(
    "https://gateway.vlm.run/typesafe/v1/systemone",
    headers={"Authorization": "Bearer <VLMRUN_API_KEY>"},
    json={
        "model": "qwen/qwen3.8-27b",
        "state": invoice,
        "questions": {
            "invoice_number": {"type": "text", "instructions": "The invoice number"},
            "issued": {"type": "date", "instructions": "The date the invoice was issued"},
            "total": {"type": "number", "decimals": 2, "instructions": "The amount due"},
            "items": {"type": "list", "items": "text", "instructions": "The description of each line item"},
            "po_number": {"type": "text", "instructions": "The purchase order number"},
        },
    },
    timeout=60,
).json()["answers"]

print(answers["total"]["value"], answers["total"]["confidence"])

const invoice = `INVOICE INV-2291
Northwind Traders, 12 Market Street
Issued: 3 March 2026
Item      Qty    Amount
Widget      2   $400.00
Gasket      5   $804.50
Total due: $1,204.50`;

const res = await fetch("https://gateway.vlm.run/typesafe/v1/systemone", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VLMRUN_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "qwen/qwen3.8-27b",
    state: invoice,
    questions: {
      invoice_number: { type: "text", instructions: "The invoice number" },
      issued: { type: "date", instructions: "The date the invoice was issued" },
      total: { type: "number", decimals: 2, instructions: "The amount due" },
      items: { type: "list", items: "text", instructions: "The description of each line item" },
      po_number: { type: "text", instructions: "The purchase order number" },
    },
  }),
});

const { answers } = await res.json();
console.log(answers.total.value, answers.total.confidence);

curl https://gateway.vlm.run/typesafe/v1/systemone \
  -H "Authorization: Bearer $VLMRUN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen/qwen3.8-27b",
    "state": "INVOICE INV-2291\nNorthwind Traders, 12 Market Street\nIssued: 3 March 2026\nItem      Qty    Amount\nWidget      2   $400.00\nGasket      5   $804.50\nTotal due: $1,204.50",
    "questions": {
      "invoice_number": {"type": "text", "instructions": "The invoice number"},
      "issued": {"type": "date", "instructions": "The date the invoice was issued"},
      "total": {"type": "number", "decimals": 2, "instructions": "The amount due"},
      "items": {"type": "list", "items": "text", "instructions": "The description of each line item"},
      "po_number": {"type": "text", "instructions": "The purchase order number"}
    }
  }'

Response

{
  "id": "sysone-c40d4bc7c7fa484ba4b9d5a6fc942",
  "model": "qwen/qwen3.8-27b",
  "answers": {
    "invoice_number": { "type": "text", "value": "INV-2291", "confidence": 0.999998, "p_null": 0.0, "span": [8, 16], "spans": null },
    "issued": { "type": "date", "value": "2026-03-03", "confidence": 0.973021, "p_null": 0.020908, "span": null, "spans": null },
    "total": { "type": "number", "value": 1204.5, "confidence": 0.99896, "p_null": 4e-06, "span": null, "spans": null },
    "items": { "type": "list", "value": ["Widget", "Gasket"], "confidence": 0.998827, "p_null": 1e-06, "span": null, "spans": [[98, 104], [122, 128]] },
    "po_number": { "type": "text", "value": null, "confidence": 1.0, "p_null": 1.0, "span": null, "spans": null }
  },
  "usage": {
    "input_tokens": 1219,
    "output_tokens": 42,
    "input_tokens_details": { "cached_tokens": 0, "image_tokens": 0, "text_tokens": 1219 },
    "reads": 5,
    "cost": 0.001
  }
}

The typesafe-sdk clients decode only Jev’s answer types. Read fields with any HTTP client, as above.


`text`	Text from the state, as written.
`number`	A number read or computed from the state, without separators or units. `decimals` rounds it. `0` returns an integer.
`date`	A calendar date, as `YYYY-MM-DD`, whatever format the state writes it in.
`list`	Every match in the state, in order. `items` is `text` (default), `number`, or `date`.
`value`	Always the field’s type or `null`. A value that is not a valid instance of its type, such as February 30, is `null`.
`confidence`	The probability of the value exactly as returned.
`p_null`	The probability that the state does not give the field, from the model itself. A generative model writes its best value unless it is near-sure the field is absent, so a value with a high `p_null` is a guess with a low `confidence`. Decide on `p_null`, not on `value` alone.
`span`, `spans`	`[start, end)` of a `text` value, or of each `list` item, in a string `state`. Absent for an image, a PDF, a JSON `state`, or a value the model normalised.
Field id	The name the model writes the value under, so a readable id such as `invoice_number` helps. One line, no `:`.
Mixing	Fields and `noul`, `choice`, `score`, and `box` questions share one request and are read concurrently.
Cost	One read per field on a generative model, one read for all fields on `google/diffusiongemma-26b-a4b-it`. A value’s tokens are billed as output.
Models	Every System One model. A generative model decodes one short sequence per field, all at once. `google/diffusiongemma-26b-a4b-it` writes every field on one canvas in a single read, without a grammar; the Gateway parses each line, and `confidence` and `p_null` are `null`.

Streaming

WS /v1/ws/systemone answers the same questions per frame. Use it for a video or an image stream.

Questions: send them once.
Frames: each frame is raw binary.
Decisions: every decision carries the same answers and usage as a posted read.
Images: frames and content parts only. A socket does not take assets.

See Realtime System One. WS /typesafe/ws is a deprecated alias of the same socket.

Gateway extensions

Six optional fields extend Jev’s contract.

Field	Applies to	Notes
`reasoning_effort`	Generative engines	`none` (default), `minimal`, `low`, `medium`, or `high`: 0, 32, 64, 128, or 256 tokens of reasoning before the answer.
`steps`	Diffusion engines	Denoise steps per read, 1 to 8. Default `1`, which is Jev’s contract.
`samples`	Any	Noise draws to average, 1 to 32. Every draw is billed.
`document_max_pages`	Any	Pages of a PDF to read, from the first, 1 to 16. Default `16`.
`document_pages`	Any	Which PDF pages to read, 0-indexed, as indices or `[start, stop]` ranges. Same as on Chat Completions.
`document_dpi`	Any	Resolution PDF pages are rendered at, 72 to 400. Default `96`. Raise it for small or faint print.

reasoning_effort notes:

Default: off. A read is a prefill. A reasoning budget turns it into a generation.
Diffusion engines: reject any reasoning budget with a 422.
Qwen engines: can fail a read that has a reasoning budget, with a 502. Use google/gemma-4-26b-a4b-it.

See the request reference for ranges and defaults. Unknown fields return a 422.

Cost levers, in order of effect

Lever	Effect
Read, do not generate	One forward pass instead of a full decode plus a parse.
Ask the same questions of many states	The schema is prefix-cached, so a fixed question set pays its prefill once per replica.
Batch questions into one request	A request takes up to 16 questions. Short ones usually fit one read; more are grouped and read concurrently, one prefill each.
Set `detail: "low"` where the question allows	70 vision tokens instead of the default 280, so 4x fewer billed image tokens at the same latency.
Ask for a box only where you need one	Each `box` is one more read carrying every image in the request.
Leave `samples` unset	Averaging over noise draws multiplies cost without steadying a borderline answer. Sharpen `instructions` instead.

Next steps

System One API

Full request and response reference, plus error envelopes.

TypeSafe SDK Compatibility

Point an existing Jev client at the Gateway with three environment variables.

Chat Completions

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

Rate Limits

Per-tier quotas and how they apply to a read.

Realtime System One

WS /v1/ws/systemone, for per-frame decisions over video or an image stream.

CLI

vlmrun gw s1 for one-off reads, gates that guard a script, and dry runs.

Overview

Platform

OpenAI Compatibility

TypeSafe Compatibility

Realtime

MCP

Misc

Quickstart

Models

When to use a read

Question types

Confidence

Inputs

Classify a PDF

Images as assets

Locate with a box

Extract fields

Streaming

Gateway extensions

Cost levers, in order of effect

Next steps

System One API

TypeSafe SDK Compatibility

Chat Completions

Rate Limits

Realtime System One

CLI

​Quickstart

​Models

​When to use a read

​Question types

​Confidence

​Inputs

​Classify a PDF

​Images as assets

​Locate with a box

​Extract fields

​Streaming

​Gateway extensions

​Cost levers, in order of effect

​Next steps

System One API

TypeSafe SDK Compatibility

Chat Completions

Rate Limits

Realtime System One

CLI

Quickstart

Models

When to use a read

Question types

Confidence

Inputs

Classify a PDF

Images as assets

Locate with a box

Extract fields

Streaming

Gateway extensions

Cost levers, in order of effect

Next steps