Rendering thumbnails

Urlbox has two different ways to produce a smaller image from a render. Understanding when to use each will help you get the result you want.

If you just need a smaller version of your screenshot, use thumb_width / thumb_height. If you need several different sizes, or want thumbnails stored as their own files, use thumbnails.

Basic example with presets

The easiest way to create a thumbnail is with a size preset, which scales the thumbnail as a percentage of the main screenshot's dimensions:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "preset": "sm"
    },
    {
      "preset": "lg"
    }
  ]
}'

Available presets

For example, on a 1280x800 screenshot, preset: "sm" (20%) produces a 256x160 thumbnail.

Custom dimensions

Instead of a preset, you can give exact pixel dimensions. width and height can be set independently, each between 10 and 2000 pixels:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "width": 200,
      "height": 150
    },
    {
      "width": 400,
      "height": 300
    }
  ]
}'

Square thumbnails

Use size as a shorthand for equal width and height:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "size": 100
    },
    {
      "size": 200
    }
  ]
}'

Fit, position and background

Each thumbnail spec can set its own fit, position and bg. If a spec omits one of these, it falls back to the equivalent top-level render option, and finally to a fixed default:

fit controls how the image is resized to the target dimensions:

position accepts any img_position value, including attention and entropy, which crop around the most visually interesting or highest-entropy region of the image rather than a fixed edge or corner.

When fit: "contain" leaves empty space around the image, bg fills it:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "size": 200,
      "fit": "contain",
      "bg": "#5F1EE6"
    }
  ]
}'

Naming thumbnails with key and suffix

Each thumbnail spec is given a filename suffix (and, in the JSON response, an identifying key) resolved from whichever of these properties is set, in priority order: key → suffix → preset → size → width → height → "thumb".

key and suffix are not interchangeable: if both are omitted, the filename falls through to the calculated dimensions and finally to the literal string thumb. Setting key also determines the property name used to look up this thumbnail when thumbnails_object is enabled, so prefer key over suffix whenever you need a stable, predictable identifier. key is limited to 10 characters.

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "preset": "sm",
      "key": "nav"
    },
    {
      "preset": "lg",
      "key": "hero"
    }
  ]
}'

Uploading to your own storage

Each thumbnail spec can carry its own presigned_url to upload that specific thumbnail directly to a URL you control, instead of Urlbox's own storage. This is useful when different thumbnail sizes need to land in different buckets or paths. See the storage guides for background on configuring your own storage.

The query-string form

The examples above show a JSON request body, where thumbnails is a plain array. Over a GET request, the same array is sent as a query string using qs-style bracket notation:

&thumbnails[0][preset]=md&thumbnails[1][width]=320&thumbnails[1][key]=w320

which is equivalent to the JSON body:

{
  "thumbnails": [{ "preset": "md" }, { "width": 320, "key": "w320" }]
}

Response format

By default, thumbnails_object is false and thumbnails come back as an array, each entry carrying its own key:

{
  "renderUrl": "https://renders.urlbox.com/.../abc123.png",
  "thumbnails": [
    { "key": "nav", "location": "https://renders.urlbox.com/.../abc123-nav.png", "size": 12345 },
    { "key": "hero", "location": "https://renders.urlbox.com/.../abc123-hero.png", "size": 56789 }
  ]
}

Setting thumbnails_object to true reshapes this into an object keyed by each thumbnail's key/suffix, with key omitted from each value since it's now the object's own key:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "preset": "sm",
      "key": "small"
    },
    {
      "preset": "lg",
      "key": "large"
    }
  ],
  "thumbnails_object": true
}'

{
  "renderUrl": "https://renders.urlbox.com/.../abc123.png",
  "thumbnails": {
    "small": { "location": "https://renders.urlbox.com/.../abc123-small.png", "size": 12345 },
    "large": { "location": "https://renders.urlbox.com/.../abc123-large.png", "size": 56789 }
  }
}

Limits

• Maximum of 5 thumbnails per request.
• Each size, width and height must be between 10 and 2000 pixels.
• key is limited to 10 characters.

Use cases

Responsive images

Generate the handful of sizes a responsive <img srcset> needs in one render:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "width": 320,
      "key": "mobile"
    },
    {
      "width": 768,
      "key": "tablet"
    },
    {
      "width": 1200,
      "key": "desktop"
    }
  ],
  "thumbnails_object": true
}'

Social media previews

Different platforms expect different crop ratios for link previews, so generate them all from a single render rather than resizing client-side:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "width": 1200,
      "height": 630,
      "key": "og"
    },
    {
      "width": 1200,
      "height": 675,
      "key": "twitter"
    },
    {
      "size": 400,
      "key": "square"
    }
  ],
  "thumbnails_object": true
}'

Gallery thumbnails

Consistent, cropped square thumbnails for an image grid:

curl -X POST \
  https://api.urlbox.com/v1/render/sync \
  -H 'Authorization: Bearer YOUR_URLBOX_SECRET' \
  -H 'Content-Type: application/json' \
  -d '{
  "url": "https://stripe.com",
  "thumbnails": [
    {
      "size": 150,
      "fit": "cover",
      "key": "grid"
    },
    {
      "size": 300,
      "fit": "cover",
      "key": "preview"
    }
  ]
}'