Media Types

Definable provides unified media classes for handling images, audio, video, and files. These work consistently across all models and agents that support multimodal input and output.

Image

from definable.media import Image

# From URL
image = Image(url="https://example.com/photo.jpg")

# From file
image = Image(filepath="/path/to/photo.png")

# From raw bytes
image = Image(content=raw_bytes, format="jpeg")

# From base64
image = Image.from_base64(base64_string, format="png")

Image Parameters

Parameter	Type	Description
`url`	`str`	Image URL
`filepath`	`str`	Local file path
`content`	`bytes`	Raw image bytes
`format`	`str`	Image format (`jpeg`, `png`, `gif`, `webp`)
`mime_type`	`str`	MIME type (auto-detected from format)
`detail`	`str`	Analysis detail: `"low"`, `"high"`, or `"auto"`

Image Output Fields

When a model generates an image:

Field	Description
`original_prompt`	The prompt used for generation
`revised_prompt`	The revised prompt (if the model modified it)
`alt_text`	Generated alt text

Audio

from definable.media import Audio

# From file
audio = Audio(filepath="/path/to/recording.mp3")

# From URL
audio = Audio(url="https://example.com/audio.wav")

# From bytes
audio = Audio(content=raw_bytes, format="wav")

Audio Parameters

Parameter	Type	Description
`url`	`str`	Audio URL
`filepath`	`str`	Local file path
`content`	`bytes`	Raw audio bytes
`format`	`str`	Audio format (`mp3`, `wav`, `flac`, `ogg`)
`duration`	`float`	Duration in seconds
`sample_rate`	`int`	Sample rate in Hz
`channels`	`int`	Number of audio channels
`transcript`	`str`	Text transcript (for audio output)

Video

from definable.media import Video

# From file
video = Video(filepath="/path/to/clip.mp4")

# From URL
video = Video(url="https://example.com/video.mp4")

Video Parameters

Parameter	Type	Description
`url`	`str`	Video URL
`filepath`	`str`	Local file path
`content`	`bytes`	Raw video bytes
`format`	`str`	Video format (`mp4`, `webm`)
`duration`	`float`	Duration in seconds
`width`	`int`	Width in pixels
`height`	`int`	Height in pixels

File

from definable.media import File

# From file
file = File(filepath="/path/to/report.pdf", mime_type="application/pdf")

# From URL
file = File(url="https://example.com/data.json", mime_type="application/json")

File Parameters

Parameter	Type	Description
`url`	`str`	File URL
`filepath`	`str`	Local file path
`content`	`bytes`	Raw file bytes
`mime_type`	`str`	MIME type (required for validation)
`filename`	`str`	Original filename
`size`	`int`	File size in bytes
`external`	`Any`	Provider-specific file object

Common Methods

All media types share these methods:

Method	Description
`get_content_bytes()`	Read the content as bytes
`to_base64()`	Encode content as base64 string
`to_dict()`	Serialize to dictionary
`from_base64(data, format)`	Create from base64 string

Using with Models

Pass media in messages:

from definable.model.message import Message

response = model.invoke(
    messages=[Message(
        role="user",
        content="Describe what you see and hear.",
        images=[Image(url="https://example.com/photo.jpg")],
        audio=[Audio(filepath="recording.mp3")],
    )],
    assistant_message=Message(role="assistant", content=""),
)

Using with Agents

Pass media directly to agent runs:

output = agent.run(
    "Analyze this document and image.",
    images=[Image(filepath="chart.png")],
    files=[File(filepath="data.csv", mime_type="text/csv")],
)

Each media type requires exactly one content source (url, filepath, or content). Providing none or multiple sources raises a validation error. The File type additionally supports an external source for provider-specific file objects.

Get Started

Basics

Capabilities

Advanced

Image

Image Parameters

Image Output Fields

Audio

Audio Parameters

Video

Video Parameters

File

File Parameters

Common Methods

Using with Models

Using with Agents

​Image

​Image Parameters

​Image Output Fields

​Audio

​Audio Parameters

​Video

​Video Parameters

​File

​File Parameters

​Common Methods

​Using with Models

​Using with Agents

Image

Image Parameters

Image Output Fields

Audio

Audio Parameters

Video

Video Parameters

File

File Parameters

Common Methods

Using with Models

Using with Agents