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",
)
page = base64.b64encode(pathlib.Path("invoice-page.jpg").read_bytes()).decode()
result = client.system_one(
"Answer about the attached page.",
{
"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.usage.input_tokens)
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",
});
const page = readFileSync("invoice-page.jpg").toString("base64");
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, usage } = await client.systemOne(request);
console.log(answers.kind.choice, usage.input_tokens);
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" --json
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
{
"id": "sysone-b317f2c7606c47c4975ba08166260",
"model": "google/diffusiongemma-26b-a4b-it",
"answers": {
"kind": {
"type": "choice",
"choice": "receipt",
"probabilities": {
"invoice": 0.0022535559303185626,
"receipt": 0.9966860953386762,
"contract": 0.0003855850269454288,
"other": 0.0006747637040598201
},
"confidence": 0.9819649256633525
},
"has_total": {
"type": "noul",
"noul": 0.5214069077960607
},
"legibility": {
"type": "score",
"score": 1.9657897574947996,
"legend": {
"0": "unreadable",
"1": "partly legible",
"2": "clear"
},
"probabilities": {
"0": 0.0020463012728342026,
"1": 0.030117639959532254,
"2": 0.9678360587676337
},
"confidence": 0.8636438424763118
}
},
"usage": {
"input_tokens": 417,
"output_tokens": 0,
"input_tokens_details": {
"cached_tokens": 32,
"image_tokens": 280,
"text_tokens": 137
},
"reads": 1,
"cost": 0.001
}
}
{
"detail": [
{
"type": "dict_type",
"loc": ["body", "questions"],
"msg": "Input should be a valid dictionary",
"input": "bad"
}
]
}
System One
Typed, calibrated decisions over text, JSON, and images
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",
)
page = base64.b64encode(pathlib.Path("invoice-page.jpg").read_bytes()).decode()
result = client.system_one(
"Answer about the attached page.",
{
"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.usage.input_tokens)
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",
});
const page = readFileSync("invoice-page.jpg").toString("base64");
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, usage } = await client.systemOne(request);
console.log(answers.kind.choice, usage.input_tokens);
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" --json
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
{
"id": "sysone-b317f2c7606c47c4975ba08166260",
"model": "google/diffusiongemma-26b-a4b-it",
"answers": {
"kind": {
"type": "choice",
"choice": "receipt",
"probabilities": {
"invoice": 0.0022535559303185626,
"receipt": 0.9966860953386762,
"contract": 0.0003855850269454288,
"other": 0.0006747637040598201
},
"confidence": 0.9819649256633525
},
"has_total": {
"type": "noul",
"noul": 0.5214069077960607
},
"legibility": {
"type": "score",
"score": 1.9657897574947996,
"legend": {
"0": "unreadable",
"1": "partly legible",
"2": "clear"
},
"probabilities": {
"0": 0.0020463012728342026,
"1": 0.030117639959532254,
"2": 0.9678360587676337
},
"confidence": 0.8636438424763118
}
},
"usage": {
"input_tokens": 417,
"output_tokens": 0,
"input_tokens_details": {
"cached_tokens": 32,
"image_tokens": 280,
"text_tokens": 137
},
"reads": 1,
"cost": 0.001
}
}
{
"detail": [
{
"type": "dict_type",
"loc": ["body", "questions"],
"msg": "Input should be a valid dictionary",
"input": "bad"
}
]
}
state. For the concepts, see System One. To migrate a client, see TypeSafe SDK Compatibility. Authentication is optional: see Authentication and Rate Limits.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
model | string | Yes | A served id or one of its aliases. An id the deployment does not serve is a 404. See Models. |
state | string | object | array | Yes | What the questions are about. Objects and arrays are sent as JSON. |
questions | object | Yes | A map of question id to question, at least one. Ids key the answers and never reach the model. |
content | array | string | No | This request’s media as content parts. A bare string is one text part. |
reasoning_effort | string | No | Generative engines only: none (default), minimal, or low, for 0, 32, or 64 reasoning tokens. A diffusion engine rejects it with 422. |
steps | integer | No | Diffusion engines only: denoise steps per read, 1 to 8. Default 1. |
samples | integer | No | Noise draws to average, 1 to 32. Every draw is billed. Default: one read. |
422.
Question object
| Field | Type | Description |
|---|---|---|
type | "noul" | "choice" | "score" | The question category. It selects the criteria and answer shape. |
instructions | string | object | array | Optional. What the question asks. |
criteria | object | array | Depends on type. |
type | criteria | Required |
|---|---|---|
noul | {"true": description, "false": description} | No |
choice | A map of label to description or null, 2 to 128 entries. | Yes |
score | An ordered array of 2 to 10 level descriptions. | Yes |
Content parts
content is a flat list: media first, then state. There are no roles and no history.
| Part | Shape | Limit |
|---|---|---|
image_url | {"type": "image_url", "image_url": {"url": "…", "detail": "high"}} | 8 per request, 5 MB each. url is a data: or http(s) URL. |
document_url | {"type": "document_url", "document_url": {"url": "…", "detail": "high"}} | 1 document per request. A PDF, as an http(s) URL. |
text | {"type": "text", "text": "…"} | Read after state. |
file | {"type": "file", "file": {"filename": "invoice.pdf", "file_data": "…", "detail": "high"}} | The same PDF as document_url, in the OpenAI file shape. file_data is a data:application/pdf;base64, or http(s) URL. filename is optional. |
422.detail | Vision tokens per image or page |
|---|---|
auto (default), high | 280 |
low | 70 |
high or auto part sets every image and page in the request to 280 tokens.
Response
| Field | Type | Description |
|---|---|---|
model | string | The model that answered. |
answers | object | Answers keyed by question id. |
usage.input_tokens | integer | Prompt tokens across every read. Counts toward your quota. |
usage.output_tokens | integer | 0 on a diffusion read. Non-zero on a generative read, which writes the answer under a grammar. |
usage.input_tokens_details | object | cached_tokens, image_tokens, and text_tokens. Gateway extension. image_tokens follows the detail budget, since the engine reports no image and text split. |
usage.reads | integer | Engine calls made: one per question group, times samples. Gateway extension. |
usage.cost | number | USD at the model’s published rate, with cached tokens at the cache rate. Gateway extension. |
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
type | Fields |
|---|---|
noul | noul: P(yes), from 0 to 1. |
choice | choice (the winning label), probabilities (label to probability), confidence. |
score | score (the expected level, sum(i * p_i)), legend, probabilities, confidence. |
confidence is 1 - H(p) / ln(K): 1 puts all mass on one label, and 0 is uniform.
Errors
| Status | error_type | When |
|---|---|---|
422 | validation list | An invalid body, an unknown field, or a schema the model cannot answer. The body is {"detail": [{"type", "loc", "msg", "input"}]}. |
404 | not_found_error | model is not served on this route. |
429 | rate limit | The per-tier quota is exceeded. |
503 | api_error | The engine is unreachable or failed. Sent with retry-after: 2. |
529 | overloaded_error | Too many reads are queued. Sent with retry-after: 1. |
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",
)
page = base64.b64encode(pathlib.Path("invoice-page.jpg").read_bytes()).decode()
result = client.system_one(
"Answer about the attached page.",
{
"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.usage.input_tokens)
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",
});
const page = readFileSync("invoice-page.jpg").toString("base64");
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, usage } = await client.systemOne(request);
console.log(answers.kind.choice, usage.input_tokens);
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" --json
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
{
"id": "sysone-b317f2c7606c47c4975ba08166260",
"model": "google/diffusiongemma-26b-a4b-it",
"answers": {
"kind": {
"type": "choice",
"choice": "receipt",
"probabilities": {
"invoice": 0.0022535559303185626,
"receipt": 0.9966860953386762,
"contract": 0.0003855850269454288,
"other": 0.0006747637040598201
},
"confidence": 0.9819649256633525
},
"has_total": {
"type": "noul",
"noul": 0.5214069077960607
},
"legibility": {
"type": "score",
"score": 1.9657897574947996,
"legend": {
"0": "unreadable",
"1": "partly legible",
"2": "clear"
},
"probabilities": {
"0": 0.0020463012728342026,
"1": 0.030117639959532254,
"2": 0.9678360587676337
},
"confidence": 0.8636438424763118
}
},
"usage": {
"input_tokens": 417,
"output_tokens": 0,
"input_tokens_details": {
"cached_tokens": 32,
"image_tokens": 280,
"text_tokens": 137
},
"reads": 1,
"cost": 0.001
}
}
{
"detail": [
{
"type": "dict_type",
"loc": ["body", "questions"],
"msg": "Input should be a valid dictionary",
"input": "bad"
}
]
}
Related
System One
TypeSafe SDK Compatibility
List Models
/typesafe route.Chat Completions
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
The body of POST /typesafe/v1/systemone.
Typed questions to answer, keyed by caller id. At most 16 per decision.
Hide child attributes
Hide child attributes
A yes/no question. The answer is P(yes).
- NoulQuestion
- ChoiceQuestion
- ScoreQuestion
Hide child attributes
Hide child attributes
"noul"Media for this request, as OpenAI content parts: image_url (max 8, data:image/…;base64 or http(s), ≤5 MB each) and one file, whose first 8 pages are read as images. Text is read after the state.
none, minimal, low, medium, high Denoise steps per read; Jev's contract is 1.
1 <= x <= 8Fixed number of noise draws to average. Unset: one read, re-read on high entropy.
1 <= x <= 32Response
Successful Response
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.
Hide child attributes
Hide child attributes
What the prompt was made of, in the shape the chat route reports usage.
cached_tokens is the engine's own count (the schema prompt repeats, so a
warm replica serves most of it from the prefix cache). image_tokens is
derived from the budget this request applied, since the engine reports no
image/text split; text_tokens is the remainder.