Image Editing v2 (Plus plan)
GET/v2/editThis 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.
请求参数
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, FFF, FF0000EE) or color name (examples: red, blue)
Can't be provided if removeBackground is set to false
URL of the image to use as a background.
Can't be provided if removeBackground is set to false
If background.imageUrl is provided, neither background.imageFile nor background.prompt can be provided, and vice versa.
[Advanced] 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.
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.
The format of the result image.
Supported values are "png", "jpeg" and "jpg".
Default value is "png".
[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)
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.
Lighting mode to use on the main image used by the API.
If set to ai.auto, the lighting will be automatically adjusted
[Advanced] Margin around the subject. Expressed in a ratio of the output image size.
Unlike padding, margin is never ignored even on cropped sides of the subject.
(See positioning section of the documentation for more information)
[Advanced] Bottom Margin, overrides margin argument on the Bottom side if provided
[Advanced] Left Margin, overrides margin argument on the left side
[Advanced] Right Margin, overrides margin argument on the right side if provided
[Advanced] Top Margin, overrides margin argument on the Top side if provided
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:
widthxheightfor a custom size (example:200x400)originalImageto keep the original image dimensionscroppedSubjectto use the size of the foreground dimensions after cropping around it
Padding around the subject. Unlike margin, it will be ignored on cropped sides of the subject if the 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)
Bottom Padding, overrides padding argument on the Bottom side if provided
Left Padding, overrides padding argument on the left side
Right Padding, overrides padding argument on the right side if provided
Top Padding, overrides padding argument on the Top side if provided
[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
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
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.
[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.