API Reference (OpenAPI)
This endpoint processes an image, removing the background if specified, and applies various transformations such as scaling, padding, and margin adjustments. It 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. The output size, background color or image, and other parameters can be customized.
Get you API Key here
Type of blur to apply to the background.
gaussian: Applies a gaussian blur to the background.bokeh: Applies a bokeh blur to the background.
gaussianPossible values: Radius of the blur effect. Higher values mean the result will be blurrier.
Minimum: 0, Maximum: 0.05
0.01Example: 0.01Color 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)
Can't be provided if removeBackground is set to false
transparentExample: #FF0000If 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.
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.
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.
https://example.com/image.jpgHow 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)
0.6Example: 0.6URL 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.
https://example.com/image.jpg(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.
a red backgroundPrompt 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.
a blue skyWhether 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
fillExample: fitPossible values: Seed used to generate the background. Can be used to get similar looking results for the same prompt.
123456(ALPHA) Warning: might get deprecated with a 2 weeks warning
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.
Important:
- the beautifier will not preserve the original background: we recommend using this option along with
removeBackgroundset totrue - the beautifier is meant for images of products or food; we do not recommend using it with subjects such as humans, pets, etc.
ai.autoPossible values: Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject.
123456Expand 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.
ai.autoSeed used to generate the background. Can be used to get similar looking results for the same prompt.
123456The pixel density of the result image.
Pixel density can be set to any value between 72 and 1200 dpi.
72The format of the result image.
Default value is "png".
Jpeg exports with a quality of 80 and WebP exports with a quality of 90.
pngExample: pngPossible values: [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.
leftPossible values: 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)
trueExample: trueThe prompt to use for generating the image.
a red car in the desertSeed used to run the AI image generator. Can be used to get similar looking results for the same prompt.
123456The size/format of the generated image.
SQUARE_HDPossible values: 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.
https://example.com/image.jpgIf set to auto and if the image has transparency, the existing transparency will be used to cutout the subject.
neverExample: autoPossible values: 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
ai.autoPossible values: 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.
0Example: 0.3Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as margin.
0.3Left Margin, overrides general margin on the left side. Accepts the same formats as margin.
0.3Right Margin, overrides general margin on the right side. Accepts the same formats as margin.
0.3Top Margin, overrides general margin on the top side. Accepts the same formats as margin.
0.3Maximum output height. Can only be provided if outputSize is originalImage or croppedSubject. Useful for: redimensioning while keeping the aspect ratio
200Maximum output width. Can only be provided if outputSize is originalImage or croppedSubject. Useful for: resizing an image while keeping the aspect ratio
200Output size of the image. In the form of either:
autoto keep the template dimensions when templateId is defined, or behave likeoriginalImagewhen templateId isn't defined (default)widthxheightfor a custom size (example:200x400)originalImageto keep the original image dimensionscroppedSubjectto use the size of the foreground dimensions after cropping around it
autoExample: 200x400Pattern: ^(auto|\d+x\d+|originalImage|croppedSubject)$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.
0Example: 0.3Bottom padding, overrides general padding on the bottom side. Accepts the same formats as padding.
0.3Left padding, overrides general padding on the left side. Accepts the same formats as padding.
0.3Right padding, overrides general padding on the right side. Accepts the same formats as padding.
0.3Top padding, overrides general padding on the top side. Accepts the same formats as padding.
0.3Controls 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
neverExample: neverPossible values: [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)
subjectBoxExample: subjectBoxPossible values: If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm
trueExample: trueWhether 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
fitExample: fitPossible values: 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.
a red objectA textual description of what the segmentation should keep.
a red objectShadow generation mode to use on the main image used by the API. If set to ai.soft, a soft shadow will be generated If set to ai.hard, a hard shadow will be generated If set to ai.floating, a floating shadow will be generated
ai.softPossible values: 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.
ai.artificialPossible values: 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.
ai.autoSeed used to generate the background. Can be used to get similar looking results for the same prompt.
123456(ALPHA) Warning: might get deprecated with a 2 weeks warning
If enabled, the input image will be upscaled (imageFile or imageUrl)
The input image (imageFile or imageUrl) must not exceed 1000x1000 pixels in dimensions when using ai.fast mode. The input image (imageFile or imageUrl) must not exceed 512x512 pixels in dimensions when using ai.slow mode.
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.
ai.fastPossible values: [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.
topPossible values: OK
The resulting image after rendering
Bad Request
Payment Required
Internal Server Error
GET /v2/edit HTTP/1.1
Host: image-api.photoroom.com
x-api-key: YOUR_API_KEY
Accept: */*
binaryThis endpoint processes an image, removing the background if specified, and applies various transformations such as scaling, padding, and margin adjustments. It accepts binary data for the image. If you want to send the URL of an image, 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. The output size, background color or image, and other parameters can be customized.
Get you API Key here
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)
Can't be provided if removeBackground is set to false
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.
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.
(ALPHA) Warning: might get deprecated with a 2 weeks warning
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.
Important:
- the beautifier will not preserve the original background: we recommend using this option along with
removeBackgroundset totrue - the beautifier is meant for images of products or food; we do not recommend using it with subjects such as humans, pets, etc.
Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject.
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 and WebP exports with a quality of 90.
[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.
The size/format of the generated image.
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
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.
Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as margin.
Left Margin, overrides general margin on the left side. Accepts the same formats as margin.
Right Margin, overrides general margin on the right side. Accepts the same formats as margin.
Top Margin, overrides general margin on the top side. Accepts the same formats as margin.
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
Output size of the image. In the form of either:
autoto keep the template dimensions when templateId is defined, or behave likeoriginalImagewhen templateId isn't defined (default)widthxheightfor a custom size (example:200x400)originalImageto keep the original image dimensionscroppedSubjectto use the size of the foreground dimensions after cropping around it
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.
Bottom padding, overrides general padding on the bottom side. Accepts the same formats as padding.
Left padding, overrides general padding on the left side. Accepts the same formats as padding.
Right padding, overrides general padding on the right side. Accepts the same formats as padding.
Top padding, overrides general padding on the top side. Accepts the same formats as padding.
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
[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.
A textual description of what the segmentation should keep.
Shadow generation mode to use on the main image used by the API. If set to ai.soft, a soft shadow will be generated If set to ai.hard, a hard shadow will be generated If set to ai.floating, a floating shadow will be generated
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.
(ALPHA) Warning: might get deprecated with a 2 weeks warning
If enabled, the input image will be upscaled (imageFile or imageUrl)
The input image (imageFile or imageUrl) must not exceed 1000x1000 pixels in dimensions when using ai.fast mode. The input image (imageFile or imageUrl) must not exceed 512x512 pixels in dimensions when using ai.slow mode.
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.
OK
The resulting image after rendering
Bad Request
Payment Required
Internal Server Error
POST /v2/edit HTTP/1.1
Host: image-api.photoroom.com
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 1257
{
"background.blur.mode": "text",
"background.blur.radius": 1,
"background.color": "text",
"background.expandPrompt": null,
"background.guidance.imageFile": "binary",
"background.guidance.scale": 1,
"background.imageFile": "binary",
"background.negativePrompt": "text",
"background.prompt": "text",
"background.scaling": "text",
"background.seed": 1,
"beautify.mode": "text",
"beautify.seed": 1,
"expand.mode": "text",
"expand.seed": 1,
"export.dpi": 1,
"export.format": "text",
"horizontalAlignment": "text",
"ignorePaddingAndSnapOnCroppedSides": true,
"imageFile": "binary",
"imageFromPrompt.prompt": "text",
"imageFromPrompt.seed": 1,
"imageFromPrompt.size": "text",
"keepExistingAlphaChannel": "text",
"layers": {},
"lighting.mode": "text",
"margin": 1,
"marginBottom": 1,
"marginLeft": 1,
"marginRight": 1,
"marginTop": 1,
"maxHeight": 1,
"maxWidth": 1,
"outputSize": "text",
"padding": 1,
"paddingBottom": 1,
"paddingLeft": 1,
"paddingRight": 1,
"paddingTop": 1,
"preserveMetadata": "text",
"referenceBox": "text",
"removeBackground": true,
"scaling": "text",
"segmentation.mode": "text",
"segmentation.negativePrompt": "text",
"segmentation.prompt": "text",
"shadow.mode": "text",
"templateId": "123e4567-e89b-12d3-a456-426614174000",
"textRemoval.mode": "text",
"uncrop.mode": "text",
"uncrop.seed": 1,
"upscale.mode": "text",
"verticalAlignment": "text"
}binaryRemove background from an image
Get you API Key here
The image file to render
The format of the resulting image
pngPossible values: The channels of the resulting image
rgbaPossible values: The background color of the resulting image. Can be a hex code (#FF00FF) or a HTML color (red, green, etc.)
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.
fullPossible values: If true, the image returned is cropped to the cutout border. Transparent pixels are removed from the border
falsePossible values: If true, automatically removes colored reflections that have been left on the main subject by a green background.
falsePossible values: OK
The resulting image after rendering
Bad Request
Payment Required
Forbidden
POST /v1/segment HTTP/1.1
Host: image-api.photoroom.com
x-api-key: YOUR_API_KEY
Content-Type: multipart/form-data
Accept: */*
Content-Length: 121
{
"image_file": "binary",
"format": "png",
"channels": "rgba",
"bg_color": "text",
"size": "full",
"crop": "false",
"despill": "false"
}binaryGet current account details, including remaining image edits and monthly quota
Get you API Key here
OK
Bad Request
Forbidden
GET /v2/account HTTP/1.1
Host: image-api.photoroom.com
x-api-key: YOUR_API_KEY
Accept: */*
{
"images": {
"available": 100,
"subscription": 100
},
"plan": "basic"
}Last updated
Was this helpful?