Image Editing v2 (Plus plan)

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.

请求参数

Query 参数

background.color

string

可选

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

默认值:

transparent

background.imageUrl

string <uri>

可选

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.

background.negativePrompt

string

可选

[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.

background.prompt

string

可选

Prompt to use for guiding the background generation process.

background.scaling

enum<string>

可选

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

枚举值:

fillfit

默认值:

fill

background.seed

number

可选

Seed used to generate the background. Can be used to get similar looking results for the same prompt.

export.format

enum<string>

可选

The format of the result image.

Supported values are "png", "jpeg" and "jpg".

Default value is "png".

枚举值:

jpegjpgpng

默认值:

png

horizontalAlignment

enum<string>

可选

[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.

枚举值:

centerleftright

ignorePaddingAndSnapOnCroppedSides

boolean

可选

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)

默认值:

true

imageUrl

string <uri>

可选

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

enum<string>

可选

Lighting mode to use on the main image used by the API.
If set to ai.auto, the lighting will be automatically adjusted

枚举值:

ai.auto

margin

number

可选

[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)

>= 0<= 1

默认值:

marginBottom

number

可选

[Advanced] Bottom Margin, overrides margin argument on the Bottom side if provided

>= 0<= 1

marginLeft

number

可选

[Advanced] Left Margin, overrides margin argument on the left side

>= 0<= 1

marginRight

number

可选

[Advanced] Right Margin, overrides margin argument on the right side if provided

>= 0<= 1

marginTop

number

可选

[Advanced] Top Margin, overrides margin argument on the Top side if provided

>= 0<= 1

maxHeight

number

可选

Maximum output height. Can only be provided if outputSize is originalImage or croppedSubject.
Useful for: redimensioning while keeping the aspect ratio

maxWidth

number

可选

Maximum output width. Can only be provided if outputSize is originalImage or croppedSubject.
Useful for: resizing an image while keeping the aspect ratio

outputSize

string

可选

Output size of the image. In the form of either:

widthxheight for a custom size (example: 200x400)

originalImage to keep the original image dimensions

croppedSubject to use the size of the foreground dimensions after cropping around it

默认值:

originalImage

正则匹配:

^(\d+x\d+|originalImage|croppedSubject)$

padding

number

可选

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)

>= 0<= 1

默认值:

paddingBottom

number

可选

Bottom Padding, overrides padding argument on the Bottom side if provided

>= 0<= 1

paddingLeft

number

可选

Left Padding, overrides padding argument on the left side

>= 0<= 1

paddingRight

number

可选

Right Padding, overrides padding argument on the right side if provided

>= 0<= 1

paddingTop

number

可选

Top Padding, overrides padding argument on the Top side if provided

>= 0<= 1

referenceBox

enum<string>

可选

[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)

枚举值:

originalImagesubjectBox

默认值:

subjectBox

removeBackground

boolean

可选

If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm

默认值:

true

scaling

enum<string>

可选

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

枚举值:

fillfit

默认值:

fit

shadow.mode

enum<string>

可选

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

枚举值:

ai.floatingai.hardai.soft

textRemoval.mode

enum<string>

可选

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.allai.artificialai.natural

verticalAlignment

enum<string>

可选

[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.

枚举值:

bottomcentertop

Header 参数

x-api-key

string

必需

Image Editing v2 (Plus plan)

请求参数

返回响应