Image sizes

When you add an image to your Typeform account, we resize it for different uses on different devices and to improve the load speed of your typeforms. This resizing applies to all file formats: JPEG, PNG, and GIF.

Three endpoints in the Create API allow you to retrieve images by size: Retrieve image by size, Retrieve background by size, and Retrieve choice image by size.

To specify the image size you want to retrieve, add a path parameter to your request URL. For example, to retrieve the mobile-sized version of an image that you want to use to illustrate a question, your request URL will look like this:

https://images.typeform.com/images/{image_id}/image/mobile

Available image size values depend on the endpoint you're using. Also, the image size values apply different scaling methods. Read on for details about the scaling methods and the image size values that are available for each endpoint.

Images are resized based on one of three scaling methods:

• Width: the image is scaled down to fit a specific width.
• Fit: the image is scaled to "fit" within a specific width and height. The image is scaled to satisfy the largest dimension.
• Thumbnail: the image is scaled so that the smallest image side is the same as the largest of the parameter box and then cropped.

The scaling method is applied based on the image size value you select.

Retrieve image by size

Use the GET https://images.typeform.com/images/{image_id}/image/{size} endpoint to retrieve images for illustrating questions, welcome screens, and thank you screens.

Here are the valid values for {size}, with their scaling methods and dimensions:

Retrieve background by size

Use the GET https://images.typeform.com/images/{image_id}/background/{size} endpoint to retrieve images you want to use as a background.

Here are the valid values for {size}, with their scaling methods and dimensions:

NOTE: Images used to personalize typeform backgrounds are scaled and cropped from a top-left alignment to make sure they fill the screen properly.

Retrieve choice image by size

Use the GET https://images.typeform.com/images/{image_id}/choice/{size} endpoint to retrieve images to use as picture_choice question options.

Here are the valid values for {size}, with their scaling methods and dimensions:

Take a look at some walkthroughs for the Create API, then check out the Create reference for more endpoints.