Skip to content

Download a variant of an asset's file

GET
/assets/{id}/variants/{variant}

Returns one of the files the server made from the asset’s original, such as a preview size, a video poster or a sprite sheet. The access check is the same as for GET /assets/{id}/file.

The preview sizes are listed by GET /previews; by default they are col (a square of up to 320 pixels) and preview, screen and hires (the longest side up to 1024, 1920 and 4096 pixels), all WebP. Other keys depend on the kind of file, for example poster for video, cover for audio with cover art, and sprites.jpg and sprites.vtt for scrubbing thumbnails. original returns the original file itself, but without the range support and media types of GET /assets/{id}/file. The asset’s preview hints (preview_available, ladder_available, scrub_available) say which variants are recorded; a variant that was never made gets 404.

{variant} is a single path segment. Keys that contain a slash, under hls/ (the video stream, starting at hls/master.m3u8), turntable/ and views/ (3D model renders), are served under the same path by separate routes with the same access check, for example /assets/{id}/variants/hls/master.m3u8. Those accept GET only, set a media type from the extension, and answer a malformed key with 400. A key with a slash under any other prefix gets 404.

This route ignores Range: a successful response is always the whole variant with 200, never 206, sent as application/octet-stream. It carries an ETag and the same 60-second public caching as GET /assets/{id}/file, and conditional requests work the same way, including a 304 that is answered before access is checked.

On an ordinary request, a refusal, an unknown or deleted asset, an asset with no file and a missing variant all get 404 with a JSON error. An id that isn’t a UUID gets a plain-text 400, and a key that storage rejects, such as one containing .., a plain-text 500.

id
required
string format: uuid

The asset’s id.

variant
required
string

The variant’s key, such as col, preview, poster or sprites.vtt. It has to be a single path segment; keys with a slash are described above.

Range
string

Ignored. This route always sends the whole variant.

The whole variant, sent as application/octet-stream.

string format: binary

Not sent by this route, which ignores Range; a successful response is always 200 with the whole variant.

string format: binary

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed