File size, resolution and format

Which image formats are supported?

For the input and result images, the Image Editing API supports four formats: PNG, JPEG, WEBP and AVIF.

By default, the result image will be in PNG format.

To configure the format of the result image, set the argument export.format with one of the following values:

• png is the lossless PNG format (biggest file size, zero quality loss, transparency is saved)

• jpeg or jpg for JPEG format (smaller file size, transparency is not saved)

• webp for WebP format (even smaller file size, transparency is saved)

• avif for AVIF format (smallest file size, takes a few seconds longer to create, transparency is saved)

JPEG, WebP export with a quality of 90. AVIF uses 75 which has the same or higher fidelity according to benchmarks

JPEG format does not support transparency.

Asking the Image Editing API to export in JPEG while also setting a background color with transparency will result in an error.

If you want to give it a try, here's the code to export an image in JPEG format:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1000x1000 \
  --form padding=0.1 \
  --form 'export.format=jpeg' \
  --output result.jpeg

Try it now!

And here's the code to export an image in WebP format:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1000x1000 \
  --form padding=0.1 \
  --form 'export.format=webp' \
  --output result.webp

Try it now!

And the code to export an image in AVIF format:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1000x1000 \
  --form padding=0.1 \
  --form 'export.format=avif' \
  --output result.avif

Try it now!

Preserving the input colour space (colorSpace: "original")

By default the Image Editing API returns results in sRGB. Set colorSpace: "original" on /v2/edit to keep the input image's own colour space and embedded ICC profile (e.g. Adobe RGB, Display P3) in the output — preserved with no conversion to sRGB. This applies to background removal (including HD): the cutout is returned as a PNG carrying the original ICC profile.

• Default (omit colorSpace, or colorSpace=sRGB): output is sRGB, exactly as before.

• colorSpace=original: output keeps the input's colour space + ICC profile.

When it works

A pure background removal (no other edits), with PNG output, on an input that has an embedded colour profile.

When it returns HTTP 400

colorSpace: "original" only applies to a plain background removal that outputs PNG. The request is rejected with a 400 (the error names the conflicting parameter) if it also includes:

• Any operation beyond background removal — AI/replacement backgrounds, a background colour or image, shadows, relighting, templates, etc.

• An output format other than PNG (e.g. JPG, WebP, AVIF).

• export.dpi.

• keepExistingAlphaChannel set to anything other than never.

• preserveMetadata set to an EXIF-subset mode.

curl -X POST https://image-api.photoroom.com/v2/edit \
    -H "x-api-key: YOUR_API_KEY" \
    -F "imageFile=@product.jpg" \
    -F "removeBackground=true" \
    -F "colorSpace=original" \
    -F "export.format=png" \
    -o cutout.png

{
    "error": {
      "message": "colorSpace: \"original\" is only supported when the request is a pure background removal with PNG output. Conflicting parameter: \"background\"."
    }
  }

If the input image has no embedded colour profile, there's nothing to preserve — the output carries the image's native colour as-is.

What are the max resolution and size of the image?

We recommend limiting images to 25 megapixels for optimal performance.

• Maximum File Size: 30MB

• Maximum Resolution: 5,000 pixels on the widest side

Images with a larger resolution are supported (if they stay below 30MB), but will be resized down to 5,000 pixels on the widest side.

Please note that large images will result in API calls taking a longer time to complete.

If you experience timeouts, we recommend that you try to increase the default timeout of your networking library.