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 x for resizing and cropping to exact dimensions.
  • Optionally specify crop center with {cx}-{cy}.
  • 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
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

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.
  • Requests beyond this limit will not be served.