Skip to main content
GET
/
v1
/
artifacts
from PIL import Image
from pydantic import BaseModel, Field
from vlmrun.client import VLMRun
from vlmrun.types import ImageRef

client = VLMRun(base_url="https://agent.vlm.run/v1", 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,
)

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}
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

ParameterTypeRequiredDescription
object_idstringYesObject ID for the artifact (format: <type>_<6-hex-chars>, e.g., img_a1b2c3)
session_idstringNoSession ID from chat completions (mutually exclusive with execution_id)
execution_idstringNoExecution 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 TypePrefixReference TypePython Return Type
Imageimg_ImageRefPIL.Image.Image
Videovid_VideoRefPath (mp4)
Audioaud_AudioRefPath (mp3)
Documentdoc_DocumentRefPath (pdf)
Reconstructionrecon_ReconRefPath (spz)
URLurl_UrlRefPath (any of the above)
Arrayarr_ArrayRefnp.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(base_url="https://agent.vlm.run/v1", 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,
)

​
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(base_url="https://agent.vlm.run/v1", 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,
)

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
object_id
string
required

Object ID for the artifact

​
session_id
string | null

Session ID for the artifact

​
execution_id
string | null

Execution ID for the artifact

Response

Successful Response