Photoroom Edit API
The Edit API from Photoroom — 1 operation(s) for edit.
OpenAPI Specification
openapi: 3.1.0
info:
title: Photoroom Account Edit API
version: 1.0.0
description: 'The Photoroom API takes an image as input, applies edits (background removal, AI backgrounds, shadows, relighting, text removal, flat lay, ghost mannequin, virtual model, and more), and returns the edited image.
For tested parameter combinations for common use cases, see our tutorials before building your integration:
- Second-hand marketplace listings: https://docs.photoroom.com/tutorials/how-to-improve-images-for-second-hand-item-marketplaces
- E-commerce with brand consistency: https://docs.photoroom.com/tutorials/how-to-create-e-commerce-images-with-consistent-brand-guidelines
- Food delivery apps: https://docs.photoroom.com/tutorials/how-to-create-food-delivery-images-with-consistent-brand-guidelines
- Google Shopping compliance: https://docs.photoroom.com/tutorials/how-to-create-compliant-product-images-for-google-shopping
- Sticker images: https://docs.photoroom.com/tutorials/how-to-create-sticker-images
To use the API, you need an API key. Create one at https://app.photoroom.com/api-dashboard. The key must be passed in the x-api-key header on every request.
Full documentation: https://docs.photoroom.com'
contact:
name: Photoroom API Team
email: api-help@photorom.com
url: https://photoroom.com/api
termsOfService: https://www.photoroom.com/legal/terms-and-conditions
security:
- x-api-key: []
tags:
- name: Edit
paths:
/v2/edit:
get:
operationId: edit-image-get
summary: Image Editing v2 (Plus plan)
description: "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.*), Virtual Model (virtualModel.*), AI expand (expand.mode), AI uncrop (uncrop.mode), AI upscale (upscale.mode), and positioning/resizing (padding, margin, outputSize).\n\nParameters 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, 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.\n\nEdits can be combined in a single call.\n\nIt accepts a URL input for the image. If you want to directly upload an image file, please use the POST 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.\n\nFor the simplest integration (recommended for no-code tools like Lovable), use this GET endpoint with imageUrl — no file upload handling required. \n\nExample of a request: GET https://image-api.photoroom.com/v2/edit?imageUrl=https://example.com/photo.jpg&removeBackground=true&background.color=FFFFFF&outputSize=1000x1000&padding=0.1 with header x-api-key: YOUR_API_KEY\n\nThe response is the edited image as binary data (image/png by default). To change format, set export.format to jpeg or webp.\n\nFull documentation: https://docs.photoroom.com/image-editing-api-plus-plan/quickstart-guide\n\nFeature documentation:\n- [HD Background Removal](https://docs.photoroom.com/image-editing-api-plus-plan/hd-background-removal)\n- [Positioning (padding, margin, scaling)](https://docs.photoroom.com/image-editing-api-plus-plan/positioning)\n- [Output Size](https://docs.photoroom.com/image-editing-api-plus-plan/output-size)\n- [Static Background](https://docs.photoroom.com/image-editing-api-plus-plan/static-background)\n- [Background Blur](https://docs.photoroom.com/image-editing-api-plus-plan/background-blur)\n- [Subject Outline](https://docs.photoroom.com/image-editing-api-plus-plan/subject-outline)\n- [AI Shadows](https://docs.photoroom.com/image-editing-api-plus-plan/ai-shadows)\n- [AI Backgrounds](https://docs.photoroom.com/image-editing-api-plus-plan/ai-backgrounds)\n- [AI Relight](https://docs.photoroom.com/image-editing-api-plus-plan/ai-relight)\n- [AI Text Removal](https://docs.photoroom.com/image-editing-api-plus-plan/ai-text-removal)\n- [AI Expand](https://docs.photoroom.com/image-editing-api-plus-plan/ai-expand)\n- [AI Uncrop](https://docs.photoroom.com/image-editing-api-plus-plan/ai-uncrop)\n- [AI Beautifier](https://docs.photoroom.com/image-editing-api-plus-plan/ai-beautifier)\n- [Flat Lay](https://docs.photoroom.com/image-editing-api-plus-plan/flat-lay)\n- [Ghost Mannequin](https://docs.photoroom.com/image-editing-api-plus-plan/ghost-mannequin)\n- [Virtual Model](https://docs.photoroom.com/image-editing-api-plus-plan/virtual-model)\n- [AI Upscale](https://docs.photoroom.com/image-editing-api-plus-plan/alpha-ai-upscale)\n- [Describe Any Change](https://docs.photoroom.com/image-editing-api-plus-plan/edit-with-ai)\n- [Create Any Image](https://docs.photoroom.com/image-editing-api-plus-plan/alpha-create-any-image)\n- [Text-Guided Segmentation](https://docs.photoroom.com/image-editing-api-plus-plan/alpha-text-guided-segmentation)\n- [Sandbox Mode (free testing)](https://docs.photoroom.com/image-editing-api-plus-plan/sandbox-mode)"
servers:
- url: https://image-api.photoroom.com
description: Production server (Plus plan)
parameters:
- name: background.blur.mode
in: query
description: 'Type of blur to apply to the background.
- `gaussian`: Applies a gaussian blur to the background.
- `bokeh`: Applies a bokeh blur to the background.'
schema:
enum:
- gaussian
- bokeh
examples:
- gaussian
- bokeh
type: string
- name: background.blur.radius
in: query
description: 'Radius of the blur effect. Higher values mean the result will be blurrier.
Minimum: 0, Maximum: 0.05'
schema:
default: 0.01
examples:
- 0.01
- 0.03
- 0.05
exclusiveMinimum: 0
maximum: 0.05
type: number
- name: background.color
in: query
description: '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.'
schema:
default: transparent
examples:
- '#FF0000'
- red
type: string
- name: background.expandPrompt
in: query
description: 'If `ai.auto`, a pre-processing step is applied to expand the prompt into a longer form.
`auto` and `never` are legacy values that will be removed in the next major version.'
schema:
anyOf:
- const: auto
type: string
- const: never
type: string
- additionalProperties: false
properties:
mode:
description: 'If `ai.auto`, a pre-processing step is applied to expand the prompt into a longer form.
Example: original prompt `"on a beach"`, expanded prompt: `"An object rests on the sandy shore of a tranquil beach. The object, partially covered in sand, casts a soft shadow under the warm sunlight. Seashells and driftwood are scattered around, with gentle waves lapping at the shore in the background, creating a serene coastal scene."`
(Note: `background.expandPrompt.mode` only affects `background.prompt`)'
enum:
- ai.auto
- ai.never
examples:
- ai.auto
- ai.never
type: string
required:
- mode
type: object
- name: background.guidance.imageFile
in: query
description: '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.'
schema:
format: binary
type: string
- name: background.guidance.imageUrl
in: query
description: 'URL of the image to use as a background image guidance.
Can''t be provided if `removeBackground` is set to `false`
The maximum size of the image is 30MB.'
schema:
examples:
- https://example.com/image.jpg
type: string
- name: background.guidance.scale
in: query
description: '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))'
schema:
default: 0.6
examples:
- '0.6'
maximum: 1
type: number
- name: background.imageUrl
in: query
description: 'URL of the image to use as a background.
Can''t be provided if `removeBackground` is set to `false`
The maximum size of the image is 30MB.
If `background.imageUrl` is provided, neither `background.imageFile` nor `background.prompt` can be provided, and vice versa.'
schema:
examples:
- https://example.com/image.jpg
type: string
- name: background.negativePrompt
in: query
description: '(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.'
schema:
examples:
- a red background
type: string
- name: background.prompt
in: query
description: '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.'
schema:
examples:
- a blue sky
- a blue sky with a white cloud
type: string
- name: background.scaling
in: query
description: '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'
schema:
default: fill
enum:
- fit
- fill
examples:
- fit
- fill
type: string
- name: background.seed
in: query
description: Seed used to generate the background. Can be used to get similar looking results for the same prompt.
schema:
examples:
- '123456'
type: number
- name: beautify.mode
in: query
description: '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.'
schema:
enum:
- ai.auto
- ai.food
- ai.car
examples:
- ai.auto
- ai.food
- ai.car
type: string
- name: beautify.seed
in: query
description: Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject.
schema:
examples:
- '123456'
type: number
- name: describeAnyChange.mode
in: query
description: '(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.'
schema:
const: ai.auto
examples:
- ai.auto
type: string
- name: describeAnyChange.prompt
in: query
description: '(DEPRECATED) Use `editWithAI.prompt` instead.
The natural language prompt describing the change to apply to the image.'
schema:
examples:
- Remove the coffee cup on the table
- Change the color of the shirt to blue
minLength: 1
type: string
- name: describeAnyChange.seed
in: query
description: '(DEPRECATED) Use `editWithAI.seed` instead.
Seed used for the generation. Can be used to get similar looking results for the same prompt.'
schema:
examples:
- '123456'
type: number
- name: editWithAI.additionalImages.{key}.imageUrl
in: query
description: URL of an additional reference image.
schema:
examples:
- https://example.com/reference-1.jpg
type: string
- name: editWithAI.mode
in: query
description: 'Edit with AI mode to use on the main image used by the API.
Currently, only `ai.auto` is supported.'
schema:
const: ai.auto
examples:
- ai.auto
type: string
- name: editWithAI.prompt
in: query
description: The natural language prompt describing the change to apply to the image.
schema:
examples:
- Remove the coffee cup on the table
- Change the color of the shirt to blue
minLength: 1
type: string
- name: editWithAI.seed
in: query
description: Seed used for the generation. Can be used to get similar looking results for the same prompt.
schema:
examples:
- '123456'
type: number
- name: expand.mode
in: query
description: '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.'
schema:
const: ai.auto
examples:
- ai.auto
type: string
- name: expand.seed
in: query
description: Seed used to generate the background. Can be used to get similar looking results for the same prompt.
schema:
examples:
- '123456'
type: number
- name: export.dpi
in: query
description: 'The pixel density of the result image.
Pixel density can be set to any value between 72 and 1200 dpi.'
schema:
examples:
- 72
- 96
- 300
maximum: 1200
minimum: 72
type: number
- name: export.format
in: query
description: 'The format of the result image.
Default value is "png".
Jpeg exports with a quality of 80 and WebP exports with a quality of 90.'
schema:
default: png
enum:
- png
- jpeg
- jpg
- webp
examples:
- png
- jpeg
- jpg
- webp
type: string
- name: flatLay.mode
in: query
description: Must be set to `ai.auto` to enable flat lay generation.
schema:
const: ai.auto
examples:
- ai.auto
type: string
- name: flatLay.prompt
in: query
description: Optional text prompt to guide the generation style.
schema:
examples:
- a clean studio flat lay
- minimal white background
type: string
- name: flatLay.size
in: query
description: The output size of the generated image.
schema:
default: SQUARE_HD
examples:
- SQUARE_HD
- PORTRAIT_HD_4_3
- LANDSCAPE_HD_16_9
enum:
- PORTRAIT_HD_16_9
- PORTRAIT_HD_4_3
- PORTRAIT_HD_3_2
- SQUARE_HD
- LANDSCAPE_HD_3_2
- LANDSCAPE_HD_4_3
- LANDSCAPE_HD_16_9
type: string
- name: ghostMannequin.mode
in: query
description: Must be set to `ai.auto` to enable ghost mannequin generation.
schema:
const: ai.auto
examples:
- ai.auto
type: string
- name: ghostMannequin.prompt
in: query
description: Optional text prompt to guide the generation style.
schema:
examples:
- ghost mannequin
- clean studio
type: string
- name: ghostMannequin.size
in: query
description: The output size of the generated image.
schema:
default: SQUARE_HD
examples:
- SQUARE_HD
- PORTRAIT_HD_4_3
- LANDSCAPE_HD_16_9
enum:
- PORTRAIT_HD_16_9
- PORTRAIT_HD_4_3
- PORTRAIT_HD_3_2
- SQUARE_HD
- LANDSCAPE_HD_3_2
- LANDSCAPE_HD_4_3
- LANDSCAPE_HD_16_9
type: string
- name: horizontalAlignment
in: query
description: '[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.'
schema:
enum:
- left
- center
- right
examples:
- left
- center
- right
type: string
- name: ignorePaddingAndSnapOnCroppedSides
in: query
description: '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)'
schema:
default: true
examples:
- 'true'
- 'false'
type: boolean
- name: imageFromPrompt.prompt
in: query
description: The prompt to use for generating the image.
schema:
examples:
- a red car in the desert
- a coffee mug on a countertop
minLength: 1
type: string
- name: imageFromPrompt.seed
in: query
description: Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt.
schema:
examples:
- '123456'
- '789012'
type: number
- name: imageFromPrompt.size
in: query
description: Supported sizes for AI image generation
schema:
examples:
- SQUARE_HD
- LANDSCAPE_16_9
- PORTRAIT_4_3
enum:
- LANDSCAPE_16_9
- LANDSCAPE_4_3
- PORTRAIT_16_9
- PORTRAIT_4_3
- SQUARE_HD
type: string
- name: imageUrl
in: query
description: 'URL of the main image used by the API. The GET endpoint accepts `imageUrl` only.
The maximum size of the image is 30MB.
If you want to directly upload an image file, please instead use the POST endpoint with the argument `imageFile`.'
schema:
examples:
- https://example.com/image.jpg
type: string
- name: keepExistingAlphaChannel
in: query
description: If set to `auto` and if the image has transparency, the existing transparency will be used to cutout the subject.
schema:
default: never
enum:
- auto
- never
examples:
- auto
- never
type: string
- name: layers
in: query
schema:
additionalProperties:
anyOf:
- additionalProperties: false
properties:
text:
additionalProperties: false
properties:
backgroundColor:
type: string
content:
type: string
font:
type: string
foregroundColor:
type: string
type: object
required:
- text
type: object
- additionalProperties: false
properties:
image:
additionalProperties: false
properties:
horizontalAlignment:
enum:
- left
- center
- right
type: string
imageFile:
description: '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`.'
examples:
- image.jpg
format: binary
type: string
imageFromPrompt:
additionalProperties: false
description: Instead of providing an image, you can provide a prompt to generate an image.
properties:
prompt:
description: The prompt to use for generating the image.
examples:
- a red car in the desert
- a coffee mug on a countertop
minLength: 1
type: string
seed:
description: Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt.
examples:
- '123456'
- '789012'
type: number
size:
description: Supported sizes for AI image generation
examples:
- SQUARE_HD
- LANDSCAPE_16_9
- PORTRAIT_4_3
enum:
- LANDSCAPE_16_9
- LANDSCAPE_4_3
- PORTRAIT_16_9
- PORTRAIT_4_3
- SQUARE_HD
type: string
required:
- prompt
type: object
imageUrl:
description: 'URL of the main image used by the API. The GET endpoint accepts `imageUrl` only.
The maximum size of the image is 30MB.
If you want to directly upload an image file, please instead use the POST endpoint with the argument `imageFile`.'
examples:
- https://example.com/image.jpg
type: string
margin:
type:
- number
- string
marginBottom:
type:
- number
- string
marginLeft:
type:
- number
- string
marginRight:
type:
- number
- string
marginTop:
type:
- number
- string
padding:
type:
- number
- string
paddingBottom:
type:
- number
- string
paddingLeft:
type:
- number
- string
paddingRight:
type:
- number
- string
paddingTop:
type:
- number
- string
removeBackground:
enum:
- auto
- never
type: string
segmentation:
additionalProperties: false
properties:
mode:
description: Controls whether or not the salient object should be kept or ignored by the segmentation model.
enum:
- keepSalientObject
- ignoreSalientObject
type: string
negativePrompt:
description: A textual description of what the segmentation should remove.
examples:
- a red object
type: string
prompt:
description: '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.'
examples:
- a red object
type: string
required:
- prompt
type: object
useForAIBackground:
enum:
- auto
- never
type: string
verticalAlignment:
enum:
- top
- center
- bottom
type: string
type: object
required:
- image
type: object
type: object
- name: lighting.mode
in: query
description: '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'
schema:
enum:
- ai.auto
- ai.preserve-hue-and-saturation
examples:
- ai.auto
- ai.preserve-hue-and-saturation
type: string
- name: margin
in: query
description: '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).'
schema:
default: 0
examples:
- '0.3'
- 30%
- 100px
type:
- number
- string
- name: marginBottom
in: query
description: Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as `margin`.
schema:
examples:
- '0.3'
- 30%
- 100px
type:
- number
- string
- name: marginLeft
in: query
description: Left Margin, overrides general margin on the left side. Accepts the same formats as `margin`.
schema:
examples:
- '0.3'
- 30%
- 100px
type:
- number
- string
- name: marginRight
in: query
description: Right Margin, overrides general margin on the right side. Accepts the same formats as `margin`.
schema:
examples:
- '0.3'
- 30%
- 100px
type:
- number
- string
- name: marginTop
in: query
description: Top Margin, overrides general margin on the top side. Accepts the same formats as `margin`.
schema:
examples:
- '0.3'
- 30%
- 100px
type:
- number
- string
- name: maxHeight
in: query
description: 'Maximum output height. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: redimensioning while keeping the aspect ratio'
schema:
examples:
- '200'
type: number
- name: maxWidth
in: query
description: 'Maximum output width. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: resizing an image while keeping the aspect ratio'
schema:
examples:
- '200'
type: number
- name: outline.blurRadius
in: query
description: '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'
schema:
default: 0
examples:
- 0.01
- 0.02
- 0.025
maximum: 0.025
minimum: 0
type: number
- name: outline.color
in: query
description: '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`)'
schema:
examples:
- FF0000
- red
type: string
- name: outline.width
in: query
description: '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-
# --- truncated at 32 KB (92 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/photoroom/refs/heads/main/openapi/photoroom-edit-api-openapi.yml