from PIL import Image
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import ImageRef
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Define a response model with an ImageRef field
class BlurredImageResponse(BaseModel):
image: ImageRef = Field(..., description="The blurred image")
# Make a chat completion request that generates an image artifact
response = client.agent.completions.create(
model="vlmrun-orion-2:auto",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Blur all the faces in this image"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]
}
],
response_format={"type": "json_schema", "schema": BlurredImageResponse.model_json_schema()},
)
# Parse the response to get the artifact reference
result = BlurredImageResponse.model_validate_json(response.choices[0].message.content)
# Retrieve the artifact using session_id and object_id
image: Image.Image = client.artifacts.get(
session_id=response.session_id,
object_id=result.image.id,
)
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseURL: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>"
});
// Retrieve the artifact using session_id and object_id
const artifact = await client.artifacts.get({
sessionId: "<SESSION_ID>",
objectId: "img_a1b2c3"
});
console.log(artifact);
{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Files
Get Artifact
Retrieve an artifact by session ID or execution ID.
GET
/
v1
/
artifacts
from PIL import Image
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import ImageRef
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Define a response model with an ImageRef field
class BlurredImageResponse(BaseModel):
image: ImageRef = Field(..., description="The blurred image")
# Make a chat completion request that generates an image artifact
response = client.agent.completions.create(
model="vlmrun-orion-2:auto",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Blur all the faces in this image"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]
}
],
response_format={"type": "json_schema", "schema": BlurredImageResponse.model_json_schema()},
)
# Parse the response to get the artifact reference
result = BlurredImageResponse.model_validate_json(response.choices[0].message.content)
# Retrieve the artifact using session_id and object_id
image: Image.Image = client.artifacts.get(
session_id=response.session_id,
object_id=result.image.id,
)
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseURL: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>"
});
// Retrieve the artifact using session_id and object_id
const artifact = await client.artifacts.get({
sessionId: "<SESSION_ID>",
objectId: "img_a1b2c3"
});
console.log(artifact);
{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>",
"input": "<unknown>",
"ctx": {}
}
]
}Retrieve the raw content of an artifact using either a
The Python SDK provides convenience methods that automatically convert artifacts to the appropriate Python types.
session_id (for chat completions) or an execution_id (for agent executions), along with the object_id from the response. Artifacts are binary objects generated during agent interactions, such as images, videos, audio files, and documents.
For a comprehensive guide on working with artifacts, including usage patterns and examples, see the Artifacts Guide.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
object_id | string | Yes | Object ID for the artifact (format: <type>_<6-hex-chars>, e.g., img_a1b2c3) |
session_id | string | No | Session ID from chat completions (mutually exclusive with execution_id) |
execution_id | string | No | Execution ID from agent executions (mutually exclusive with session_id) |
Either
session_id or execution_id must be provided, but not both. Use session_id for artifacts from chat completions and execution_id for artifacts from agent executions.Object Reference Format
Object references follow the format:<type_prefix>_<6-digit-hex-string> (e.g., img_a1b2c3).
| Artifact Type | Prefix | Reference Type | Python Return Type |
|---|---|---|---|
| Image | img_ | ImageRef | PIL.Image.Image |
| Video | vid_ | VideoRef | Path (mp4) |
| Audio | aud_ | AudioRef | Path (mp3) |
| Document | doc_ | DocumentRef | Path (pdf) |
| Reconstruction | recon_ | ReconRef | Path (spz) |
| URL | url_ | UrlRef | Path (any of the above) |
| Array | arr_ | ArrayRef | np.ndarray |
Response
Returns the raw binary content of the artifact with the appropriate content type based on the artifact type.Get Artifact by Session ID
Usesession_id to retrieve artifacts from chat completion responses.
from PIL import Image
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import ImageRef
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Define a response model with an ImageRef field
class BlurredImageResponse(BaseModel):
image: ImageRef = Field(..., description="The blurred image")
# Make a chat completion request that generates an image artifact
response = client.agent.completions.create(
model="vlmrun-orion-2:auto",
messages=[
{
"role": "user",
"content": [
{"type": "text", "text": "Blur all the faces in this image"},
{"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
]
}
],
response_format={"type": "json_schema", "schema": BlurredImageResponse.model_json_schema()},
)
# Parse the response to get the artifact reference
result = BlurredImageResponse.model_validate_json(response.choices[0].message.content)
# Retrieve the artifact using session_id and object_id
image: Image.Image = client.artifacts.get(
session_id=response.session_id,
object_id=result.image.id,
)
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseURL: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>"
});
// Retrieve the artifact using session_id and object_id
const artifact = await client.artifacts.get({
sessionId: "<SESSION_ID>",
objectId: "img_a1b2c3"
});
console.log(artifact);
Get Artifact by Execution ID
Useexecution_id to retrieve artifacts from agent execution responses.
from PIL import Image
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.client.types import AgentExecutionConfig, AgentExecutionResponse, ImageUrl
from vlmrun.types import ImageRef, MessageContent
client = VLMRun(api_key="<VLMRUN_API_KEY>")
# Define typed inputs and response model
class ExecutionInputs(BaseModel):
image: MessageContent = Field(..., description="The input image")
class ImageResponse(BaseModel):
image: ImageRef = Field(..., description="The processed image")
# Execute an agent
execution: AgentExecutionResponse = client.agent.execute(
name="image/blur-image",
inputs=ExecutionInputs(
image=MessageContent(type="image_url", image_url=ImageUrl(url="https://example.com/photo.jpg"))
),
config=AgentExecutionConfig(
prompt="Blur the entire image",
response_model=ImageResponse
)
)
# Wait for completion
execution = client.executions.wait(execution.id, timeout=180)
# Parse the response and retrieve the artifact using execution_id
result = ImageResponse.model_validate(execution.response)
image: Image.Image = client.artifacts.get(
execution_id=execution.id,
object_id=result.image.id,
)
import { VlmRun } from "vlmrun";
const client = new VlmRun({
baseURL: "https://api.vlm.run/v1",
apiKey: "<VLMRUN_API_KEY>"
});
// Retrieve the artifact using execution_id and object_id
const artifact = await client.artifacts.get({
executionId: "<EXECUTION_ID>",
objectId: "img_a1b2c3"
});
console.log(artifact);
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Query Parameters
Session ID for the artifacts
Execution ID for the artifacts
Object ID to retrieve a single artifact
Workspace filename to retrieve a single artifact
Maximum number of items to return when listing
Required range:
1 <= x <= 1000Number of items to skip when listing
Required range:
x >= 0Response
Successful Response