fetch_media
Read-onlyIdempotent
Download a generated media file (video, frame) and return its bytes, base64-encoded, so the file can be saved or shown even though the media endpoint isn't publicly reachable with your MCP key.
THIS IS THE EXPENSIVE PATH — prefer `download_url` from the job result. Bytes returned
here travel as TEXT, and text is where context dies: a 480 KB audio stem is ~640 thousand
base64 characters, roughly 160 000 tokens, in ONE tool result. The same file behind
`download_url` costs about twenty. An inline image preview is cheap by comparison (it
travels as an image, ~450 tokens) — it is base64 in a text field that hurts.
Because of that this tool REFUSES big files by default and hands back a download link
instead. Pass force_bytes=True only when you genuinely need the bytes inside the
conversation and know what it costs.
path: the `download_path` / `first_frame_path` / `last_frame_path` value from a job
result (e.g. "/v1/media/<id>.mp4"), or just the bare filename.
max_kb: size ceiling for an in-band answer (default 64 KB ≈ 21 000 tokens).
Returns {"filename", "media_type", "base64"}. The download is scoped to your own
account group — you can only fetch media your key produced. Note videos can be
several MB, so the base64 payload is large; fetch only when you actually need the
bytes (to save/display), not to check status (use check_job for that).
On storage: the server keeps a local cache of results and, when it runs short of disk,
drops the OLDEST files first, whether fetched or not. A dropped file is fetched back
from the Google account that made it on the next request; if that takes a while you get
`retry_after_s` — call again then. If that account is disconnected, the error names it
and gives `reconnect_url`: tell the user to reconnect it, then retry. Only when the
original cannot be fetched back does it answer 410 with the date. Saving the bytes
locally is still the way to keep something for good.Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| max_kb | No | ||
| force_bytes | No |