!pip install vlmrun
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfig
from vlmrun.types import MessageContent, FileUrl
# Define a Pydantic model for the execution inputs
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="The file to extract data from")
# Define a Pydantic model for the response
class 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 store
file = 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, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponse
from vlmrun.types import MessageContent, ImageUrl
class 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,
)
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import MessageContent
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="Uploaded file")
client = VLMRun(api_key="<VLMRUN_API_KEY>")
file = client.files.upload(file=Path("invoice.pdf"))
response = client.agent.execute(
name="<agent-name>:<agent-version>",
inputs=ExecutionInputs(
file=MessageContent(type="input_file", file_id=file.id),
),
batch=True,
)
npm install vlmrun zod
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>",
});
// Execute the agent with a file URL
const response = await client.agent.execute({
name: "<agent-name>:<agent-version>",
inputs: {
file: {
type: "file_url",
file_url: { url: "https://example.com/invoice.pdf" },
},
},
batch: true,
});
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>",
});
const response = await client.agent.execute({
name: "<agent-name>:<agent-version>",
inputs: {
image: {
type: "image_url",
image_url: { url: "https://example.com/photo.jpg", detail: "high" },
},
instruction: {
type: "text",
text: "Describe the product in the image.",
},
},
batch: true,
});
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": {
"type": "file_url",
"file_url": { "url": "https://example.com/invoice.pdf" }
}
},
"batch": true
}'
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": { "type": "input_file", "file_id": "file_abc123" }
},
"batch": true
}'
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"image": {
"type": "image_url",
"image_url": { "url": "https://example.com/photo.jpg", "detail": "high" }
},
"instruction": {
"type": "text",
"text": "Describe the product in the image."
}
},
"batch": true
}'
{
"name": "<string>",
"usage": {
"elements_processed": 123,
"credits_used": 123,
"steps": 123,
"message": "<string>",
"duration_seconds": 0,
"service_tier": "<string>",
"mode_multiplier": 123,
"standard_cost_dollars": 123,
"cost_dollars": 123,
"savings_dollars": 123
},
"id": "<string>",
"response": "<unknown>",
"execution_mode": "agent",
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Execute Agent
!pip install vlmrun
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfig
from vlmrun.types import MessageContent, FileUrl
# Define a Pydantic model for the execution inputs
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="The file to extract data from")
# Define a Pydantic model for the response
class 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 store
file = 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, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponse
from vlmrun.types import MessageContent, ImageUrl
class 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,
)
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import MessageContent
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="Uploaded file")
client = VLMRun(api_key="<VLMRUN_API_KEY>")
file = client.files.upload(file=Path("invoice.pdf"))
response = client.agent.execute(
name="<agent-name>:<agent-version>",
inputs=ExecutionInputs(
file=MessageContent(type="input_file", file_id=file.id),
),
batch=True,
)
npm install vlmrun zod
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>",
});
// Execute the agent with a file URL
const response = await client.agent.execute({
name: "<agent-name>:<agent-version>",
inputs: {
file: {
type: "file_url",
file_url: { url: "https://example.com/invoice.pdf" },
},
},
batch: true,
});
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>",
});
const response = await client.agent.execute({
name: "<agent-name>:<agent-version>",
inputs: {
image: {
type: "image_url",
image_url: { url: "https://example.com/photo.jpg", detail: "high" },
},
instruction: {
type: "text",
text: "Describe the product in the image.",
},
},
batch: true,
});
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": {
"type": "file_url",
"file_url": { "url": "https://example.com/invoice.pdf" }
}
},
"batch": true
}'
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": { "type": "input_file", "file_id": "file_abc123" }
},
"batch": true
}'
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"image": {
"type": "image_url",
"image_url": { "url": "https://example.com/photo.jpg", "detail": "high" }
},
"instruction": {
"type": "text",
"text": "Describe the product in the image."
}
},
"batch": true
}'
{
"name": "<string>",
"usage": {
"elements_processed": 123,
"credits_used": 123,
"steps": 123,
"message": "<string>",
"duration_seconds": 0,
"service_tier": "<string>",
"mode_multiplier": 123,
"standard_cost_dollars": 123,
"cost_dollars": 123,
"savings_dollars": 123
},
"id": "<string>",
"response": "<unknown>",
"execution_mode": "agent",
"status": "pending",
"created_at": "2023-11-07T05:31:56Z",
"completed_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Request Inputs
Theinputs 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 |
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.Generic payload — all input types
A singleinputs 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):
{
"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
}
Minimal payload shapes
{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": { "type": "file_url", "file_url": { "url": "https://example.com/invoice.pdf" } }
}
}
{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": { "type": "input_file", "file_id": "file_abc123" }
}
}
{
"name": "<agent-name>:<agent-version>",
"inputs": {
"image": { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg", "detail": "high" } },
"instruction": { "type": "text", "text": "Describe the product in the image." }
}
}
{
"name": "<agent-name>:<agent-version>",
"inputs": {
"video": { "type": "video_url", "video_url": { "url": "https://example.com/clip.mp4" } },
"reference": { "type": "image_url", "image_url": { "url": "https://example.com/style.jpg" } }
}
}
{
"name": "<agent-name>:<agent-version>",
"inputs": {
"audio": { "type": "audio_url", "audio_url": { "url": "https://example.com/meeting.mp3" } }
}
}
{
"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" }
}
}
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.
"auto" or null) resolves to standard. See the pricing guide for full details.!pip install vlmrun
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionResponse, AgentExecutionConfig
from vlmrun.types import MessageContent, FileUrl
# Define a Pydantic model for the execution inputs
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="The file to extract data from")
# Define a Pydantic model for the response
class 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 store
file = 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, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponse
from vlmrun.types import MessageContent, ImageUrl
class 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,
)
from pathlib import Path
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import MessageContent
class ExecutionInputs(BaseModel):
file: MessageContent = Field(..., description="Uploaded file")
client = VLMRun(api_key="<VLMRUN_API_KEY>")
file = client.files.upload(file=Path("invoice.pdf"))
response = client.agent.execute(
name="<agent-name>:<agent-version>",
inputs=ExecutionInputs(
file=MessageContent(type="input_file", file_id=file.id),
),
batch=True,
)
npm install vlmrun zod
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>",
});
// Execute the agent with a file URL
const response = await client.agent.execute({
name: "<agent-name>:<agent-version>",
inputs: {
file: {
type: "file_url",
file_url: { url: "https://example.com/invoice.pdf" },
},
},
batch: true,
});
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseUrl: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>",
});
const response = await client.agent.execute({
name: "<agent-name>:<agent-version>",
inputs: {
image: {
type: "image_url",
image_url: { url: "https://example.com/photo.jpg", detail: "high" },
},
instruction: {
type: "text",
text: "Describe the product in the image.",
},
},
batch: true,
});
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": {
"type": "file_url",
"file_url": { "url": "https://example.com/invoice.pdf" }
}
},
"batch": true
}'
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"file": { "type": "input_file", "file_id": "file_abc123" }
},
"batch": true
}'
curl -X POST https://api.vlm.run/v1/agent/execute \
-H "Authorization: Bearer $VLMRUN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "<agent-name>:<agent-version>",
"inputs": {
"image": {
"type": "image_url",
"image_url": { "url": "https://example.com/photo.jpg", "detail": "high" }
},
"instruction": {
"type": "text",
"text": "Describe the product in the image."
}
},
"batch": true
}'
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
Request to execute an agent.
Optional metadata to pass to the model.
Hide child attributes
Hide child attributes
The environment where the request was made.
dev, staging, prod The session ID of the request
Whether to enable logs for this request.
Whether the file can be used for training
Whether to allow retention of the data
Extra metadata for the request (e.g. dataset_id, subset_id).
The configuration for the agent execution request.
Hide child attributes
Hide child attributes
The prompt to guide the execution of the agent.
The JSON schema to the agent
The type of tools to use for the agent
document, image, video, multimodal List of agent skills to enable for this execution. Skills provide domain-specific expertise and capabilities.
Hide child attributes
Hide child attributes
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.
The unique identifier of the skill — a UUID or a name string (e.g., 'pillow', 'batch-processing').
Human-readable skill name for lookup (e.g., 'invoice-extraction'). Alternative to skill_id. Deprecated in favour of skill_id.
The version of the skill — an integer (e.g. 2) or 'latest'.
DEPRECATED: Use 'skill_version' instead. The version of the skill.
Human-readable name for the inline skill (used for discovery and logging).
Short description of what the inline skill does.
Source payload for inline skills. Contains the base64-encoded zip bundle with type, media_type, and data fields.
Hide child attributes
Hide child attributes
Base64-encoded zip bundle containing the skill files.
Encoding type for the inline skill data. Currently only 'base64' is supported.
"base64"MIME type of the skill bundle. Must be 'application/zip'.
DEPRECATED: Use 'source.data' instead. Base64-encoded zip bundle containing the skill files (inline skills only).
List of tool names to use for this agent execution. If provided, only these tools will be loaded. Tool names should match function names exactly.
Reuse cached representations of large document/video inputs across calls in the same session to reduce input-token cost and latency.
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.
auto, default, standard, flex, priority 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.
agent, program Unique identifier of the request.
Date and time when the request was created (in UTC timezone)
The URL to call when the request is completed.
1VLM Run Agent model to use for execution. When omitted, the skill's vlmrun.yaml model is used; otherwise the agent default.
vlmrun-orion-1, vlmrun-orion-1:auto, vlmrun-orion-1:fast, vlmrun-orion-1:pro, vlmrun-orion-2, vlmrun-orion-2:auto, vlmrun-orion-2:qwen3.6-35b-a3b, vlmrun-orion-2:gemma4-26b-a4b, vlmrun-orion-2:cosmos3-nano, vlmrun-orion-2:kimi-2.6, vlmrun-orion-2:kimi-k3, vlmrun-orion-2:gpt-5.5, vlmrun-orion-2:opus-4.8, vlmrun-orion-2:muse-spark-1.1, vlmrun-orion-2:grok-4.5, vlmrun-orion-2:gemini-flash-3.6, vlmrun-orion-2:fast, vlmrun-orion-2:pro Name of the agent. If not provided, we use the prompt to identify the unique agent.
Whether to process the document in batch mode (async).
The inputs to the agent.
Response
Successful Response
Response to the agent execution request.
Name of the agent
The usage metrics for the request.
Hide child attributes
Hide child attributes
Number of elements processed.
The type of element processed (e.g. image, page, video, audio).
image, page, video, audio Amount of total credits used.
Number of steps processed, in case of agentic execution.
The message from the credit usage job.
Duration of the request in seconds.
Delivery tier (standard, priority, flex).
Pricing multiplier applied to standard cost.
Pre-multiplier customer cost in USD, derived from tokens and unit rates.
Effective customer cost in USD after the service-tier multiplier.
Discount in USD when using flex (standard_cost_dollars - cost_dollars).
Unique identifier of the agent execution response.
The response from the model.
How the execution ran: program when a cached skill pipeline.py ran as fixed code (no LLM agent loop), else agent. Always agent for non-Orion-2 models.
agent, program The status of the job.
pending, enqueued, running, completed, failed, paused Date and time when the execution was created (in UTC timezone)
Date and time when the execution was completed (in UTC timezone)