Register Now: Use Visual Dev + AI to Ship 10x Faster on July 24

Announcing Visual Copilot - Figma to production in half the time

Builder.io logo
Contact Sales
Contact Sales

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

The Image API is a read-only API to help developers download optimized versions of previously uploaded images, providing seamless integration with your existing image content.

The API supports multiple images and various visual content types, such as photos, png image, and other image files. Crafting your requests with the API explorer also helps you request images to your specified dimensions.

To make images available through the API, you must first add the image content using Image blocks in the Visual Editor or fields when working with CMS Data models.

Requests take the following format:

https://cdn.builder.io/api/v1/image/<filename>?<params>
  • <filename> is the name of your requested image or photo, typically auto-generated by Builder at upload time.
  • <params> are settings that determine the image properties such as height and width in pixels, meaning you can retrieve the image in your specified dimensions.

Use the API Explorer below to experiment with the API's query parameters. This interactive tool provides a way to discover how different parameter combinations affect the output image or photo.

It's useful for understanding the wide array of API options, testing various API settings, and generating the desired API query URL for your specific image optimization needs.

To use the API explorer:

  1. Select the checkboxes next to the parameters you want to adjust. Checking a box displays the corresponding control (slider or dropdown) for that parameter.
  2. Use the sliders to set numeric values for quality, height, and width. Move the slider handles to change the values and generate the updated URL below.
  3. For format, fit, and position, choose the desired option from the dropdown menus, such as fill or center.
  4. As you make changes, the URL at the bottom updates in real time, showing the constructed request with your selected parameters. You can copy this generated URL to use in your application or for further testing.

Experiment with different combinations to discover how the output image reflects the chosen parameters and how you can take advantage of the power and speed of the Image API at scale.

API Explorer

To learn more about the features and details of the API, use this explorer to choose an image or photo and check options that generate a request.

Selected

2. Select parameters:

3. Your query:

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

As you might gather from the tool above, this API supports a number of query parameters for customizing and optimizing images and photos, providing control over specified dimensions, quality, format, and other properties.

This section of the document provides a comprehensive reference for each available parameter, covering their purposes, accepted values, default behaviors, and interactions.

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 the default. Adjusting the quality parameter means you can find the optimal balance between image or photo quality and file size for your specific needs.

height

Height of the output image in pixels. If no value is provided, it defaults to the original image's intrinsic height.

Note that the API doesn't upscale images or photoes. Values greater than the original image's intrinsic height result in an image with the same dimensions as the original image.

width

Width of the output image or photo in pixels. If no value is provided, it defaults to the image's intrinsic width.

Note that the API doesn't upscale images or photos. Values greater than the image's intrinsic width result in an image with the same dimensions as the original image.

format

The image or photo's file format. By default, Builder uses the format of the uploaded image, which includes multiple image types such as jpg, jpeg, png, or gif. However, we recommend using ?format=webp to override any of those file types to be webp, which provides better image optimization.

fit

When height or width are set in the request, the fit parameter determines how to handle the image or photo's aspect ratio.

Valid values are cover, contain, fill, inside, and outside. If no value is provided, cover is chosen by default.

This parameter only has an effect if the format is set to webp.

For more detail, visit Sharp's documentation on image resizing.

position

When height or width are set in the request, the position parameter determines the location of the image or photo's anchor point for cropping.

For example, if you download a 200x200 image using the query parameters height=100&width=100&format=webp&position=bottom left, your downloaded image will be a 100x100 square, cropping 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 parameter only has an effect if format is set to webp.

For more detail about image resizing and aspect ration handling, visit Sharp's documentation on image resizing.

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

First, create the Data model:

  1. Go to the Models section in Builder.
  2. Click the + Create Model button.
  3. Choose Data.
  4. Name the model in the Name field and fill out the Description field.
  5. Click Create.
  6. For Type, choose File.
  7. In the Fields tab, click the + New Field button.
  8. Name your field and choose the Type of File.
  9. In the Allowed file types section that opens, check .jpeg and .png.
  10. At the top of the page, click Save.

Next, create an entry with the new Data model:

  1. Go to Content.
  2. Click the + New Entry button and select your Data model.
  3. Name the entry and choose a photo or image.
  4. Click the Publish button.

This content focuses on using a Data model with the Image API. For more details, read the Data Models and Custom Fields documentation.

You can now access your image or photo URL programmatically using the Content API. The following code examples use 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 or photo URL is available on your File field.
const imageUrl = content.data.avatar;

// Create variants of the image by adding query params
const variantUrl = `${imageUrl}?height=200&width=200&quality=90&fit=fill`;


// Using a `Photo` model (you'd make this model yourself)

const photoContent = await builder.get('Photo').toPromise();
const photoUrl = photoContent.data.url;


// Generate a request for a specific size and quality
const photoVariantUrl = `${photoUrl}?width=500&quality=80`;

A leader among image APIs, the Builder Image API provides businesses and developers a powerful tool for managing and optimizing visual content across various platforms and devices.

By leveraging this API, developers can seamlessly integrate image optimization capabilities into their applications, ensuring fast, responsive, and visually appealing images and photos for users at scale.

Was this article helpful?

Product

Visual CMS

Theme Studio for Shopify

Sign up

Login

Featured Integrations

React

Angular

Next.js

Gatsby

Get In Touch

Chat With Us

Twitter

Linkedin

Careers

© 2020 Builder.io, Inc.

Security

Privacy Policy

Terms of Service

Newsletter

Get the latest from Builder.io

By submitting, you agree to our Privacy Policy