MediaReference

MediaReference is the pointer stored in the database in place of media bytes.

MediaReference is the pointer stored on a run in place of the media bytes. It records which backend holds the object and enough metadata to serve it without a further lookup.

Field	Type	Default	Description
media_id	str	-	ID of the media object this reference replaces.
storage_key	str	-	Key of the object in the backend.
session_id	Optional[str]	None	Session whose run uploaded the object.
storage_backend	str	-	Backend that holds the object, for example "s3", "gcs", or "local".
bucket	Optional[str]	None	Bucket holding the object. For local storage, the resolved base path.
region	Optional[str]	None	Region of the bucket.
url	Optional[str]	None	Durable URL for the object, when the backend has one. Signed URLs expire, so they are never stored here.
mime_type	Optional[str]	None	Content type of the stored object.
filename	Optional[str]	None	Original filename.
size	Optional[int]	None	Size of the object in bytes.
content_hash	Optional[str]	None	SHA-256 of the content.
media_type	Optional[str]	None	One of "image", "audio", "video", or "file".
metadata	Optional[Dict[str, Any]]	None	Full metadata for the media. The backend may store a sanitized subset on the object itself.

Metadata

Image, Audio, Video and File take a metadata dict. It is written onto the stored object and kept in full on the reference.

Image(content=data, metadata={"source": "invoice-scan", "page": "3"})

Backends trim what they put on the object itself: S3 takes ASCII only within about 1800 bytes, GCS within 8000, and the local backend writes it to a .meta.json file beside the object. The reference keeps the whole dict either way.

Over HTTP, send it to the agent or team run route as files_metadata, a JSON array matched to files[] by position. The array must stay under 8000 bytes or the request is rejected with 422.