Upload, pin and retrieve files

An artifact is a stored material. A media-source node places a material on the graph. A download link makes an existing material temporarily accessible to an external client. These are separate steps.

Upload a file

Use upload_artifact for a file within its direct-upload limit. For a larger file, use start_upload → numbered upload_chunk calls → finish_upload. Use the returned upload ID and limits; keep every byte in order. cancel_upload discards an unfinished upload session.

After success, retain the returned artifact ID. Read the material metadata to check kind, filename, type and size. A document can be stored and downloaded, but it cannot be pinned to an image, video or audio node and is not automatically converted into text.

Put the material on the graph

Use apply_graph_ops with pin_file and the discovered artifact ID for an appropriate media-source node. Read the graph back, then inspect the source preview in the studio.

For supported media-page links, import_clip brings the file into your materials. YouTube first requires inspect_import and a quality selected from its returned options. Inspect all returned items when a source contains more than one material; do not silently select or discard the rest.

Retrieve a finished material

Find it with list_artifacts, then request its current download link:

{
  "name": "get_artifact",
  "arguments": { "artifact_id": "<artifact id returned by list_artifacts>" }
}

Use download_url before expires_at. Links last 15 minutes. If there is no downloadable link, read download_note; the raw material URL may require authentication or point to an external source.

An expired link is not a reason to repeat a paid generation. Request another link for the same artifact. If the material is not in the first bounded list, use the correct project/kind and inspect the corresponding generation or node before concluding that it is missing.

A video from your own V2 Decoration also returns design_profile, the series style used for that video, and its design_profile_fingerprint. Pass design_profile unchanged as series_profile to the next decorate_video, together with renderer: 'hyperframes' and decoration_version: 2, to keep the series in one style; without them the style is not applied and the response says so in series_profile_warning. Other materials, and materials of another account, have no such field. See subtitles and decoration.

See individual media operations for asynchronous output handling and connection/input diagnosis for ownership and file-type errors.

Last checked: 22 October 2026. The live reference supplies upload limits and exact request fields.