API Reference (OpenAPI)
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)
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.
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.
123456If 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
removeBackgroundset totrue - the beautifier is meant for images of products, food, or cars; 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.
123456(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.
ai.auto(DEPRECATED) Use editWithAI.prompt instead.
The natural language prompt describing the change to apply to the image.
Remove the coffee cup on the table(DEPRECATED) Use editWithAI.seed instead.
Seed used for the generation. Can be used to get similar looking results for the same prompt.
123456Edit with AI mode to use on the main image used by the API.
Currently, only ai.auto is supported.
ai.autoThe natural language prompt describing the change to apply to the image.
Remove the coffee cup on the tableSeed used for the generation. Can be used to get similar looking results for the same prompt.
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: Must be set to ai.auto to enable flat lay generation.
ai.autoOptional text prompt to guide the generation style.
a clean studio flat layThe output size of the generated image.
SQUARE_HDExample: SQUARE_HDPossible values: Must be set to ai.auto to enable ghost mannequin generation.
ai.autoOptional text prompt to guide the generation style.
ghost mannequinThe output size of the generated image.
SQUARE_HDExample: SQUARE_HDPossible 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.
123456Supported sizes for AI image generation
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
200Blur 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
0Example: 0.01Apply 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)
FF0000Width 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
0.03Example: 0.01Output 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 metadataexifSubset: Preserve EXIF Copyright (IFD0) and UserComment (ExifIFD) fields only. Deprecated — useexifSubsetWithXmpCompatibilityinstead. Will be removed in a future release.exifSubsetWithXmpCompatibility: Same asexifSubsetbut 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).
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: Must be set to ai.auto to enable virtual model generation.
ai.autoThe model (person) to use for the virtual try-on. Either a preset model name or a custom image.
{"preset":{"name":"avery"}}The pose of the model in the generated image.
randomExample: standingPossible values: Optional text prompt to guide the generation style.
street styleThe output quality of the generated image. Higher quality produces larger images. standard outputs ~1K, advanced ~2K, and premium ~4K resolution.
standardExample: standardPossible values: The scene (background/environment) to use. Either a preset scene name or a custom image.
{"preset":{"name":"random"}}The output size of the generated image.
PORTRAIT_HD_3_2Example: SQUARE_HDPossible values: OK
The resulting image after rendering
Bad Request
Payment Required
Internal Server Error
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)
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.
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.
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
removeBackgroundset totrue - the beautifier is meant for images of products, food, or cars; 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.
(DEPRECATED) Use editWithAI.mode instead.
Describe any change mode to use on the main image used by the API.
Currently, only ai.auto is supported.
(DEPRECATED) Use editWithAI.prompt instead.
The natural language prompt describing the change to apply to the image.
(DEPRECATED) Use editWithAI.seed instead.
Seed used for the generation. Can be used to get similar looking results for the same prompt.
Edit with AI mode to use on the main image used by the API.
Currently, only ai.auto is supported.
The natural language prompt describing the change to apply to the image.
Seed used for the generation. Can be used to get similar looking results for the same prompt.
Expand mode to use on the main image used by the API.
If set to ai.auto, all transparent pixels will automatically be filled based on the content of the current background (either the original background, if removeBackground has been set to false, or a static background, if background.imageUrl has been provided)
Expand will rely on output size, subject position, and fitting mode.
Seed used to generate the background. Can be used to get similar looking results for the same prompt.
The pixel density of the result image.
Pixel density can be set to any value between 72 and 1200 dpi.
The format of the result image.
Default value is "png".
Jpeg exports with a quality of 80 and WebP exports with a quality of 90.
Must be set to ai.auto to enable flat lay generation.
Optional text prompt to guide the generation style.
The output size of the generated image.
Must be set to ai.auto to enable ghost mannequin generation.
Optional text prompt to guide the generation style.
The output size of the generated image.
[Advanced] Defines the horizontal alignment of the cutout subject within its bounding box.
Specifying a custom horizontal alignment will implicitly set ignorePaddingAndSnapOnCroppedSides to false for the horizontal direction.
If set to true (default), cropped sides of the subject will snap to the edges For instance, for a portrait image cropped below the elbows, the subject will be aligned at the bottom even if a bottom padding is provided (but it will still respect bottom margin)
Can't be provided if removeBackground is set to false
(See positioning section of the documentation for more information)
Bytes of the main image used by the API. The POST endpoint accepts imageFile only.
The maximum size of the image is 30MB.
If you want to send the URL of an image, please instead use the GET endpoint with the argument imageUrl.
The prompt to use for generating the image.
Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt.
Supported sizes for AI image generation
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
Blur radius for the outline, creating a glow or soft edge effect. Higher values mean the outline will be more blurred, 0 means no blur.
Minimum: 0, Maximum: 0.025
Apply a colored outline around the subject to highlight it. Can be a hex color without the hash sign (example: FF0000, FF0000EE) or color name (examples: red, blue)
Width of the outline relative to the image size. Suggested values:
- 0.01-0.02: Subtle/thin outline
- 0.03-0.05: Standard/medium outline (default: 0.03)
- 0.06-0.1: Bold/thick outline The value represents a ratio where 0.1 (10%) is the maximum thickness.
Minimum: 0, Maximum: 0.1
Output size of the image. In the form of either:
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 metadataexifSubset: Preserve EXIF Copyright (IFD0) and UserComment (ExifIFD) fields only. Deprecated — useexifSubsetWithXmpCompatibilityinstead. Will be removed in a future release.exifSubsetWithXmpCompatibility: Same asexifSubsetbut also writes Copyright and UserComment as XMP fields (dc:rights / exif:UserComment) for applications that read XMP instead of EXIF (e.g. Adobe products, macOS Preview).
[Advanced] subjectBox by default. When set to originalImage, the padding / margin will be around the original image and not the cropped subject.
It can lead to the subject disappearing when scaling is set to 'fill', for instance if the subject is on the left of a landscape image and outputSize is a square.
Most use cases don't require this option. It is useful if you'd like to maintain subject positioning in the original image.
Can't be provided if removeBackground is set to false
(See positioning section of the documentation for more information)
If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm
Whether the subject should fit (default) or fill the output image If set to fit, the empty pixels will be transparent
Can only be provided if imageUrl or imageFile is provided
Controls whether or not the salient object should be kept or ignored by the segmentation model.
A textual description of what the segmentation should remove.
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.
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.
Must be set to ai.auto to enable virtual model generation.
The model (person) to use for the virtual try-on. Either a preset model name or a custom image.
The pose of the model in the generated image.
Optional text prompt to guide the generation style.
The output quality of the generated image. Higher quality produces larger images. standard outputs ~1K, advanced ~2K, and premium ~4K resolution.
The scene (background/environment) to use. Either a preset scene name or a custom image.
The output size of the generated image.
OK
The resulting image after rendering
Bad Request
Payment Required
Internal Server Error
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
Get you API Key here
OK
The name of the pricing plan
basicBad Request
Forbidden
Last updated
Was this helpful?