# Get a file variant

Source: https://api-docs.magicdoor.com/api-reference/files/get-file-variant

Fetches a resized or re-encoded copy of a file — a thumbnail, a preview, a smaller video or audio rendition. Like the raw download, the response is a 302 redirect to a signed storage URL rather than the bytes themselves.

`GET https://files.magicdoor.com/files/{fileId}/v/{variant}/{filename}`

**Authentication:** bearer token in the `Authorization` header, as `Bearer <token>`.

## Path parameters

- `fileId` (string, required) — The source file, as a Snowflake id in decimal-string form. Must be a positive whole number. Example: `1831208734196891649`.
- `variant` (string, required) — Which rendition you want. From the company portal this has to be one of the presets listed below. 3 to 100 characters, made of letters, digits, and the characters `;` `,` `_` `-`. One of: `thumb`, `preview`, `original`, `320p`, `720p`, `1080p`, `64k`, `128k`, `192k`, `320k`. Example: `thumb`.
- `filename` (string) — An optional trailing segment that renames this one download. Leave the whole segment off and the variant's own generated name is used, such as `kitchen-leak-thumb.webp`. When you do send it, it must be 3 to 200 characters, and it must be URL-escaped. Example: `kitchen-leak.webp`.

## Query parameters

- `wait` (boolean) — Whether to hold the request open until the variant has been generated. Leaving it at `true` always gives you the variant. Setting it to `false` only changes anything for files a browser could already display, and then only while the variant is still being made — see below. Default: `true`. Example: `true`.
- `download` (boolean) — `true` makes the storage URL send `Content-Disposition: attachment`, so a browser saves the file instead of displaying it. Default: `false`. Example: `false`.

## Example request

```bash
curl --request GET \
  --url 'https://files.magicdoor.com/files/1831208734196891649/v/thumb/kitchen-leak.webp?wait=true&download=false' \
  --header 'Authorization: Bearer <token>'
```

## Responses

### 302 — Redirect to the signed storage URL that holds the content

- `Location` (string) — The signed storage URL for the variant — or, when `wait=false` and the variant is not ready, for the original file. Valid for seven days and needs no MagicDoor access token of its own, so treat it as a secret. There is no response body.

### 401 — The access token is missing, expired, or invalid

### 404 — No such file, the file has been deleted, it belongs to another company — or the variant could not be produced

```json
{
  "type": "https://httpstatuses.com/404",
  "title": "Not Found",
  "status": 404,
  "detail": "File not found.",
  "instance": "/files/1831208734196891649/v/thumb/kitchen-leak.webp",
  "traceId": "0HN7GK9C2M4PQ",
  "entityType": "File",
  "entityId": "1831208734196891649"
}
```

## The presets

| Variant | Works on | What you get |
| --- | --- | --- |
| `thumb` | Images | WebP, longest side at most 192 pixels |
| `preview` | Images | WebP, longest side at most 1280 pixels |
| `original` | Images | WebP at the original pixel size, quality 90 — the one to use to make a format a browser cannot show, such as HEIC, displayable |
| `320p` | Video | H.264 video with AAC audio, scaled to 320 lines |
| `720p` | Video | H.264 video with AAC audio, scaled to 720 lines |
| `1080p` | Video | H.264 video with AAC audio, scaled to 1080 lines |
| `64k` | Audio | MP3 at 64 kbit/s |
| `128k` | Audio | MP3 at 128 kbit/s |
| `192k` | Audio | MP3 at 192 kbit/s |
| `320k` | Audio | MP3 at 320 kbit/s |

> **Warning: Presets only, and a silent 404 when it cannot be done**
>
> Company portal callers can only bring a preset into existence. Ask for anything else, ask for a preset that does not suit the source — a `720p` of a PDF, a `thumb` of an audio file — and the answer is `404`, with none of the detail the other failures carry. There is no way to tell a wrong variant name from a source file that cannot be converted.

## Generation, and what `wait` really does

The first request for a given file and variant is what creates it; later requests reuse it.

- **`wait=true`, the default.** The request stays open until the variant has been made, then redirects to it. Slower on that first call, but you always get what you asked for.
- **`wait=false`.** Only takes effect when the source file is already something a browser can display — a JPEG, PNG, WebP, MP4, WebM, MP3, PDF, and so on. If the variant is not ready yet, you are redirected to the **original file** instead and generation carries on in the background, so a later request gets the variant. For anything a browser cannot display, `wait=false` is ignored and the request behaves as if it were `true`, because redirecting to the original would be no use.

The signed URL behaves exactly as it does on [Download a file](https://api-docs.magicdoor.com/api-reference/files/download-file.md): follow the redirect, and do not forward your MagicDoor `Authorization` header to storage.