Index
Edit

Image URLs

The anatomy of the image url

Let's dissect this Sanity image-url:

https://cdn.sanity.io/images/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg

https://cdn.sanity.io/images/ is the common base for all Sanity image urls. It is followed by the project id (zp7mbokg in this instance), the dataset (production) and then the asset id which is comprised of a name (G3i4emG6B8JnTmGoN0UjgAp8) a dash then the width and height of the original image (300x450) and the file format of the original image (jpg).

The image urls can always be found in the asset-document referred to by an image, but you don't actually have to fetch this document as the asset document id contains all the information (and represents a stable, documented interface you can trust).

The asset id corresponding the the url above looks like this: "image-G3i4emG6B8JnTmGoN0UjgAp8-300x450-jpg". As you can see it provides the name, dimensions and format. Given the project id and dataset name you have every piece you need to assemble the url without fetching the asset document:

https://cdn.sanity.io/images/<project id>/<dataset name>/<asset name>-<original width>x<original height>.<original file format>

So this represents the base url. If you fetch this you will be served the original asset. This wastes a lot of bandwidth as content managers should upload full resolution assets. The Sanity image pipeline therefore scales, crops and processes images on the fly for you based on the url-parameters your provide. E.g. by appending ?h=200 to the base url you instruct Sanity to scale the image to be 200 pixels tall:

https://cdn.sanity.io/images/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg?h=200

You can specify any number of parameters. This will extract a rectangle from the image, scale it to 200 pixels tall and blur it:

https://cdn.sanity.io/images/zp7mbokg/production/G3i4emG6B8JnTmGoN0UjgAp8-300x450.jpg?rect=70,20,120,150&h=200&blur=10

Gotcha

Small images get scaled up to the width or height you specify. To avoid this use &fit=max.

Even though the Sanity image backend is fast, you get a tremendous performance boost if your frontend limits the number of sizes and crops you ask for. Sanity will cache the result in the global CDN, and if we see the same url again we serve the exact same data directly from the edge cache closest the the user.

The URL parameters

Width: w=<pixels>

Scale the image to be that wide.

Height: h=<pixels>

Scale the image to be that tall.

Limit sizes: min-h=<pixels>, max-h=<pixels>, min-w=<pixels>, max-w=<pixels>

Specifies size limits giving the backend some freedom in picking a size according to the source image aspect ratio.

Fit: fit=<clip, crop, fill, fillmax, max, scale, min>

Affects how the image is handled when you specify target dimensions.

  • clip: The image is resized to fit within the bounds you specified without cropping or distorting the image.
  • crop: Crops the image to fill the size you specified when you specify both w and h
  • fill: Like clip, but the any free area not covered by your image is filled with the color specified in the bg parameter.
  • fillmax: Places the image within box you specify, never scaling the image up. If there is excess room in the image, it is filled with the color specified in the bg parameter.
  • max: Fit the image within the box you specify, but never scaling the image up.
  • scale: Scales the image to fit the constraining dimensions exactly. The resulting image will fill the dimensions, and will not maintain the aspect ratio of the input image.
  • min: Resizes and crops the image to match the aspect ratio of the requested width and height. Will not exceed the original width and height of the image.

Crop: crop=<top, bottom, left, right, center, focalpoint, entropy>

Use with fit=crop to specify how cropping is performed:

  • top, bottom, left and right: The crop starts from the edge specified. crop=top,left will crop the image starting in the top left corner.
  • center: Will crop around the center of the image
  • focalpoint: Will crop around the focal point specified using the fp-x and fp-y parameters.
  • entropy: Attempts to preserve the "most important" part of the image by selecting the crop that preserves the most complex part of the image.

Focal point: fp-x=<coordinate>, fp-y=<coordinate>

Specify a center point to focus on when cropping the image. Values from 0.0 to 1.0 in fractions of the image dimensions. (See crop)

Rectangle: rect=<left>,<top>,<width>,<height>

Crop the image according to the provided coordinates (in pixel units of the source image).

Format: fm=<jpg, pjpg, png or webp>

Specifies the file format of the image.

Quality: q=<0-100>

Specify the compression quality (where applicable).

Download: dl=<suggested file-name>

Configures the headers so that opening this link causes the browser to download the image rather than showing it. The browser will suggest to use the file name you provided.

Image processing: blur=<0-100>, sharpen=<0-100>, invert

Blur, sharpen or invert the image.

Orientation: or=<0, 90, 180 or 270>

Rotate the image in 90 degree increments.

Flipping: flip=h, flip=v, flip=hv

Flip image horizontally, vertically or both.

Previous: AssetsNext: Asset CDN