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%2F869bfbaec9c64415ae68235d9b7b1425Using 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`| Name | Description |
|---|---|
| Compression quality ranging from |
| 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 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. |
| The image's file format. The only supported value is currently |
| When Valid values are This param only has an effect if You can learn more at Sharp's documentation on image resizing. |
| When For example, if you download a 200x200 image using the query params Valid values are This param only has an effect if You can learn more at Sharp's documentation on image resizing. |
Looking to hire a third party to help with your project?
Submit a project request and our partnerships team will reach out to connect you with an Expert from our partner ecosystem.
