TypeSafe SDK Compatibility

The Gateway serves TypeSafe’s Jev API under /typesafe. The client appends /v1/systemone and /v1/models to its base URL. There is no mapping layer. Requests are not rewritten.

Pointing the SDK at the Gateway

Set three environment variables. On Python 3.14+ and Node.js 22.15+, also turn off request compression: see No zstd request bodies.

export TYPESAFE_BASE_URL="https://gateway.vlm.run/typesafe"
export TYPESAFE_API_KEY="<VLMRUN_API_KEY>"

# Required. The SDKs default to `jev-latest`, which this route does not
# serve, so a client that does not name a model gets a 404 on every call.
export TYPESAFE_DEFAULT_MODEL="google/diffusiongemma-26b-a4b-it"

pip install typesafe-sdk

npm install @typesafe-ai/sdk

Both SDKs read TYPESAFE_DEFAULT_MODEL. Pass model per client or per call. Any served id works. See Models.

Compatibility matrix

Feature	Status	Notes
`POST /v1/systemone`	Same	Identical request and response shapes.
`GET /v1/models`	Same	Jev’s `{name, description, release_date}` cards.
Question types (`noul`, `choice`, `score`)	Same	Including `legend`, `probabilities`, and `confidence`.
`box` questions	Same	Served by every model on this route. `jev-preview` is not served. Preview quality: see Locate with a box.
`assets`	Same	Inline `data_base64` or a multipart upload, so `typesafe_sdk.Image` works unchanged. Rejections are `422`, where TypeSafe answers `400` or `413`.
`x-typesafe-request-id` header	Same	Mirrors the Gateway’s `x-request-id`.
`usage.input_tokens` / `output_tokens`	Same	`output_tokens` is 0 on a diffusion read; a generative read reports what it wrote.
Error envelopes	Same	`422` validation lists, `404`, `429`, `503`, `529`.
`content`	Extended	Not in Jev. Content parts (`image_url`, `file`, `document_url`, `text`) carrying this request’s media.
`steps`, `samples`	Same	1 to 8 and 1 to 32.
`reasoning_effort`	Extended	Not in Jev. Generative engines only; `none` by default.
`jev-latest`	Not supported	No catch-all alias. Name a served id, or the request is a `404`.
`usage.cost`, `usage.reads`, `usage.input_tokens_details`	Extended	Not in Jev. The SDK’s decoder ignores them, so an unmodified client still parses the response.
`WS /v1/ws/systemone`	Extended	Not in Jev. The same decisions per frame over one socket. `WS /typesafe/ws` is a deprecated alias.
`think`	Not supported	A generation pass is the opposite of a low-latency read.
`sequential`	Not supported	Question groups are read in parallel, unconditioned.

See all 16 rowsShow less

Things worth knowing

What	Why it matters
Probabilities differ	They come from a different model. Revalidate any threshold you tuned on TypeSafe before relying on it here.
Strict bodies	An unknown field is a `422`, where Jev ignores it, so a typo surfaces instead of being dropped.
No zstd request bodies	The SDKs compress bodies over 1 KB with zstd on Python 3.14+ (or the `zstd` extra) and Node.js 22.15+. The Gateway does not decode them yet. Pass `compression=False` (Python) or `compression: false` (Node.js) to the client.
Choice ceiling	2 to 128 labels per `choice`. Jev allows up to 255.
Automatic re-reads are off	Upstream re-reads on high entropy; here that costs ~3.5x the latency for probabilities that move 0.2 or less. Use `samples` to average, and note every draw is billed.
Auth and quotas are the Gateway’s	Upstream API keys and origin secrets do not apply. See Authentication and Rate Limits.

Check the connection

from typesafe_sdk import TypeSafeClient

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

for model in client.models.list().models:
    print(model.name, model.release_date)

import { TypeSafeClient } from "@typesafe-ai/sdk";

const client = new TypeSafeClient({
  apiKey: process.env.VLMRUN_API_KEY,
  baseURL: "https://gateway.vlm.run/typesafe",
});

for (const model of await client.models.list()) {
  console.log(model.name, model.release_date);
}

curl https://gateway.vlm.run/typesafe/v1/models \
  -H "Authorization: Bearer $VLMRUN_API_KEY"

A list of served models means the base URL and key are right. See List Models for the response shape.

System One

Question types, images, confidence, and cost levers.

System One API

Read the request and response reference.

Overview

Platform

OpenAI Compatibility

TypeSafe Compatibility

Realtime

MCP

Misc

TypeSafe SDK Compatibility

Pointing the SDK at the Gateway

Compatibility matrix

Things worth knowing

Check the connection

System One

System One API

​Pointing the SDK at the Gateway

​Compatibility matrix

​Things worth knowing

​Check the connection

​Related

System One

System One API

Pointing the SDK at the Gateway

Compatibility matrix

Things worth knowing

Check the connection

Related