The VLM Run Python SDK is the official Python SDK for VLM Run API platform, providing a convenient way to interact with our REST APIs.
🚀 Getting Started
Installation
pip install vlmrun
Installation with Optional Features
The package provides optional features that can be installed based on your needs:
-
Video processing features (numpy, opencv-python):
pip install "vlmrun[video]"
-
Document processing features (pypdfium2):
pip install "vlmrun[doc]"
-
Visualization and notebook helpers (pandas, IPython):
pip install "vlmrun[all]"
-
System One typed decisions (
typesafe-sdk):pip install "vlmrun[typesafe]"
-
All optional features:
pip install "vlmrun[all]"
The CLI and OpenAI-compatible gateway (vlmrun gw chat, vlmrun chat) work out of the box with pip install vlmrun.
System One — typed decisions
vlmrun gw systemone answers named questions about text, JSON, images and PDFs with
calibrated probabilities. Answers are read off the model in one denoise step, so nothing
is generated and nothing is parsed — an answer can never be off-schema. The route speaks
TypeSafe's contract, so it is driven by the official typesafe-sdk client
(pip install "vlmrun[typesafe]").
vlmrun gw systemone "Invoice #44 was charged twice, I need this fixed today" \
--noul is_urgent="Is the customer asking for something time-sensitive?" \
--choice department="billing|technical|sales" \
--score frustration="Calm|Frustrated|Very angry"
# questions as inline JSON (or @file.json, or - for stdin)
vlmrun gw systemone ticket.txt --json -Q '[
{"id": "is_urgent", "type": "noul"},
{"id": "department", "type": "choice", "options": ["billing", "technical", "sales"]}
]'
# images and one PDF ride along; --detail sets the vision budget
vlmrun gw systemone invoice.pdf --detail high --choice kind="invoice|receipt|contract"
From Python:
from vlmrun.client import VLMRun
client = VLMRun()
result = client.gateway.systemone.decide(
state="Invoice #44 was charged twice, I need this fixed today",
questions=[
{"id": "is_urgent", "type": "noul", "instructions": "Is this time-sensitive?"},
{"id": "department", "type": "choice", "options": ["billing", "technical", "sales"]},
],
)
result.nouls["is_urgent"].noul # 0.91
result.choices["department"].choice # "billing"
result.choices["department"].confidence # 0.71
Three flags make a read scriptable:
# --gate sets the exit code: 0 all passed, 1 a gate failed, 2 the request failed
vlmrun gw s1 invoice.pdf --choice kind="invoice|receipt|contract" \
--gate 'kind==invoice' --gate 'kind.confidence>0.9'
# --repeat sends the same request N times and reports mean and spread
vlmrun gw s1 ticket.txt --noul is_urgent --repeat 5
# --dry-run prints the request body without sending it (pipe it to curl)
vlmrun gw s1 scan.jpg --noul signed --dry-run
Several engines serve the route and there is no catch-all alias — vlmrun gw s1 models
lists what your gateway serves. Generative engines can think before answering:
vlmrun gw s1 models
vlmrun gw s1 ticket.txt -m google/gemma-4-26b-a4b-it \
--reasoning-effort medium --choice dept="billing|tax|technical"
vlmrun gw s1 is a shorthand for vlmrun gw systemone. See
vlmrun gw systemone --help for both question dialects, media rules and limits.
Basic Usage
from PIL import Image
from vlmrun.client import VLMRun
from vlmrun.common.utils import remote_image
# Initialize the client
client = VLMRun(api_key="<your-api-key>")
# Process an image using local file or remote URL
image: Image.Image = remote_image("https://storage.googleapis.com/vlm-data-public-prod/hub/examples/document.invoice/invoice_1.jpg")
response = client.image.generate(
images=[image],
domain="document.invoice"
)
print(response)
# Or process an image directly from URL
response = client.image.generate(
urls=["https://storage.googleapis.com/vlm-data-public-prod/hub/examples/document.invoice/invoice_1.jpg"],
domain="document.invoice"
)
print(response)
OpenAI-Compatible Chat Completions
The VLM Run SDK provides OpenAI-compatible chat completions through the agent endpoint. This allows you to use the familiar OpenAI API with VLM Run's powerful vision-language models.
from vlmrun.client import VLMRun
client = VLMRun(
api_key="your-key",
base_url="https://api.vlm.run/v1"
)
response = client.agent.completions.create(
model="vlmrun-orion-1",
messages=[
{"role": "user", "content": "Hello!"}
]
)
print(response.choices[0].message.content)
For async support:
import asyncio
from vlmrun.client import VLMRun
client = VLMRun(api_key="your-key", base_url="https://api.vlm.run/v1")
async def main():
response = await client.agent.async_completions.create(
model="vlmrun-orion-1",
messages=[{"role": "user", "content": "Hello!"}]
)
print(response.choices[0].message.content)
asyncio.run(main())
CLI Chat with Skills
The vlmrun chat command supports skills — local directories containing a SKILL.md and optional assets that give the agent domain-specific expertise. Skills are sent inline with each request (no server-side upload required).
# Chat with an inline skill
vlmrun chat "Generate a youtube thumbnail for a video using the VLM Run brand colors" -k ./path/to/vlmrun-branding/
# Attach multiple skills (coming soon)
vlmrun chat "Analyze this invoice" -i invoice.pdf -k ./accounting-skills/ -k ./invoice-extraction/
To create a persistent server-side skill, use vlmrun skills upload ./my-skill/.
Claude Code
Install the VLM Run CLI skill directly in Claude Code via the plugin marketplace in the vlm-run/skills repository:
- Register the repository as a plugin marketplace:
/plugin marketplace add vlm-run/skills
- Install the skill:
/plugin install vlmrun-cli-skill@vlm-run/skills
- Configure your API key and base URL using the CLI (get your key from app.vlm.run):
vlmrun config init
vlmrun config set --api-key <your-api-key>
vlmrun config show
- Verify the skill is loaded by asking Claude Code (requires restart):
What skills are available in the /vlmrun-cli-skill?
🔗 Quick Links
- 💬 Need help? Email us at support@vlm.run or join our Discord
- 📚 Check out our Documentation
- 📣 Follow us on Twitter and LinkedIn
Release files for vlmrun 0.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vlmrun-0.9.1.tar.gz | 158.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vlmrun-0.9.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 306.2 kB
Release files / vlmrun-0.9.1.tar.gz
| Download URL | vlmrun-0.9.1.tar.gz |
|---|---|
| Size | 158.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6cdf1382e6ab321749e915eab991f82a1c575debd7e7790402068a99b1d9ff34
|
|
BLAKE2b-256 checksum How to use checksums |
9f406986a6c60384fc8d16498a1b7b3a37722c0cbe10a6ff6a9bf1af7860698b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / vlmrun-0.9.1-py3-none-any.whl
| Download URL | vlmrun-0.9.1-py3-none-any.whl |
|---|---|
| Size | 147.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a0e1397d4240664b33cf54028f4ffb21afcf80d017da031d4bdb5715e3e3aae8
|
|
BLAKE2b-256 checksum How to use checksums |
da217b57d1a285b596c29f678db96f44d199dd9c926ff77ad4a2008932c34a29
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
