Image Editing v2 (Plus plan)
Changed onThis endpoint processes an image and applies one or more edits: background removal, AI-generated backgrounds (background.prompt), realistic shadows (shadow.mode), relighting (lighting.mode), text removal (textRemoval.mode), background blur (background.blur.), subject outline (outline.), AI beautification (beautify.mode), Flat Lay (flatLay.), Ghost Mannequin (ghostMannequin.), Ironing (ironing.mode), Virtual Model (virtualModel.*), AI expand (expand.mode), AI uncrop (uncrop.mode), AI upscale (upscale.mode), and positioning/resizing (padding, margin, outputSize).
Parameters are grouped by feature using dot notation: background.* for backgrounds, shadow.* for shadows, lighting.* for relighting, outline.* for subject outlines, beautify.* for AI beautification, flatLay.* for flat lay generation, ghostMannequin.* for ghost mannequin generation, ironing.* for wrinkle removal, virtualModel.* for virtual model generation, expand.* for AI expand, uncrop.* for AI uncrop, upscale.* for AI upscale, export.* for output format, and segmentation.* for text-guided segmentation.
Edits can be combined in a single call.
It accepts an image file for the image. If you want to send a URL, please use the GET endpoint. For more details on the difference between the GET and POST endpoints, please have a look at our documentation: https://docs.photoroom.com/image-editing-api/which-endpoints-are-available.
If you only have a URL for your image (not a local file), use the GET endpoint instead — it is simpler to integrate. Use this POST endpoint when you need to upload image files directly as multipart/form-data.
For this POST endpoint, all parameters must be passed via the request body using multipart/form-data encoding. Parameters must not be passed using the query string.
Full documentation: https://docs.photoroom.com/image-editing-api-plus-plan/quickstart-guide
Feature documentation:
- HD Background Removal
- Positioning (padding, margin, scaling)
- Output Size
- Static Background
- Background Blur
- Subject Outline
- AI Shadows
- AI Backgrounds
- AI Relight
- AI Text Removal
- AI Expand
- AI Uncrop
- AI Beautifier
- Flat Lay
- Ghost Mannequin
- Virtual Model
- AI Upscale
- Describe Any Change
- Create Any Image
- Text-Guided Segmentation
- Sandbox Mode (free testing)
Request
- Base URLhttps://image-api.photoroom.com
- URLhttps://image-api.photoroom.com/v2/edit
- AuthAPI key in header x-api-key
Request body multipart/form-data
Type of blur to apply to the background.
- gaussian: Applies a gaussian blur to the background.
- bokeh: Applies a bokeh blur to the background.
Radius of the blur effect. Higher values mean the result will be blurrier.
Minimum: 0, Maximum: 0.05
Color of the background. If omitted, background will be transparent unless background.imageUrl or background.imageFile is provided. Can be a hex color without the hash sign (example: FF0000, FF0000EE) or color name (examples: red, blue)
When removeBackground is set to false, the color will be used to fill padding areas created by outputSize and any transparent areas in the original image.
Bytes of the image to use as a background image guidance. Only available in the POST request
Can't be provided if removeBackground is set to false
The maximum size of the image is 30MB.
How closely the generated background will be matching the guiding image, between 0 and 1.
A value of 1 means it will match the guiding image as much as possible, a value of 0 means the guiding image will be ignored.
(Only working when using the new model)
Bytes of the image to use as a background. Only available in the POST request
Can't be provided if removeBackground is set to false
The maximum size of the image is 30MB.
If background.imageFile is provided, neither background.imageUrl nor background.prompt can be provided, and vice versa.
(LEGACY) This parameter will only have an effect when using the previous AI Backgrounds model, which is used when setting the header: pr-ai-background-model-version: 2
A negative prompt to use for guiding the background generation process; If provided, the generation algorithm will try to avoid properties listed in the negativePrompt.
Prompt to use for guiding the background generation process.
Tips for writing high-quality prompts are available in our documentation.
If background.prompt is provided, neither background.imageUrl nor background.imageFile can be provided, and vice versa.
Whether the background should fit or fill (default) the output image If set to fit, the empty pixels will be transparent
Can only be provided if background.imageUrl or background.imageFile is provided
Seed used to generate the background. Can be used to get similar looking results for the same prompt.
If enabled, the input image will be beautified (imageFile or imageUrl).
This is intended to enhance product images by automatically improving the aesthetics of the image, such as the lighting, background, and overall appearance.
If set to ai.auto, the input image will be beautified to match the aesthetic of a packshot product image.
If set to ai.food, the input image will be beautified in a way that's specific to food images, such as placing the subject on a plate.
If set to ai.car, the input image will be beautified in a way that's specific to car images, such as removing reflections.
Important:
- the beautifier will not preserve the original background: we recommend using this option along with removeBackground set to true
- the beautifier is meant for images of products, food, or cars; we do not recommend using it with subjects such as humans, pets, etc.
Controls what happens when the image doesn't match the subject expected by beautify.mode. The subject check is only available for beautify.mode ai.food.
If set to error, the request is rejected with HTTP 400: for ai.food, when the provided image is not detected as food (before any processing happens) — use this to fail fast instead of beautifying a non-food image; for any other mode, because the check is not supported there.
If set to ignore (the default), no subject check is performed and the image is beautified as-is.
Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject.
Controls the colour space of the output image.
- sRGB (default): the output is encoded in sRGB (current behaviour).
- original: the input's embedded ICC profile is preserved in the output. Only valid when the request is a background removal with PNG output, optionally positioned relative to the original image box: referenceBox: "originalImage" combined with padding (and its side-specific variants) and/or an explicit outputSize ("widthxheight"). Note that a non-zero padding or a size-changing outputSize resamples the pixels (never a colour conversion — the ICC profile and gamut are untouched). Combining original with any other operation (background, shadow, other geometry changes, non-PNG export, export.dpi, keepExistingAlphaChannel: "auto", EXIF-subset preserveMetadata modes, ...) returns a 400 error naming the conflicting parameter.
(DEPRECATED) Use editWithAI.mode instead.
Describe any change mode to use on the main image used by the API.
Currently, only ai.auto is supported.
(DEPRECATED) Use editWithAI.prompt instead.
The natural language prompt describing the change to apply to the image.
(DEPRECATED) Use editWithAI.seed instead.
Seed used for the generation. Can be used to get similar looking results for the same prompt.
Bytes of an additional reference image. Only available in the POST request.
Edit with AI mode to use on the main image used by the API.
Currently, only ai.auto is supported.
The natural language prompt describing the change to apply to the image.
Seed used for the generation. Can be used to get similar looking results for the same prompt.
Expand mode to use on the main image used by the API.
If set to ai.auto, all transparent pixels will automatically be filled based on the content of the current background (either the original background, if removeBackground has been set to false, or a static background, if background.imageUrl has been provided)
Expand will rely on output size, subject position, and fitting mode.
Seed used to generate the background. Can be used to get similar looking results for the same prompt.
The pixel density of the result image.
Pixel density can be set to any value between 72 and 1200 dpi.
The format of the result image.
Default value is "png".
Jpeg exports with a quality of 80, WebP and AVIF export with a quality of 90.
Must be set to ai.auto to enable flat lay generation.
Optional text prompt to guide the generation style.
The output size of the generated image.
Must be set to ai.auto to enable ghost mannequin generation.
Optional text prompt to guide the generation style.
The output size of the generated image.
[Advanced] Defines the horizontal alignment of the cutout subject within its bounding box.
Specifying a custom horizontal alignment will implicitly set ignorePaddingAndSnapOnCroppedSides to false for the horizontal direction.
If set to true (default), cropped sides of the subject will snap to the edges For instance, for a portrait image cropped below the elbows, the subject will be aligned at the bottom even if a bottom padding is provided (but it will still respect bottom margin)
Can't be provided if removeBackground is set to false
(See positioning section of the documentation for more information)
Bytes of the main image used by the API. The POST endpoint accepts imageFile only.
The maximum size of the image is 30MB.
If you want to send the URL of an image, please instead use the GET endpoint with the argument imageUrl.
The prompt to use for generating the image.
Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt.
Supported sizes for AI image generation
Must be set to ai.auto to enable ironing.
If set to auto and if the image has transparency, the existing transparency will be used to cutout the subject.
Lighting mode to use on the main image used by the API.
If set to ai.auto, the lighting will be automatically adjusted
If set to ai.preserve-hue-and-saturation, the lighting will be adjusted while keeping color hues and saturations as close as possible to the original image
If set to ai.optimize-portrait, the lighting will be adjusted using a model optimized for portrait subjects
Maximum output height. Can only be provided if outputSize is originalImage or croppedSubject. Useful for: redimensioning while keeping the aspect ratio
Maximum output width. Can only be provided if outputSize is originalImage or croppedSubject. Useful for: resizing an image while keeping the aspect ratio
Blur radius for the outline, creating a glow or soft edge effect. Higher values mean the outline will be more blurred, 0 means no blur.
Minimum: 0, Maximum: 0.025
Apply a colored outline around the subject to highlight it. Can be a hex color without the hash sign (example: FF0000, FF0000EE) or color name (examples: red, blue)
Width of the outline relative to the image size. Suggested values:
- 0.01-0.02: Subtle/thin outline
- 0.03-0.05: Standard/medium outline (default: 0.03)
- 0.06-0.1: Bold/thick outline The value represents a ratio where 0.1 (10%) is the maximum thickness.
Minimum: 0, Maximum: 0.1
Output size of the image. In the form of either:
- auto to keep the template dimensions when templateId is defined, or behave like originalImage when templateId isn't defined (default)
- widthxheight for a custom size (example: 200x400)
- originalImage to keep the original image dimensions
- croppedSubject to use the size of the foreground dimensions after cropping around it
Controls which metadata from the original image will be preserved in the output image.
- never: No metadata preservation (default)
- xmp: Preserve XMP metadata including camera settings, copyright information, and other embedded metadata
- exifSubset: Preserve EXIF Copyright (IFD0) and UserComment (ExifIFD) fields only. Deprecated — use exifSubsetWithXmpCompatibility instead. Will be removed in a future release.
- exifSubsetWithXmpCompatibility: Same as exifSubset but also writes Copyright and UserComment as XMP fields (dc:rights / exif:UserComment) for applications that read XMP instead of EXIF (e.g. Adobe products, macOS Preview).
[Advanced] subjectBox by default. When set to originalImage, the padding / margin will be around the original image and not the cropped subject.
It can lead to the subject disappearing when scaling is set to 'fill', for instance if the subject is on the left of a landscape image and outputSize is a square.
Most use cases don't require this option. It is useful if you'd like to maintain subject positioning in the original image.
Can't be provided if removeBackground is set to false
(See positioning section of the documentation for more information)
If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm
Whether the subject should fit (default) or fill the output image If set to fit, the empty pixels will be transparent
Can only be provided if imageUrl or imageFile is provided
Controls whether or not the salient object should be kept or ignored by the segmentation model.
A textual description of what the segmentation should remove.
Warning: Text-Guided Segmentation is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. A textual description of what the segmentation should keep.
Override for the intensity of the shadow.
0 means a very faint shadow, 1 means a very dark shadow.
This option is only supported by the 2026-04-15 AI Shadows model. It requires setting shadow.mode to ai.auto-with-overrides.
Shadow generation mode to use on the main image used by the API. If set to ai.soft, a soft shadow will be generated. Only compatible with legacy AI Shadows models If set to ai.hard, a hard shadow will be generated. Only compatible with legacy AI Shadows models If set to ai.floating, a floating shadow will be generated. Not compatible with the 2026-04-15 AI Shadows model If set to ai.preset-soft, a soft shadow will be generated. Only compatible with the 2026-04-15 AI Shadows model If set to ai.preset-hard, a hard shadow will be generated. Only compatible with the 2026-04-15 AI Shadows model If set to ai.auto-with-overrides, a shadow with most natural appearance for the input image will be generated. Override parameters can be provided to gain full control over the appearance of that shadow. Only compatible with the 2026-04-15 AI Shadows model
Override for the softness of the shadow.
0 means a very hard shadow, 1 means a very soft shadow.
This option is only supported by the 2026-04-15 AI Shadows model. It requires setting shadow.mode to ai.auto-with-overrides.
The ID of the template to render
Text removal mode to use on the main image used by the API.
If set to ai.artificial, artificial text will be automatically removed. Artificial text includes all text added on an image through post-precessing, such as company name, watermarks, discount, etc.
If set to ai.natural, natural text will be automatically removed. Natural text includes text that naturally occurs in an image such as writing on buildings or clothings, road signs, etc.
If set to ai.all, all text (natural and artificial) will be automatically removed.
Uncrop mode to use on the main image used by the API.
Currently, only ai.auto is supported. With ai.auto, the subject will be automatically detected and uncropped.
Seed used to generate the background. Can be used to get similar looking results for the same prompt.
Optional input downscaling strategy applied before AI Upscale when the selected model rejects the current input size.
never: keep the current behavior and return an error when the image is too large. always: downscale oversized images to the largest input size accepted by the selected model before upscaling. skipUpscaleIfNotNeeded: only downscale oversized images when the 4x upscaled result can still be at least as large as the original input.
Warning: AI Upscale is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period.
If enabled, the input image will be upscaled (imageFile or imageUrl)
Input limits depend on the model selected for AI Upscale. With the default model:
- ai.fast: maximum 1,000,000 input pixels
- ai.slow: maximum 262,144 input pixels
The upscaling process will enlarge the input image up to 4 times its original size. This will significantly increase the resolution and affect both the input processing and the final output dimensions.
ai.fast: This algorithm is optimized for speed and may not produce the highest quality results. ai.slow: This algorithm is optimized for quality and may take more time to process.
[Advanced] Defines the vertical alignment of the cutout subject within its bounding box.
Specifying a custom vertical alignment will implicitly set ignorePaddingAndSnapOnCroppedSides to false for the vertical direction.
Must be set to ai.auto to enable virtual model generation.
The pose of the model in the generated image.
Optional text prompt to guide the generation style.
The output quality of the generated image. Higher quality produces larger images. standard outputs ~1K, advanced ~2K, and premium ~4K resolution.
The output size of the generated image.
Response
OK
Changes
- info
endpoint added
- info