Image API

You can use Builder's Image API to access and download optimized versions of images that you've uploaded.

Overview

Image API requests take the following format:

https://cdn.builder.io/api/v1/image/<filename>?<params>

<filename> is the name of your image file, typically auto-generated by Builder at upload time.
<params> are settings that determine the image's height, width, and so on.

The Image API is a read-only API for downloading previously uploaded images. All images must be manually uploaded using Image blocks in the Visual Editor or File fields when working with CMS Data models.

Image API explorer

You can use the tool below to experiment with the Image API's query parameters.

Image API URL:

https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F869bfbaec9c64415ae68235d9b7b1425

Using the Image API with CMS Data models

A common use case for the Image API is to download variants of images stored in CMS Data models.

To get started, create a CMS Data model and add a File field:

When adding your new field:

Edit the field's Name.
Select File as the field's Type.
Confirm that only ".jpeg" and ".png" are selected under Allowed file types.

Click Save once you've finished adding your new field.

Now create a new content item for your model. Click on Choose Photo to upload the image for your field.

Click Publish once you've uploaded your image and finished creating your content item.

You can now access your image URL programmatically using the Content API. The following example uses Builder's JavaScript SDK:

// For a CMS Data model named 'user', querying a user profile
// with the username 'cparker'.
const content = await builder
  // Replace the model name and options object with your own
  // model name and query options.
  .get('user', { query: { 'data.username': 'cparker' } })
  .toPromise();

// Your uploaded image's URL is available on your File field.
const imageUrl = content.data.avatar;

// Create variants by adding Image API query parameters.
const variantUrl = `${imageUrl}?height=200`

Query parameter reference

Name	Description
`quality`	Compression quality ranging from `1` (worst quality, smallest file size) to `100` (best quality, largest file size). If no value is provided, `85` is chosen by default.
`height`	Height in pixels. If no value is provided, defaults to the image's intrinsic height. Note that the Image API doesn't upscale. Values greater than the image's intrinsic height are equivalent to the intrinsic height.
`width`	Width in pixels. If no value is provided, defaults to the image's intrinsic width. Note that the Image API doesn't upscale. Values greater than the image's intrinsic width are equivalent to the intrinsic width.
`format`	The image's file format. The only supported value is currently `webp`. If no value is provided, defaults to JPEG.
`fit`	When `height` or `width` are set in the query, `fit` determines how to handle the image's aspect ratio. Valid values are `cover`, `contain`, `fill`, `inside`, and `outside`. If no value is provided, `cover` is chosen by default. This param only has an effect if `format` is set to `webp`. You can learn more at Sharp's documentation on image resizing.
`position`	When `height` or `width` are set in the query, `position` determines the location of the image's anchor point for the purpose of cropping. For example, if you download a 200x200 image using the query params `height=100&width=100&format=webp&position=bottom left`, your downloaded image will be a 100x100 square taken from the bottom left corner of the original image. Valid values are `top`, `right top`, `right`, `right bottom`, `bottom`, `left bottom`, `left`, `left top`, and `center`. If no value is provided, `center` is chosen by default. This param only has an effect if `format` is set to `webp`. You can learn more at Sharp's documentation on image resizing.

Was this article helpful?