Dynamic Thumbnails

In many API responses, a thumbnail_url is returned. The size can be controlled with the thumb_width and thumb_height request parameters, but further customization is possible.

NOTE: It's OK to cache the thumbnail URL, but always use the API to retrieve the thumbnail URL as it may change over time. Periodic revalidation of asset publishing status is required, during which you should refresh the thumbnail URL. Do not store it as a canonical reference to the asset.

Summary

  • Use w or h for resizing by one dimension while preserving aspect ratio.
  • Use f to contain an image within a box, preserving aspect ratio and without cropping. A single number (500f) contains within a square box; {width}x{height}f (500x300f) contains within a specific box. The image may be enlarged if the box is bigger than the source.
  • Use m ({width}x{height}m) for the same contain behavior as f, except the image is never enlarged — sources already smaller than the box are returned at their original size.
  • Use x ({width}x{height}) for resizing and cropping to exact dimensions.
  • Optionally specify crop center with {cx}-{cy} (only applies to exact-dimension x requests).
  • Use _q to control JPEG quality (ignored for WebP).
  • Thumbnails are cached for fast delivery at scale.

Examples

Format Description Example URL
500h_q95.jpg Resize to 500px tall; width is auto-scaled. Link
500f_q95.jpg Contain within a 500×500px square box; the longest side is scaled to 500px and the shorter side is auto-scaled. Equivalent to 500x500f. Link
500x300f_q95.jpg Contain within a 500×300px box without cropping; the image is scaled proportionally so it fits entirely within both dimensions (it may end up smaller than 500×300 on one side). Link
800x800m_q95.jpg Scale down to fit within an 800×800px box without cropping, but never enlarge; sources already smaller than 800×800 are returned unchanged. Link
500x400_q95.jpg Resize and crop to exactly 500×400px. Link
500x400_50-50_q95.jpg Resize and crop to 500×400px, with crop centered at 50% left / 50% top of the source. Link

Contain vs Max vs Crop

  • Crop (500x400): resizes and crops to the exact requested dimensions. Part of the image may be cut off.
  • Contain (500f or 500x300f): scales proportionally so the entire image remains visible, with no cropping. May enlarge a smaller source to fill the box.
  • Max (800x800m): same as contain, but never enlarges — if the source is already smaller than the requested box, it's returned at its original size.

Cropping Behavior

  • When exact dimensions are provided (500x400), a crop is performed.
  • The crop center can optionally be specified as {cx}-{cy}, where:
    • cx = percentage from the left edge (0–100).
    • cy = percentage from the top edge (0–100).
  • If crop center is not specified:
    • Portrait images default to 50-0 (center horizontally, top vertically).
    • Landscape images default to 50-50 (center both horizontally and vertically).

Crop Center Visual Guide

  • 50-50 → Centered in the middle of the image
  • 50-0 → Centered horizontally, aligned at the top
  • 50-40 → Centered horizontally, 40% down from the top
  • 30-70 → 30% from left, 70% down from the top

This allows precise control over which part of the image is visible after cropping.

Quality Parameter

  • _q{value} specifies the JPEG quality (1–100).
  • Example: _q95 = 95% JPEG quality.
  • Note: When the client accepts WebP (most modern browsers), the quality parameter is ignored and images are served as WebP automatically.

Limits

  • Maximum supported dimensions: 2000×2000 pixels, for all formats (w, h, f, m, and x).
  • Requests beyond this limit will not be served.