Made in Builder

Made in Builder

×

Developers

Product

Use Cases

Pricing

Developers

Resources

Company

Get StartedLogin

Product

Features

Integrations

Talk to an Expert

Pricing

Blog

Home

Resources

Blog

Forum

Github

Login

Signup

×

Visual CMS

Drag-and-drop visual editor and headless CMS for any tech stack

Theme Studio for Shopify

Build and optimize your Shopify-hosted storefront, no coding required

Resources

Blog

Get StartedLogin

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:

  1. Edit the field's Name.
  2. Select File as the field's Type.
  3. 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:

Query parameter reference

NameDescription

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?