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:
- Select the checkboxes next to the parameters you want to adjust. Checking a box displays the corresponding control (slider or dropdown) for that parameter.
- 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.
- For format, fit, and position, choose the desired option from the dropdown menus, such as fill or center.
- 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.
2. Select parameters:
3. Your query:
https://cdn.builder.io/api/v1/image/assets%2FYJIGb4i01jvw0SRdL5Bt%2F869bfbaec9c64415ae68235d9b7b1425As 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.
| Name | Description |
|---|---|
| Compression quality ranging from |
| 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 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. |
| The image or photo's file format. By default, Builder uses the format of the uploaded image, which includes multiple image types such as |
| When Valid values are This parameter only has an effect if the For more detail, visit Sharp's documentation on image resizing. |
| When For example, if you download a 200x200 image using the query parameters Valid values are This parameter only has an effect if 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:
- Go to the Models section in Builder.
- Click the + Create Model button.
- Choose Data.
- Name the model in the Name field and fill out the Description field.
- Click Create.
- For Type, choose File.
- In the Fields tab, click the + New Field button.
- Name your field and choose the Type of File.
- In the Allowed file types section that opens, check .jpeg and .png.
- At the top of the page, click Save.
Next, create an entry with the new Data model:
- Go to Content.
- Click the + New Entry button and select your Data model.
- Name the entry and choose a photo or image.
- 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.
