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.