Skip to main content
Use --variant to choose the representation to download. This is useful when an original camera file is much larger than the viewing copy needed for review or analysis.

​
Download one proxy

Streaming proxies are H.264 MP4 files with AAC audio when the source contains audio. They preserve aspect ratio, fit within a 1080p landscape or portrait frame, and are not upscaled. The CLI does not offer a resolution, bitrate, or codec selector. These proxies are viewing copies. Use original when you need the source media’s original quality and format for finishing or delivery. Downloading a proxy does not change the original in Aspect.

​
Download a folder of proxies

The command preserves the folder tree and gives each downloaded video a _proxy.mp4 filename. It can also take a project URL. For a background job:
Track the returned ID with transfer commands. Standard --replace and --keep-both download options apply to the resulting proxy filenames.

​
Download preview images

Generated poster images use WebP. If the asset has a custom thumbnail, the CLI prefers it and uses its format’s extension, so a preview filename may instead end in .jpg or .png. Use the returned path rather than assuming the extension in a script.

​
When a variant is missing

Proxy and preview files are produced by media processing. Upload completion does not guarantee that a requested variant already exists, and some assets do not have that representation. The download does not generate a missing proxy, wait for processing, or fall back to downloading originals. Check the asset in Aspect and retry after processing is complete. In automation, inspect the downloaded count and failed array; the number of proxy files can be smaller than the number of source assets.

​
Retrieve a download URL through the API

If another application needs the proxy’s URL, the REST API also exposes it:
Replace <asset-id> with the asset’s id returned by:
The response to the download-URL request includes url and url_expires_at. Fetch the returned URL before it expires; request another URL when needed rather than treating it as a permanent public link. The API checks the user’s download permission. For a preview that follows the CLI’s custom-thumbnail preference, use variant=preview&prefer_custom_thumbnail=true. See the API overview for authentication. To work with proxies as local files, download them as shown above. aspect mount mounts the project filesystem and has no proxy-variant selector.