REST API for background removal, AI image editing, AI shadows, AI backgrounds, product reposition, virtual model, ghost mannequin, photo composition, and image to video. Authenticated by API key obtained from the Photoroom API Dashboard. OpenAPI published at https://image-api.photoroom.com/openapi.
openapi: 3.1.0
info:
title: Photoroom 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: [email protected]
url: https://photoroom.com/api
termsOfService: https://www.photoroom.com/legal/terms-and-conditions
security:
- x-api-key: []
components:
securitySchemes:
x-api-key:
type: apiKey
name: x-api-key
in: header
description: Get you API Key [here](https://app.photoroom.com/api-dashboard)
schemas:
image-response:
type: string
title: Resulting image
description: The resulting image after rendering
format: binary
payment-error:
type: object
properties:
error:
type: object
properties:
detail:
type: string
description: The details of the error
title: Details
example: API credits exhausted. Visit https://app.photoroom.com/api-dashboard
to purchase more API credits
required:
- detail
required:
- error
title: Payment Error
unknown-error:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: The message describing the error
title: Message
example: An unexpected error occurred. Please try again later or contact
support.
required:
- message
required:
- error
title: Unknown Error
edit-image-bad-request:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: The message describing the error
title: Message
example: removeBackground must be boolean
required:
- message
required:
- error
title: Invalid value
remove-background-post-params:
type: object
properties:
image_file:
type: string
description: The image file to render
title: Image File
format: binary
format:
type: string
default: png
title: Format
description: The format of the resulting image
enum:
- png
- jpg
- webp
channels:
type: string
default: rgba
title: Channels
description: The channels of the resulting image
enum:
- rgba
- alpha
bg_color:
type: string
title: Background Color
description: The background color of the resulting image. Can be a hex code
(`#FF00FF`) or a HTML color (`red`, `green`, etc.)
size:
type: string
default: full
title: Size
description: Will resize the output to the specified size. Can be `preview`
(0.25 Megapixels), `medium` (1.5 MP), `hd` (4 MP) or `full` (36 MP, can
be slower for large images). Useful for mobile apps that need smaller
images.
enum:
- preview
- medium
- hd
- full
crop:
type: string
default: 'false'
title: Crop
description: If `true`, the image returned is cropped to the cutout border.
Transparent pixels are removed from the border
enum:
- 'true'
- 'false'
despill:
type: string
default: 'false'
title: Green screen despilling
description: If `true`, automatically removes colored reflections that have
been left on the main subject by a green background.
enum:
- 'true'
- 'false'
required:
- image_file
title: Remove Background POST params
render-image-post-params:
type: object
properties:
templateId:
type: string
description: The ID of the template to render
title: Template ID
example: 592dd982-4a1b-4cd9-ab11-21481d5a0064
imageFile:
type: string
description: The image file to render
title: Image File
format: binary
imageUrl:
type: string
format: uri
title: Image URL
description: Deprecated, use `imageFile` instead.
example: https://s3.amazonaws.com/a.storyblok.com/f/191576/1024x1024/d25e1a99d7/sample-05.png
deprecated: true
required:
- templateId
title: Render image POST params
parameters: {}
paths:
/v1/segment:
post:
operationId: remove-background
summary: Remove Background (Basic plan)
description: Remove background from an image
servers:
- url: https://sdk.photoroom.com
description: Production server (Basic plan)
requestBody:
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/remove-background-post-params'
responses:
'200':
description: OK
headers:
x-uncertainty-score:
schema:
summary: The uncertainty score of the cutout
description: The uncertainty score is a number between 0 and 1. 0
means the model is very confident that the cutout is accurate, 1
means the model is unsure. For instance, shoes on a shoe box might
give a higher uncertainty score as the model is unsure what to segment
(shoes, box or both). Currently the model returns an uncertainty
score only for images of objects. If an image contains humans, it
will return the value -1.
content:
image/png:
schema:
type: string
title: Resulting image
description: The resulting image after rendering
format: binary
application/json:
schema:
type: object
properties:
base64img:
type: string
title: Base64 encoded image
format: base64
required:
- base64img
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: The details of the error
title: Details
example: Please provide an image.
status_code:
type: number
description: The status code of the error
title: Status Code
example: 400
type:
type: string
description: The type of the error
title: Type
example: missing_image
required:
- detail
- status_code
- type
title: Field Missing Error
'402':
description: Payment Required
content:
application/json:
schema:
type: object
properties:
detail:
type: string
description: The details of the error
title: Details
example: Please provide an image.
status_code:
type: number
description: The status code of the error
title: Status Code
example: 400
type:
type: string
description: The type of the error
title: Type
example: missing_image
required:
- detail
- status_code
- type
title: Field Missing Error
'403':
description: Forbidden
/v1/account:
get:
operationId: account-details-v1
summary: Account Details v1
description: Get current account details, including remaining credits balance
and monthly quota
servers:
- url: https://image-api.photoroom.com
description: Production server (Plus plan)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
credits:
type: object
properties:
available:
type: number
description: The number of credits available
title: Available
example: 100
subscription:
type: number
description: The number of credits available in the subscription
title: Subscription
example: 100
minimum: 0
required:
- available
- subscription
required:
- credits
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: The message describing the error
title: Message
example: 'apiKey: Required'
required:
- message
required:
- error
title: Field Missing Error
'403':
description: Forbidden
/v2/account:
get:
operationId: account-details-v2
summary: Account Details v2
description: Get current account details, including remaining image edits and
monthly quota
servers:
- url: https://image-api.photoroom.com
description: Production server (Plus plan)
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
images:
type: object
properties:
available:
type: number
description: The number of images available
title: Available
example: 100
subscription:
type: number
description: The total number of image available in the subscription
title: Subscription
example: 100
minimum: 0
required:
- available
- subscription
plan:
type: string
description: The name of the pricing plan
title: Plan
example: basic
required:
- images
- plan
'400':
description: Bad Request
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
message:
type: string
description: The message describing the error
title: Message
example: 'apiKey: Required'
required:
- message
required:
- error
title: Field Missing Error
'403':
description: Forbidden
/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 \u2014 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
# --- truncated at 32 KB (116 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/photoroom/refs/heads/main/openapi/photoroom-openapi.yml