!pip install vlmrunfrom pathlib import Pathfrom pydantic import BaseModel, Fieldfrom vlmrun.client import VLMRunfrom vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfigfrom vlmrun.types import MessageContent, FileUrl# Define a Pydantic model for the execution inputsclass ExecutionInputs(BaseModel): file: MessageContent = Field(..., description="The file to extract data from")# Define a Pydantic model for the responseclass Invoice(BaseModel): invoice_id: str = Field(..., description="The ID of the invoice") total_amount: float = Field(..., description="The total amount of the invoice")client = VLMRun(api_key="<VLMRUN_API_KEY>")# Upload the file to the object storefile = client.files.upload(file=Path("test.pdf"))# Execute the agent (by name and version)response: AgentExecutionResponse = client.agent.execute( name="<agent-name>:<agent-version>", inputs=ExecutionInputs( file=MessageContent(type="file_url", file_url=FileUrl(url=file.public_url)) ), batch=True,)# Execute the agent (by inline prompt)response: AgentExecutionResponse = client.agent.execute( inputs=ExecutionInputs( file=MessageContent(type="file_url", file_url=FileUrl(url=file.public_url)) ), config=AgentExecutionConfig( prompt="Extract the invoice_id and total amount from the invoice.", response_model=Invoice, ), batch=True,)
from pydantic import BaseModel, Fieldfrom vlmrun.client import VLMRunfrom vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponsefrom vlmrun.types import MessageContent, ImageUrlclass ExecutionInputs(BaseModel): image: MessageContent = Field(..., description="Image to analyze") instruction: MessageContent = Field(..., description="What to extract or do")client = VLMRun(api_key="<VLMRUN_API_KEY>")response: AgentExecutionResponse = client.agent.execute( name="<agent-name>:<agent-version>", inputs=ExecutionInputs( image=MessageContent( type="image_url", image_url=ImageUrl(url="https://example.com/photo.jpg", detail="high"), ), instruction=MessageContent( type="text", text="Describe the product in the image.", ), ), batch=True,)
!pip install vlmrunfrom pathlib import Pathfrom pydantic import BaseModel, Fieldfrom vlmrun.client import VLMRunfrom vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfigfrom vlmrun.types import MessageContent, FileUrl# Define a Pydantic model for the execution inputsclass ExecutionInputs(BaseModel): file: MessageContent = Field(..., description="The file to extract data from")# Define a Pydantic model for the responseclass Invoice(BaseModel): invoice_id: str = Field(..., description="The ID of the invoice") total_amount: float = Field(..., description="The total amount of the invoice")client = VLMRun(api_key="<VLMRUN_API_KEY>")# Upload the file to the object storefile = client.files.upload(file=Path("test.pdf"))# Execute the agent (by name and version)response: AgentExecutionResponse = client.agent.execute( name="<agent-name>:<agent-version>", inputs=ExecutionInputs( file=MessageContent(type="file_url", file_url=FileUrl(url=file.public_url)) ), batch=True,)# Execute the agent (by inline prompt)response: AgentExecutionResponse = client.agent.execute( inputs=ExecutionInputs( file=MessageContent(type="file_url", file_url=FileUrl(url=file.public_url)) ), config=AgentExecutionConfig( prompt="Extract the invoice_id and total amount from the invoice.", response_model=Invoice, ), batch=True,)
from pydantic import BaseModel, Fieldfrom vlmrun.client import VLMRunfrom vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponsefrom vlmrun.types import MessageContent, ImageUrlclass ExecutionInputs(BaseModel): image: MessageContent = Field(..., description="Image to analyze") instruction: MessageContent = Field(..., description="What to extract or do")client = VLMRun(api_key="<VLMRUN_API_KEY>")response: AgentExecutionResponse = client.agent.execute( name="<agent-name>:<agent-version>", inputs=ExecutionInputs( image=MessageContent( type="image_url", image_url=ImageUrl(url="https://example.com/photo.jpg", detail="high"), ), instruction=MessageContent( type="text", text="Describe the product in the image.", ), ), batch=True,)
The inputs field accepts a JSON object whose values are MessageContent items. Each value is a typed, discriminated union — the type field determines which modality is passed in as context for the agent. You can mix and match any number of modalities in a single request (e.g. a document + a reference image + a text instruction).
type
Payload field
Modality
When to use
text
text
Plain text
Instructions, questions, or prompt context
image_url
image_url.url (+ optional detail)
Image (URL)
Images hosted publicly (jpg, png, webp, …)
video_url
video_url.url
Video (URL)
Videos hosted publicly (mp4, mov, …)
audio_url
audio_url.url
Audio (URL)
Audio files hosted publicly (mp3, wav, …)
file_url
file_url.url
Document / file (URL)
PDFs, Word docs, or any other file accessible over HTTP(S)
input_file
file_id
Uploaded file
Files uploaded via POST /v1/files — pass the returned file.id
Each slot can also be a plain JSON primitive (string, number, boolean, array, object) when the agent’s input schema declares a non-media field — e.g. an email_body string or a structured metadata object to include alongside the uploaded file.See the Multi-modal Inputs guide for the full reference on each modality, including detail levels for images / video, uploaded-file workflows, and typed Pydantic / Zod input models.
inputs is just a dictionary of named context slots — the keys are arbitrary (e.g. "file", "document", "reference_image", "instruction", "email_details") and match the input schema of your agent. Each value is either a MessageContent object of one of the types above, or a plain JSON primitive.
A single inputs object can freely mix every modality together with raw strings / JSON. The example below combines an uploaded file, a file URL, an image URL, a video URL, an audio URL, a text instruction, and two plain-primitive context fields (an HTML email body and a structured metadata object):
All input types
{ "name": "<agent-name>:<agent-version>", "inputs": { "file": { "type": "input_file", "file_id": "dbb28d43-d741-4e0c-b25b-04ddc69b3197" }, "supporting_document": { "type": "file_url", "file_url": { "url": "https://example.com/referral.pdf" } }, "reference_image": { "type": "image_url", "image_url": { "url": "https://example.com/layout.png", "detail": "high" } }, "demo_video": { "type": "video_url", "video_url": { "url": "https://example.com/clip.mp4" } }, "voicemail": { "type": "audio_url", "audio_url": { "url": "https://example.com/voicemail.mp3" } }, "instruction": { "type": "text", "text": "Schedule the patient and confirm insurance eligibility." }, "email_details": "<div dir=\"ltr\">Hi,<br />Please see the attached order form for Oscar Bhujel. Kindly let us know once the appointment is scheduled.<br />Thank you,<br />Camielle Jane Lim</div>", "metadata": { "received_at": "2026-04-20T16:30:00Z", "priority": "normal", "source": "gmail" } }, "batch": true}
{ "name": "<agent-name>:<agent-version>", "inputs": { "file": { "type": "input_file", "file_id": "dbb28d43-d741-4e0c-b25b-04ddc69b3197" }, "email_details": "<div>Please see the attached order form. Let us know once scheduled.</div>", "metadata": { "received_at": "2026-04-20T16:30:00Z", "source": "gmail" } }}
Set config.service_tier to control both billing and request routing — mirroring OpenAI’s service_tier and Vertex AI’s Gemini Flex/Priority offering:
standard / default(default) — baseline rates and latency.
flex — 0.5× cost (50% off), higher latency. Best for batch / background workloads.
priority — 1.8× cost, lowest latency. Best for latency-sensitive, user-facing workflows.
Omitting the field (or passing "auto" or null) resolves to standard. See the pricing guide for full details.
!pip install vlmrunfrom pathlib import Pathfrom pydantic import BaseModel, Fieldfrom vlmrun.client import VLMRunfrom vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfigfrom vlmrun.types import MessageContent, FileUrl# Define a Pydantic model for the execution inputsclass ExecutionInputs(BaseModel): file: MessageContent = Field(..., description="The file to extract data from")# Define a Pydantic model for the responseclass Invoice(BaseModel): invoice_id: str = Field(..., description="The ID of the invoice") total_amount: float = Field(..., description="The total amount of the invoice")client = VLMRun(api_key="<VLMRUN_API_KEY>")# Upload the file to the object storefile = client.files.upload(file=Path("test.pdf"))# Execute the agent (by name and version)response: AgentExecutionResponse = client.agent.execute( name="<agent-name>:<agent-version>", inputs=ExecutionInputs( file=MessageContent(type="file_url", file_url=FileUrl(url=file.public_url)) ), batch=True,)# Execute the agent (by inline prompt)response: AgentExecutionResponse = client.agent.execute( inputs=ExecutionInputs( file=MessageContent(type="file_url", file_url=FileUrl(url=file.public_url)) ), config=AgentExecutionConfig( prompt="Extract the invoice_id and total amount from the invoice.", response_model=Invoice, ), batch=True,)
from pydantic import BaseModel, Fieldfrom vlmrun.client import VLMRunfrom vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponsefrom vlmrun.types import MessageContent, ImageUrlclass ExecutionInputs(BaseModel): image: MessageContent = Field(..., description="Image to analyze") instruction: MessageContent = Field(..., description="What to extract or do")client = VLMRun(api_key="<VLMRUN_API_KEY>")response: AgentExecutionResponse = client.agent.execute( name="<agent-name>:<agent-version>", inputs=ExecutionInputs( image=MessageContent( type="image_url", image_url=ImageUrl(url="https://example.com/photo.jpg", detail="high"), ), instruction=MessageContent( type="text", text="Describe the product in the image.", ), ), batch=True,)
The type of the skill. Use 'skill_reference' for DB-stored skills referenced by id/name. Use 'inline' to provide the skill as a base64-encoded zip bundle.
Delivery tier for the agent run. auto/default/None resolves to standard (baseline 1.0× billing); flex is 0.5× billing with higher latency, and priority is 1.8× billing with a premium latency SLO.
Orion-2 only (ignored for other models and the document/image/video generate APIs). agent (default): run the full LLM agent loop (the agent decides at runtime). program: run cached skill pipeline.py as fixed code when available.