Get Artifact

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-1: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": {}
    }
  ]
}

GET

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-1: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 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`

The Python SDK provides convenience methods that automatically convert artifacts to the appropriate Python types.

Response

Returns the raw binary content of the artifact with the appropriate content type based on the artifact type.

Get Artifact by Session ID

Use session_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-1: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

Use execution_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

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

session_id

string | null

Session ID for the artifacts

execution_id

string | null

Execution ID for the artifacts

object_id

string | null

Object ID to retrieve a single artifact

filename

string | null

Workspace filename to retrieve a single artifact

limit

integer

default:100

Maximum number of items to return when listing

Required range: 1 <= x <= 1000

offset

integer

default:0

Number of items to skip when listing

Required range: x >= 0

Response

Successful Response

Get Skill Download URL Submit Feedback

Get Started

Health

Generate

Predictions

Chat

Agent

Executions

Files

Models / Hub

Skills

Artifacts

Feedback

Query Parameters

Object Reference Format

Response

Get Artifact by Session ID

Get Artifact by Execution ID

Authorizations

Query Parameters

Response

​Query Parameters

​Object Reference Format

​Response

​Get Artifact by Session ID

​Get Artifact by Execution ID

Authorizations

Query Parameters

Response

Query Parameters

Object Reference Format

Response

Get Artifact by Session ID

Get Artifact by Execution ID