Frame Generation
video-generate
The video-generate parameter controls what kind of image output is produced from a video.
| Value | Description |
|---|---|
animation | Generates an animated image. Use fm to select the format (gif, webp, avif, png). Defaults to GIF if fm is omitted. |
gif | Legacy alias for video-generate=animation&fm=gif. Prefer animation for new integrations. |
thumbnail | Extracts a single static image frame from the video. Use fm to specify the output format (e.g. fm=jpg, fm=png). |
spritesheet | Generates a spritesheet image grid. See the Spritesheets docs for full parameter details. |
animation
Generates an animated image from a video clip. The fm parameter selects the output format:
fm value | Output |
|---|---|
gif (or omit fm) | Animated GIF |
webp | Animated WebP |
avif | Animated AVIF |
png | Animated PNG (APNG) |
jxl | Animated JXL (see note) |
jpg and other still-only formats | Single still frame — the animation flag is silently ignored |
JXL note: the current FFmpeg build has no animated JPEG XL encoder, so Iris first renders an animated WebP; the downstream imgix image pipeline transcodes it to animated JXL for delivery.
WebP and AVIF are full-color and substantially smaller than GIF. Animated AVIF produces the smallest files.
You can control the clip window with the clip parameters.
The output can be transformed with any Rendering API parameter. For example, auto=compress,format applies optimal compression, and fit controls resizing.
Defaults and limits:
| Property | Default | Cap |
|---|---|---|
| Duration | 5 s | 10 s (min 0.25 s) |
| Frame rate | 15 fps | 30 fps (never above source fps) |
| Width / height | 320 px on unset axis | 640 px per axis (never above source) |
| Loop | Infinite | — |
Use video-loop to control loop behavior: omitting video-loop or setting a negative value loops forever; video-loop=0 plays once; video-loop=N plays N additional times after the first.
gif
Legacy alias for video-generate=animation&fm=gif. Fully supported for backwards compatibility, but new integrations should prefer video-generate=animation&fm=gif for clarity and access to all animated formats. See the animation section for demos and full parameter details.
thumbnail
Generates a static thumbnail image from the video. The fm parameter specifies the output image format (e.g. fm=jpg, fm=png).
The thumbnail frame is auto-selected as the most representative frame using color-histogram scoring, which avoids solid-color and black frames. To extract a thumbnail at a specific time, use video-thumbnail instead.
If fm=gif is also present, video-generate=thumbnail takes precedence and returns a single still frame rather than an animation.
