Skip to content
HTML/CSS to ImageDocs

Choose a recording’s format, frame rate, and size

output is an object that sets a recording’s file format, frame rate, and output size. For images, use format instead.

The extension on recording_url matches the format, for example …/v1/recording/{id}.gif. Recordings have no audio track.

Field Type Default Description
format String mp4 mp4, webm, or gif.
fps Integer 30 (MP4, WebM)
15 (GIF)
Frames per second. MP4 and WebM accept 10–120. GIF accepts 10–50.
scale Number 1 Resizes the finished video without changing the page layout. 0.5 halves the width and height. Must be greater than 0.01.

Leaving output out gives an MP4 at 30 fps with no scaling. A GIF defaults to 15 fps.

Format Content type Use it for
mp4 video/mp4 Most places: social media, email links, <video> tags, and video editors.
webm video/webm Web pages where you control the <video> tag. Often smaller than MP4.
gif image/gif Places that only accept images, like READMEs, some email clients, and chat apps.

GIFs are much larger than MP4 or WebM at the same size and length. For a GIF, start with fps: 15 and scale: 0.5, and keep it short.

{
"url": "https://example.com/",
"viewport_width": 1280,
"viewport_height": 720,
"device_scale": 1,
"duration_ms": 6000,
"actions": [{ "type": "simple_scroll" }],
"output": { "format": "gif", "fps": 15, "scale": 0.5 }
}
{
"html": "…",
"viewport_width": 1920,
"viewport_height": 1080,
"device_scale": 1,
"duration_ms": 5000,
"duration_mode": "fixed",
"output": { "format": "mp4", "fps": 60 }
}

Capture at 2× density, then scale the output back down:

{
"url": "https://example.com/",
"viewport_width": 1280,
"viewport_height": 720,
"device_scale": 2,
"duration_ms": 10000,
"actions": [{ "type": "simple_scroll" }],
"output": { "format": "webm", "scale": 0.5 }
}

Resolution: viewport, device_scale, and scale

Section titled “Resolution: viewport, device_scale, and scale”

Three settings decide the final pixel size:

  1. viewport_width / viewport_height: the browser window in CSS pixels. This controls layout and responsive breakpoints.
  2. device_scale: pixel density during capture. 2 captures at twice the CSS size for sharp, retina-quality text.
  3. output.scale: resizes the finished media. It doesn’t change layout or capture work.
output width = floor(ceil(viewport_width × device_scale) × output.scale)
output height = floor(ceil(viewport_height × device_scale) × output.scale)
Viewport device_scale output.scale Output size
1280 × 720 1 1 1280 × 720
1280 × 720 2 1 2560 × 1440
1280 × 720 2 0.5 1280 × 720, sharper than the first row
1080 × 1080 1 0.5 540 × 540

The output width and height must each be 2–6000 pixels. Video encoders may round the size slightly so it works with the codec.

Capture work is limited to 3840 × 2160 pixels at 60 fps, or 497,664,000 pixels per second:

ceil(viewport_width × device_scale) × ceil(viewport_height × device_scale) × fps ≤ 497,664,000

This uses device_scale but not output.scale, because scaling happens after capture. If a request goes over the limit, it’s rejected with a 400. To fix it, lower the viewport, device_scale, or fps.

Viewport device_scale fps Pixels per second OK?
1920 × 1080 2 60 497,664,000 ✅ At the limit
1920 × 1080 2 120 995,328,000 ❌ Lower fps to 60
1920 × 1080 1 120 248,832,000 ✅
1800 × 1800 (HTML default) 2 (HTML default) 30 388,800,000 ✅

Need help?

Talk to a human. Email support@htmlcsstoimage.com and we’ll help you get started.