--- title: "Image Editing v2 (Plus plan)" method: POST path: "/v2/edit" --- # Image Editing v2 (Plus plan) `POST /v2/edit` ## Request - Base URL: `https://image-api.photoroom.com` - URL: `https://image-api.photoroom.com/v2/edit` - Auth: API key in header `x-api-key` This 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](https://docs.photoroom.com/image-editing-api-plus-plan/hd-background-removal) - [Positioning (padding, margin, scaling)](https://docs.photoroom.com/image-editing-api-plus-plan/positioning) - [Output Size](https://docs.photoroom.com/image-editing-api-plus-plan/output-size) - [Static Background](https://docs.photoroom.com/image-editing-api-plus-plan/static-background) - [Background Blur](https://docs.photoroom.com/image-editing-api-plus-plan/background-blur) - [Subject Outline](https://docs.photoroom.com/image-editing-api-plus-plan/subject-outline) - [AI Shadows](https://docs.photoroom.com/image-editing-api-plus-plan/ai-shadows) - [AI Backgrounds](https://docs.photoroom.com/image-editing-api-plus-plan/ai-backgrounds) - [AI Relight](https://docs.photoroom.com/image-editing-api-plus-plan/ai-relight) - [AI Text Removal](https://docs.photoroom.com/image-editing-api-plus-plan/ai-text-removal) - [AI Expand](https://docs.photoroom.com/image-editing-api-plus-plan/ai-expand) - [AI Uncrop](https://docs.photoroom.com/image-editing-api-plus-plan/ai-uncrop) - [AI Beautifier](https://docs.photoroom.com/image-editing-api-plus-plan/ai-beautifier) - [Flat Lay](https://docs.photoroom.com/image-editing-api-plus-plan/flat-lay) - [Ghost Mannequin](https://docs.photoroom.com/image-editing-api-plus-plan/ghost-mannequin) - [Virtual Model](https://docs.photoroom.com/image-editing-api-plus-plan/virtual-model) - [AI Upscale](https://docs.photoroom.com/image-editing-api-plus-plan/alpha-ai-upscale) - [Describe Any Change](https://docs.photoroom.com/image-editing-api-plus-plan/edit-with-ai) - [Create Any Image](https://docs.photoroom.com/image-editing-api-plus-plan/alpha-create-any-image) - [Text-Guided Segmentation](https://docs.photoroom.com/image-editing-api-plus-plan/alpha-text-guided-segmentation) - [Sandbox Mode (free testing)](https://docs.photoroom.com/image-editing-api-plus-plan/sandbox-mode) ## Request body `multipart/form-data` - object - `background.blur.mode` string: Type of blur to apply to the background. - `gaussian`: Applies a gaussian blur to the background. - `bokeh`: Applies a bokeh blur to the background. - `background.blur.radius` number: Radius of the blur effect. Higher values mean the result will be blurrier. Minimum: 0, Maximum: 0.05 - `background.color` string: 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. - `background.expandPrompt` unknown - `background.guidance.imageFile` string, binary: 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. - `background.guidance.scale` number: 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](https://docs.photoroom.com/image-editing-api-plus-plan/ai-backgrounds#important-model-selection)) - `background.imageFile` string, binary: 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. - `background.negativePrompt` string: (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. - `background.prompt` string: Prompt to use for guiding the background generation process. Tips for writing high-quality prompts are available [in our documentation](https://docs.photoroom.com/image-editing-api-plus-plan/ai-backgrounds#how-to-write-a-high-quality-prompt). If `background.prompt` is provided, neither `background.imageUrl` nor `background.imageFile` can be provided, and vice versa. - `background.scaling` string: 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 - `background.seed` number: Seed used to generate the background. Can be used to get similar looking results for the same prompt. - `beautify.mode` string: 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. - `beautify.onSubjectMismatch` string: 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. - `beautify.seed` number: Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject. - `colorSpace` string: 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. - `describeAnyChange.mode` string: (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. - `describeAnyChange.prompt` string: (DEPRECATED) Use `editWithAI.prompt` instead. The natural language prompt describing the change to apply to the image. - `describeAnyChange.seed` number: (DEPRECATED) Use `editWithAI.seed` instead. Seed used for the generation. Can be used to get similar looking results for the same prompt. - `editWithAI.additionalImages.{key}.imageFile` string, binary: Bytes of an additional reference image. Only available in the POST request. - `editWithAI.mode` string: Edit with AI mode to use on the main image used by the API. Currently, only `ai.auto` is supported. - `editWithAI.prompt` string: The natural language prompt describing the change to apply to the image. - `editWithAI.seed` number: Seed used for the generation. Can be used to get similar looking results for the same prompt. - `expand.mode` string: 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. - `expand.seed` number: Seed used to generate the background. Can be used to get similar looking results for the same prompt. - `export.dpi` number: The pixel density of the result image. Pixel density can be set to any value between 72 and 1200 dpi. - `export.format` string: 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. - `flatLay.mode` string: Must be set to `ai.auto` to enable flat lay generation. - `flatLay.prompt` string: Optional text prompt to guide the generation style. - `flatLay.size` string: The output size of the generated image. - `ghostMannequin.mode` string: Must be set to `ai.auto` to enable ghost mannequin generation. - `ghostMannequin.prompt` string: Optional text prompt to guide the generation style. - `ghostMannequin.size` string: The output size of the generated image. - `horizontalAlignment` string: [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. - `ignorePaddingAndSnapOnCroppedSides` boolean: 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) - `imageFile` string, binary: 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`. - `imageFromPrompt.prompt` string: The prompt to use for generating the image. - `imageFromPrompt.seed` number: Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt. - `imageFromPrompt.size` string: Supported sizes for AI image generation - `ironing.mode` string: Must be set to `ai.auto` to enable ironing. - `keepExistingAlphaChannel` string: If set to `auto` and if the image has transparency, the existing transparency will be used to cutout the subject. - `layers` object - `lighting.mode` string: 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 - `margin` union: General margin around the subject. Can be expressed as a number between 0 and 0.49, a percentage string between 0% and 49% (e.g., "30%"), or a pixel value string (e.g., "100px"). Unlike `padding`, margin is never ignored even on cropped sides of the subject. Expressed in a ratio of the output image size. See positioning section of the documentation for more information. Tips to assist with positioning are available [in our documentation](https://docs.photoroom.com/image-editing-api-plus-plan/positioning). - number - string - `marginBottom` union: Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as `margin`. - number - string - `marginLeft` union: Left Margin, overrides general margin on the left side. Accepts the same formats as `margin`. - number - string - `marginRight` union: Right Margin, overrides general margin on the right side. Accepts the same formats as `margin`. - number - string - `marginTop` union: Top Margin, overrides general margin on the top side. Accepts the same formats as `margin`. - number - string - `maxHeight` number: Maximum output height. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: redimensioning while keeping the aspect ratio - `maxWidth` number: Maximum output width. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: resizing an image while keeping the aspect ratio - `outline.blurRadius` number: 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 - `outline.color` string: 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`) - `outline.width` number: 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 - `outputSize` string: 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 - `padding` union: General padding around the subject. Can be expressed as a number between 0 and 0.49, a percentage string between 0% and 49% (e.g., "30%"), or a pixel value string (e.g., "100px"). Unlike `margin`, padding will be ignored on cropped sides of the subject if that option is enabled. Expressed in a ratio of the size of the document, minus margins (similar to CSS). See positioning section of the documentation for more information. Tips to assist with positioning are available [in our documentation](https://docs.photoroom.com/image-editing-api-plus-plan/positioning). - number - string - `paddingBottom` union: Bottom padding, overrides general padding on the bottom side. Accepts the same formats as `padding`. - number - string - `paddingLeft` union: Left padding, overrides general padding on the left side. Accepts the same formats as `padding`. - number - string - `paddingRight` union: Right padding, overrides general padding on the right side. Accepts the same formats as `padding`. - number - string - `paddingTop` union: Top padding, overrides general padding on the top side. Accepts the same formats as `padding`. - number - string - `preserveMetadata` string: 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). - `referenceBox` string: [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) - `removeBackground` boolean: If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm - `scaling` string: 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 - `segmentation.mode` string: Controls whether or not the salient object should be kept or ignored by the segmentation model. - `segmentation.negativePrompt` string: A textual description of what the segmentation should remove. - `segmentation.prompt` string: 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. - `shadow.directionOverride` unknown - `shadow.intensityOverride` number: 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.mode` string: 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 - `shadow.softnessOverride` number: 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`. - `shadow.spreadOverride` unknown - `shadow.subjectPoseOverride` unknown - `templateId` string, uuid: The ID of the template to render - `textRemoval.mode` string: 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` string: 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. - `uncrop.seed` number: Seed used to generate the background. Can be used to get similar looking results for the same prompt. - `upscale.downscaleIfNeeded` string: 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. - `upscale.mode` string: 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. - `verticalAlignment` string: [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. - `virtualModel.additionalProductImages` unknown[]: Additional product images showing different angles or details of the same item. These help the model better understand the product and generate more accurate results. - unknown - `virtualModel.mode` string: Must be set to `ai.auto` to enable virtual model generation. - `virtualModel.model` unknown - `virtualModel.pose` string: The pose of the model in the generated image. - `virtualModel.prompt` string: Optional text prompt to guide the generation style. - `virtualModel.quality` string: The output quality of the generated image. Higher quality produces larger images. `standard` outputs ~1K, `advanced` ~2K, and `premium` ~4K resolution. - `virtualModel.scene` unknown - `virtualModel.size` string: The output size of the generated image. ## Response `200` OK ## Other responses - `400`: Bad Request - `402`: Payment Required - `500`: Internal Server Error ## Changes - **2026-11-03** `a9597c56073d`: 1 info - endpoint added [Operation history](https://skmtc.dev/photoroom/apis/photoroom-api/changes/v2/edit/post.md) --- [API](https://skmtc.dev/photoroom/apis/photoroom-api.md) - [All operations](https://skmtc.dev/photoroom/apis/photoroom-api/llms.txt) - [OpenAPI document](https://skmtc.dev/photoroom/apis/photoroom-api/revisions/a9597c56073d?raw)