# 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: {% embed url="" %} {% hint style="info" %} The tool used in the video is available here: . This tool will consume API image, we recommend using [Sandbox mode](/image-editing-api-plus-plan/sandbox-mode.md) if you want to test for free. {% endhint %} ## New AI Shadows Model {% hint style="warning" %} Warning: this new AI Shadows model is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. {% endhint %} ### 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! {% hint style="info" %} This tool will consume API image, we recommend using [Sandbox mode](/image-editing-api-plus-plan/sandbox-mode.md) if you want to test for free. {% endhint %} ### 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:

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: ```bash 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`

If you want to give it a try, here's the code to reproduce the first example above: ```bash 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`

(original image)

shadow.mode=ai.auto-with-overrides

shadow.softnessOverride=0.3

shadow.mode=ai.auto-with-overrides

shadow.softnessOverride=0.7



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

(original image)

shadow.mode=ai.auto-with-overrides

shadow.intensityOverride=0.3

shadow.mode=ai.auto-with-overrides

shadow.intensityOverride=0.7

```bash 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. {% hint style="warning" %} 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 {% endhint %}



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

(original image)

shadow.mode=ai.auto-with-overrides

shadow.spreadOverride=short

shadow.mode=ai.auto-with-overrides

shadow.spreadOverride=medium

```bash 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. {% hint style="warning" %} 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 {% endhint %}



(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`

(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

```bash 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. {% hint style="warning" %} 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 {% endhint %}



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

(original image)

shadow.mode=ai.auto-with-overrides

shadow.subjectPoseOverride=flatlay

shadow.mode=ai.auto-with-overrides

shadow.subjectPoseOverride=upright



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

{% hint style="warning" %} If you've also added an [AI Background](/image-editing-api-plus-plan/ai-backgrounds.md) 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. {% endhint %} If you want to give it a try, here's the code to reproduce the examples above: {% code overflow="wrap" %} ```bash 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 ``` {% endcode %} Try it now! --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.photoroom.com/image-editing-api-plus-plan/ai-shadows.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.