> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve proxies and previews

> Download generated H.264 video proxies and poster images for review, analysis, or automation without downloading the original media.

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.

| Variant | What is downloaded | Example local filename |
| - | - | - |
| `original` | The original asset; the default | `interview.mov` |
| `stream_proxy` | The generated H.264 MP4 streaming proxy | `interview_proxy.mp4` |
| `preview` | A poster image, preferring a custom thumbnail when one exists | `interview_preview.webp` for a generated preview |

## Download one proxy

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./proxies --variant stream_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

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage" ./proxies --variant stream_proxy
```

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:

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage" ./proxies --variant stream_proxy --detach
```

Track the returned ID with [transfer commands](/docs/cli/transfers). Standard `--replace` and `--keep-both` [download options](/docs/cli/downloads#existing-local-files) apply to the resulting proxy filenames.

## Download preview images

```bash theme={null}
aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./previews --variant preview
```

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.

| Request | Missing-variant behavior |
| - | - |
| One specific asset | The download fails if that asset lacks the requested variant. |
| A folder or project | Assets without the variant are left out. The download can succeed with zero files if none match. |

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:

```bash theme={null}
curl --fail --silent --show-error \
  -H "Authorization: Bearer $ASPECT_API_KEY" \
  "https://api.aspect.inc/assets/<asset-id>/download?variant=stream_proxy"
```

Replace `<asset-id>` with the asset's `id` returned by:

```bash theme={null}
aspect ls "aspect://Acme/Documentary/Footage/interview.mov" --json
```

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](/docs/api-reference/index) 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.