Quickstart Guide

Who is this API for?

The Image Editing API enables anyone to easily create high-quality images.

This is what a typical call to the API looks like:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --form imageFile=@/absolute/path/to/image.jpg \
  --form removeBackground=true \
  --form background.color=FFFFFF \
  --form padding=0.15 \
  --form shadow.mode=ai.soft \
  --output result.png

If you don't yet have an apiKey, here are the steps to create yours.

And these are examples of results that this API call produces:

(original image)	(result image)

Let's go over the parameters of this API call.

imageFile=@/absolute/path/to/image.jpg

This parameter represents the input image that you want to edit.

This image can be provided either:

• as a file, using the parameter imageFile

• as a URL, using the parameter imageUrl

More details about maximum file size, resolution and image formats are available here.

removeBackground=true

This parameter specifies that the background of the input image should be removed.

removeBackground is set to true by default, so you can omit it when you want the background to be removed

background.color=FFFFFF

This parameter creates a new background that consists of a white solid color.

Alternatively to using a solid color, you can also opt for:

• having a transparent background (this is this the default behavior)

• using a static image

• creating an AI Background

padding=0.15

This parameter adds 15% of padding around the subject, for a more visually pleasing result.

The positioning of the subject in the result image is fully customizable, you can read more about it here.

shadow.mode=ai.soft

This parameter adds a realistic shadow to the subject, which helps the result image look more natural.

The look of the shadow can be customized, you can read more about it here.

How do I configure my first API call?

We designed the Image Editing API so that it’s both very powerful and very easy to use:

1. First, you’ll use our interactive playground to define the edits you want to apply to your images (such as removing the background, resizing, adding padding, etc.)

Please note that not all features of the Image Editing API are available in the API Playground

1. Then, the playground will automatically generate the code to make the API call.

We recommend that you try the playground by yourself: it’s really the best way to get a sense of what the API can do.

The playground should be pretty intuitive to use, but if you want a detailed overview of its features, you can watch this video:

To read more about each attribute available for the API endpoint, please have a look at our API reference documentation.

Which endpoints are available?

The Image Editing API exposes two endpoints.

GET endpoint

GET https://image-api.photoroom.com/v2/edit

The GET endpoint expects you to:

• configure the edits you want to apply through query string arguments

• provide the input image as a URL, through the argument imageUrl

This means that the images you process through that endpoint must already be hosted on the Internet.

Here's an example of an API call made using the GET endpoint:

curl 'https://image-api.photoroom.com/v2/edit?shadow.mode=ai.soft&background.color=FFFFFF&padding=0.1&imageUrl=URL_OF_YOUR_IMAGE' \
--header 'x-api-key: YOUR_API_KEY' \
--output result-get-endpoint.png

The full API reference documentation of this endpoint is available here

POST endpoint

POST https://image-api.photoroom.com/v2/edit

The POST endpoint allows you to:

• directly upload an image file, through the argument imageFile

• configure the edits through the body of the request rather than the query string

Here's an example of an API call made using the POST endpoint:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'Accept: image/png, application/json' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: YOUR_API_KEY' \
  --form imageFile=@/absolute/path/to/image.jpg \
  --form shadow.mode=ai.soft \
  --form background.color=FFFFFF \
  --form padding=0.1 \
  --output result-post-endpoint.png

The full API reference documentation of this endpoint is available here