AI Shadows

The Image Editing API allows you to add realistic shadows to the main subject of the input image.

Here's a demo of how you can use AI Shadows to create studio quality product images at scale:

The tool used in the video is available here: https://try-api.photoroom.com/shadows.

This tool will consume API image, we recommend using Sandbox mode if you want to test for free.

New AI Shadows Model

Overview

We've shipped a new model for AI Shadows that gives you complete control over the softness, intensity and position of the shadow.

To use this new model you will need to:

1. add the HTTP header pr-ai-shadows-model-version: 2026-04-15 to your API call

2. set the parameter shadow.mode to ai.auto-with-overrides

By default, this new model will automatically determine the best values for the softness, intensity and position of the shadow.

However, you also have access to 5 parameters that let you override each of these dimensions, to control the appearance of the shadow:

• shadow.softnessOverride, controls whether the shadow will have hard or soft edges

• shadow.intensityOverride, controls how dark the shadow will be

• shadow.spreadOverride, controls how long the shadow will be

• shadow.directionOverride, controls the direction of the shadow relative to the subject

• shadow.subjectPoseOverride, controls whether the subject is laying flat or standing upright

Under-the-hood, these parameters allow you to precisely control how the light source should be positioned relative to the subject:

Preview Tool

We've built a tool that will help you:

1. easily visualize the impact that each of these override parameters has

2. define the set of parameter values that will produce the result you're looking for

Try it now!

This tool will consume API image, we recommend using Sandbox mode if you want to test for free.

Auto Mode

When none of the 5 override parameters have been set, the model will fully determine the best shadow appearance for each input image:

shadow.mode=ai.auto-with-overrides

This can be useful because it enables you to immediately start using the feature, without needing to decide on a value for each override parameter

If you want to give it a try, here's the code to reproduce the example above:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --output result-with-auto-shadow.png

Try it now!

If needed, it's also possible to set a value for some of the override parameters, while letting the model determine the value of the others:

shadow.mode=ai.auto-with-overrides shadow.intensityOverride=0.9 shadow.spreadOverride=short

Deterministic Mode

When all 5 override parameters have been set, the appearance of the shadow becomes fully deterministic.

Doing so enables you to achieve a consistent shadow appearance at scale:

shadow.mode=ai.auto-with-overrides shadow.softnessOverride=0.3 shadow.intensityOverride=0.8 shadow.spreadOverride=medium shadow.directionOverride=behindLeft shadow.subjectPoseOverride=upright

shadow.mode=ai.auto-with-overrides shadow.softnessOverride=0.3 shadow.intensityOverride=0.8 shadow.spreadOverride=medium shadow.directionOverride=behindRight shadow.subjectPoseOverride=upright

If you want to give it a try, here's the code to reproduce the first example above:

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --form shadow.softnessOverride=0.3 \
  --form shadow.softnessOverride=0.3 \
  --form shadow.intensityOverride=0.8 \
  --form shadow.spreadOverride=medium \
  --form shadow.directionOverride=behindLeft \
  --form shadow.subjectPoseOverride=upright \
  --output result-with-deterministic-shadow.png

Try it now!

Override Parameters

shadow.softnessOverride

Controls whether the shadow will have hard or soft edges.

0 means a very hard shadow, 1 means a very soft shadow.

(original image)	shadow.mode=ai.auto-with-overrides shadow.softnessOverride=0.3	shadow.mode=ai.auto-with-overrides shadow.softnessOverride=0.7

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --form shadow.softnessOverride=0.3 \
  --output result.png

Try it now!

shadow.intensityOverride

Controls how dark the shadow will be.

0 means a very faint shadow, 1 means a very dark shadow.

(original image)	shadow.mode=ai.auto-with-overrides shadow.intensityOverride=0.3	shadow.mode=ai.auto-with-overrides shadow.intensityOverride=0.7

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --form shadow.intensityOverride=0.3 \
  --output result.png

Try it now!

shadow.spreadOverride

Controls how long the shadow will be.

Can be provided either as an angle in degrees or as one of the following presets:

• short (= 10°)

• medium (= 45°)

• long (= 90°)

When using degrees, 0 means a very short shadow and 90 means a very long shadow.

When using a value in degrees, only set a numeric value, do not add the ° character.

e.g.: 45 is a valid value, 45° is not a valid value

(original image)	shadow.mode=ai.auto-with-overrides shadow.spreadOverride=short	shadow.mode=ai.auto-with-overrides shadow.spreadOverride=medium

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --form shadow.spreadOverride=medium \
  --output result.png

Try it now!

shadow.directionOverride

Controls the direction of the shadow relative to the subject.

Can be provided either as an angle in degrees or as one of the following presets:

• behind (= 0°)

• behindLeft (= 45°)

• left (= 90°)

• frontLeft (= 135°)

• front (= 180°)

• frontRight (= 225°)

• right (= 270°)

• behindRight (= 315°)

When using degrees:

• 0 means the shadow is behind the subject

• 90 means the shadow is at the left of the subject

• 180 means the shadow is in front of the subject

• 270 means the shadow is at the right of the subject.

When using a value in degrees, only set a numeric value, do not add the ° character.

e.g.: 45 is a valid value, 45° is not a valid value

(original image)	shadow.mode=ai.auto-with-overrides shadow.directionOverride=behindLeft	shadow.mode=ai.auto-with-overrides shadow.directionOverride=frontLeft	shadow.mode=ai.auto-with-overrides shadow.directionOverride=frontRight	shadow.mode=ai.auto-with-overrides shadow.directionOverride=behindRight

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --form shadow.directionOverride=frontLeft \
  --output result.png

Try it now!

shadow.subjectPoseOverride

Controls whether the subject is laying flat or standing upright.

Can be provided either as an angle in degrees or as one of the following presets:

• flatlay (= 0°)

• upright (= 90°)

When using degrees, 0 means the subject is laying flat and 90 means the subject is placed upright.

When using a value in degrees, only set a numeric value, do not add the ° character.

e.g.: 45 is a valid value, 45° is not a valid value

(original image)	shadow.mode=ai.auto-with-overrides shadow.subjectPoseOverride=flatlay	shadow.mode=ai.auto-with-overrides shadow.subjectPoseOverride=upright

curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'pr-ai-shadows-model-version: 2026-04-15' \
  --form imageFile=@/path/to/your/image.jpg \
  --form background.color=FFFFFF \
  --form outputSize=1920x1080 \
  --form padding=0.15 \
  --form shadow.mode=ai.auto-with-overrides \
  --form shadow.subjectPoseOverride=flatlay \
  --output result.png

Try it now!

Previous AI Shadows Model

To add a realistic shadow, set the argument shadow.mode with one of the following values:

(original image)	shadow.mode=ai.soft	shadow.mode=ai.hard	shadow.mode=ai.floating

If you've also added an AI Background to your image, then it's not recommended to also add an AI Shadow as the generated background will already include a shadow for the subject.

If you want to give it a try, here's the code to reproduce the examples above:

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 shadow.mode=ai.soft \
  --output with-realistic-shadow.png

Try it now!