Made in Builder.io

Ship Your First Personalized Web Experience webinar on June 15 @ 10AM PT. Register Now

Talk to Us
Product
Developers
Talk to Us

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

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:

// 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`
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.


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.

Connect with us

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

Get the latest from Builder.io

Developer Newsletter

Latest tips, tricks, and news for frontend developers from our blog

Product Newsletter

Latest features and updates on the Builder.io platform

By submitting, you agree to our Privacy Policy

Product

Features

Pricing

What's New

Resources

Documentation

Blog

Community Forum

Templates

Partners

Submit an Idea

Use Cases

Landing Pages

Headless CMS

Headless Storefront

Customer Showcase

Customer Success Stories

Builder.io logo

Visually build and optimize digital experiences on any tech stack. No coding required, and developer approved.

Get Started

Log In

Product

Features

Pricing

Integrations

Use Cases

© 2023 Builder.io, Inc.

Security

Privacy Policy

SaaS Terms