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: api-help@photorom.com 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 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)' schema: default: true examples: - 'true' - 'false' type: boolean - name: imageFromPrompt.prompt in: query description: The prompt to use for generating the image. schema: examples: - a red car in the desert - a coffee mug on a countertop minLength: 1 type: string - name: imageFromPrompt.seed in: query description: Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt. schema: examples: - '123456' - '789012' type: number - name: imageFromPrompt.size in: query description: Supported sizes for AI image generation schema: examples: - SQUARE_HD - LANDSCAPE_16_9 - PORTRAIT_4_3 enum: - LANDSCAPE_16_9 - LANDSCAPE_4_3 - PORTRAIT_16_9 - PORTRAIT_4_3 - SQUARE_HD type: string - name: imageUrl in: query description: '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`.' schema: examples: - https://example.com/image.jpg type: string - name: keepExistingAlphaChannel in: query description: If set to `auto` and if the image has transparency, the existing transparency will be used to cutout the subject. schema: default: never enum: - auto - never examples: - auto - never type: string - name: layers in: query schema: additionalProperties: anyOf: - additionalProperties: false properties: text: additionalProperties: false properties: backgroundColor: type: string content: type: string font: type: string foregroundColor: type: string type: object required: - text type: object - additionalProperties: false properties: image: additionalProperties: false properties: horizontalAlignment: enum: - left - center - right type: string imageFile: description: '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`.' examples: - image.jpg format: binary type: string imageFromPrompt: additionalProperties: false description: Instead of providing an image, you can provide a prompt to generate an image. properties: prompt: description: The prompt to use for generating the image. examples: - a red car in the desert - a coffee mug on a countertop minLength: 1 type: string seed: description: Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt. examples: - '123456' - '789012' type: number size: description: Supported sizes for AI image generation examples: - SQUARE_HD - LANDSCAPE_16_9 - PORTRAIT_4_3 enum: - LANDSCAPE_16_9 - LANDSCAPE_4_3 - PORTRAIT_16_9 - PORTRAIT_4_3 - SQUARE_HD type: string required: - prompt type: object imageUrl: description: '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`.' examples: - https://example.com/image.jpg type: string margin: type: - number - string marginBottom: type: - number - string marginLeft: type: - number - string marginRight: type: - number - string marginTop: type: - number - string padding: type: - number - string paddingBottom: type: - number - string paddingLeft: type: - number - string paddingRight: type: - number - string paddingTop: type: - number - string removeBackground: enum: - auto - never type: string segmentation: additionalProperties: false properties: mode: description: Controls whether or not the salient object should be kept or ignored by the segmentation model. enum: - keepSalientObject - ignoreSalientObject type: string negativePrompt: description: A textual description of what the segmentation should remove. examples: - a red object type: string prompt: description: 'Warning: Text-Guided Segmentation is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. A textual description of what the segmentation should keep.' examples: - a red object type: string required: - prompt type: object useForAIBackground: enum: - auto - never type: string verticalAlignment: enum: - top - center - bottom type: string type: object required: - image type: object type: object - name: lighting.mode in: query description: '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' schema: enum: - ai.auto - ai.preserve-hue-and-saturation examples: - ai.auto - ai.preserve-hue-and-saturation type: string - name: margin in: query description: '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](https://docs.photoroom.com/image-editing-api-plus-plan/positioning).' schema: default: 0 examples: - '0.3' - 30% - 100px type: - number - string - name: marginBottom in: query description: Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as `margin`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: marginLeft in: query description: Left Margin, overrides general margin on the left side. Accepts the same formats as `margin`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: marginRight in: query description: Right Margin, overrides general margin on the right side. Accepts the same formats as `margin`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: marginTop in: query description: Top Margin, overrides general margin on the top side. Accepts the same formats as `margin`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: maxHeight in: query description: 'Maximum output height. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: redimensioning while keeping the aspect ratio' schema: examples: - '200' type: number - name: maxWidth in: query description: 'Maximum output width. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: resizing an image while keeping the aspect ratio' schema: examples: - '200' type: number - name: outline.blurRadius in: query description: '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' schema: default: 0 examples: - 0.01 - 0.02 - 0.025 maximum: 0.025 minimum: 0 type: number - name: outline.color in: query description: '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`)' schema: examples: - FF0000 - red type: string - name: outline.width in: query description: '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' schema: default: 0.03 examples: - 0.01 - 0.02 - 0.05 maximum: 0.1 minimum: 0 type: number - name: outputSize in: query description: 'Output size of the image. In the form of either: - `auto` to keep the template dimensions when templateId is defined, or behave like `originalImage` when templateId isn''t defined (default) - `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' schema: default: auto examples: - 200x400 - originalImage - croppedSubject pattern: ^(auto|\d+x\d+|originalImage|croppedSubject)$ type: string - name: padding in: query description: '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](https://docs.photoroom.com/image-editing-api-plus-plan/positioning).' schema: default: 0 examples: - '0.3' - 30% - 100px type: - number - string - name: paddingBottom in: query description: Bottom padding, overrides general padding on the bottom side. Accepts the same formats as `padding`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: paddingLeft in: query description: Left padding, overrides general padding on the left side. Accepts the same formats as `padding`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: paddingRight in: query description: Right padding, overrides general padding on the right side. Accepts the same formats as `padding`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: paddingTop in: query description: Top padding, overrides general padding on the top side. Accepts the same formats as `padding`. schema: examples: - '0.3' - 30% - 100px type: - number - string - name: preserveMetadata in: query description: "Controls which metadata from the original image will be preserved\ \ in the output image.\n\n- `never`: No metadata preservation (default)\n\ - `xmp`: Preserve XMP metadata including camera settings, copyright information,\ \ and other embedded metadata\n- `exifSubset`: Preserve EXIF Copyright (IFD0)\ \ and UserComment (ExifIFD) fields only. **Deprecated** \u2014 use `exifSubsetWithXmpCompatibility`\ \ instead. Will be removed in a future release.\n- `exifSubsetWithXmpCompatibility`:\ \ Same as `exifSubset` but 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)." schema: default: never enum: - never - xmp - exifSubset - exifSubsetWithXmpCompatibility examples: - never - xmp - exifSubset - exifSubsetWithXmpCompatibility type: string - name: referenceBox in: query description: '[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)' schema: default: subjectBox enum: - subjectBox - originalImage examples: - subjectBox - originalImage type: string - name: removeBackground in: query description: If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm schema: default: true examples: - 'true' - 'false' type: boolean - name: scaling in: query description: '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' schema: default: fit enum: - fit - fill examples: - fit - fill type: string - name: segmentation.mode in: query description: Controls whether or not the salient object should be kept or ignored by the segmentation model. schema: enum: - keepSalientObject - ignoreSalientObject type: string - name: segmentation.negativePrompt in: query description: A textual description of what the segmentation should remove. schema: examples: - a red object type: string - name: segmentation.prompt in: query description: 'Warning: Text-Guided Segmentation is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. A textual description of what the segmentation should keep.' schema: examples: - a red object type: string - name: shadow.directionOverride in: query description: 'Override for the direction of the shadow. Can be provided either as an angle in degrees or as one of the following presets: - `behind` = 0 - `behindLeft` = 45 - `left` = 90 - `frontLeft` = 135 - `front` = 180 - `frontRight` = 225 - `right` = 270 - `behindRight` = 315 When using degrees, 0 means the shadow is behind the subject, 90 means the shadow is at the left of the subject, 180 means the shadow is in front of the subject, and 270 means the shadow is at the right of the subject. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' schema: anyOf: - type: number - enum: - behind - behindLeft - left - frontLeft - front - frontRight - right - behindRight type: string examples: - 0 - 90 - 180 - 270 - behind - left - frontRight - name: shadow.intensityOverride in: query description: 'Override for the intensity of the shadow. 0 means a very faint shadow, 1 means a very dark shadow. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' schema: examples: - 0 - 0.5 - 1 maximum: 1 minimum: 0 type: number - name: shadow.mode in: query description: Shadow generation mode to use on the main image used by the API. If set to `ai.soft`, a soft shadow will be generated. Only compatible with legacy AI Shadows models If set to `ai.hard`, a hard shadow will be generated. Only compatible with legacy AI Shadows models If set to `ai.floating`, a floating shadow will be generated. Not compatible with the `2026-04-15` AI Shadows model If set to `ai.preset-soft`, a soft shadow will be generated. Only compatible with the `2026-04-15` AI Shadows model If set to `ai.preset-hard`, a hard shadow will be generated. Only compatible with the `2026-04-15` AI Shadows model If set to `ai.auto-with-overrides`, a shadow with most natural appearance for the input image will be generated. Override parameters can be provided to gain full control over the appearance of that shadow. Only compatible with the `2026-04-15` AI Shadows model schema: enum: - ai.soft - ai.hard - ai.floating - ai.preset-soft - ai.preset-hard - ai.auto-with-overrides examples: - ai.soft - ai.hard - ai.floating - ai.preset-soft - ai.preset-hard - ai.auto-with-overrides type: string - name: shadow.softnessOverride in: query description: 'Override for the softness of the shadow. 0 means a very hard shadow, 1 means a very soft shadow. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' schema: examples: - 0 - 0.35 - 1 maximum: 1 minimum: 0 type: number - name: shadow.spreadOverride in: query description: 'Override for the spread of the shadow. Can be provided either as an angle in degrees or as one of the following presets: - `short` = 10 - `medium` = 45 - `long` = 90 When using degrees, 0 means a very short shadow and 90 means a very long shadow. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' schema: anyOf: - type: number - enum: - short - medium - long type: string examples: - 0 - 25 - 45 - 90 - short - medium - long - name: shadow.subjectPoseOverride in: query description: 'Override for the pose of the subject. Can be provided either as an angle in degrees or as one of the following presets: - `flatlay` = 0 - `upright` = 90 When using degrees, 0 means the subject is laying flat and 90 means the subject is placed upright. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' schema: anyOf: - type: number - enum: - flatlay - upright type: string examples: - 0 - 45 - 90 - flatlay - upright - name: templateId in: query description: The ID of the template to render schema: format: uuid type: string - name: textRemoval.mode in: query description: '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.' schema: enum: - ai.artificial - ai.natural - ai.all examples: - ai.artificial - ai.natural - ai.all type: string - name: uncrop.mode in: query description: '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.' schema: const: ai.auto examples: - ai.auto type: string - name: uncrop.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: upscale.downscaleIfNeeded in: query description: 'Optional input downscaling strategy applied before AI Upscale when the selected model rejects the current input size. `never`: keep the current behavior and return an error when the image is too large. `always`: downscale oversized images to the largest input size accepted by the selected model before upscaling. `skipUpscaleIfNotNeeded`: only downscale oversized images when the 4x upscaled result can still be at least as large as the original input.' schema: enum: - never - always - skipUpscaleIfNotNeeded examples: - never - always - skipUpscaleIfNotNeeded type: string - name: upscale.mode in: query description: 'Warning: AI Upscale is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. If enabled, the input image will be upscaled (imageFile or imageUrl) Input limits depend on the model selected for AI Upscale. With the default model: - `ai.fast`: maximum 1,000,000 input pixels - `ai.slow`: maximum 262,144 input pixels 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.' schema: enum: - ai.fast - ai.slow examples: - ai.fast - ai.slow type: string - name: verticalAlignment in: query description: '[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.' schema: enum: - top - center - bottom examples: - top - center - bottom type: string - name: virtualModel.additionalProductImages in: query description: 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. schema: items: additionalProperties: false properties: imageFile: description: Bytes of an additional product image. Only available in the POST request. format: binary type: string imageUrl: description: URL of an additional product image. examples: - https://example.com/product-back.jpg type: string type: object maxItems: 4 minItems: 1 type: array - name: virtualModel.mode in: query description: Must be set to `ai.auto` to enable virtual model generation. schema: const: ai.auto examples: - ai.auto type: string - name: virtualModel.model in: query description: The model (person) to use for the virtual try-on. Either a preset model name or a custom image. schema: anyOf: - additionalProperties: false properties: preset: additionalProperties: false description: Use a preset model by name. properties: name: description: Name of the preset model. enum: - avery - sam - taylor - kendall - jordan - casey - alex - maya - reece - lena - julia - jackson - sophia - emma - ava - zoe - fiona examples: - avery - jordan - sophia type: string required: - name type: object required: - preset type: object - additionalProperties: false properties: custom: additionalProperties: false description: Use a custom model image. properties: imageFile: description: Bytes of a custom model image. Only available in the POST request. format: binary type: string imageUrl: description: URL of a custom model image. examples: - https://example.com/model.jpg type: string type: object required: - custom type: object default: preset: name: avery - name: virtualModel.pose in: query description: The pose of the model in the generated image. schema: default: random enum: - random - standing - 34turn - powerstance - walkingforward - handinpocket - crossedarms - back - overtheshoulder - seated - adjustingclothing - playfulspin examples: - standing - 34turn - overtheshoulder - seated type: string - name: virtualModel.prompt in: query description: Optional text prompt to guide the generation style. schema: examples: - street style - studio look - casual outdoor type: string - name: virtualModel.quality in: query description: The output quality of the generated image. Higher quality produces larger images. `standard` outputs ~1K, `advanced` ~2K, and `premium` ~4K resolution. schema: default: standard enum: - standard - advanced - premium examples: - standard - advanced - premium type: string - name: virtualModel.scene in: query description: The scene (background/environment) to use. Either a preset scene name or a custom image. schema: anyOf: - additionalProperties: false properties: preset: additionalProperties: false description: Use a preset scene by name. properties: name: description: Name of the preset scene. enum: - random - street - bedroom - sunset - factory - studio - coloredstudio - concretestudio - beach - tropical - library - forest - businessdistrict - countryside - flowers - goldenlight - mountain - pool - latincity - cafe - asiancity - nightlights - desert examples: - street - studio - beach type: string required: - name type: object required: - preset type: object - additionalProperties: false properties: custom: additionalProperties: false description: Use a custom scene image. properties: imageFile: description: Bytes of a custom scene image. Only available in the POST request. format: binary type: string imageUrl: description: URL of a custom scene image. examples: - https://example.com/scene.jpg type: string type: object required: - custom type: object default: preset: name: random - name: virtualModel.size in: query description: The output size of the generated image. schema: default: PORTRAIT_HD_3_2 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 responses: '200': description: OK content: image/png: schema: $ref: '#/components/schemas/image-response' 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. pr-ai-background-seed: schema: summary: The seed used when generating the background description: This is the seed used when generating the background. Can be used to get similar looking results for the same prompt. pr-texts-detected: schema: summary: The number of texts detected in the image description: When removing texts from an image, it will return the number of texts detected. pr-unsupported-attributes: schema: summary: 'Unsupported Attributes (example: pr-unsupported-attributes=''Unsupported attributes: background.inner'')' description: '[Temporary] If the request contains attributes that are not supported by the API, this header will be returned with a list of the unsupported attributes. Soon to be replaced by a 400 Bad Request response.' pr-edit-further-url: schema: summary: A URL to open the result of the API call in the Photoroom webapp and edit it further description: If you're not fully satisfied with the result returned by the Image Editing API, it's possible to open the result image inside the Photoroom Web App, where you'll be able to adjust the result '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/edit-image-bad-request' '402': description: Payment Required content: application/json: schema: $ref: '#/components/schemas/payment-error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/unknown-error' post: operationId: edit-image-post 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 an image file for\ \ the image. If you want to send a URL, 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.\n\ \nIf you only have a URL for your image (not a local file), use the GET endpoint\ \ instead \u2014 it is simpler to integrate. Use this POST endpoint when you\ \ need to upload image files directly as multipart/form-data.\n\nFor this\ \ POST endpoint, all parameters must be passed via the request body using\ \ multipart/form-data encoding. Parameters must not be passed using the query\ \ string.\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) requestBody: content: multipart/form-data: schema: type: object properties: background.blur.mode: type: string 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.' background.blur.radius: type: number description: 'Radius of the blur effect. Higher values mean the result will be blurrier. Minimum: 0, Maximum: 0.05' background.color: type: string 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.' background.expandPrompt: 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.' background.guidance.imageFile: type: string format: binary 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.' background.guidance.scale: type: number 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))' background.imageFile: type: string format: binary description: '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.' background.negativePrompt: type: string 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.' background.prompt: type: string 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.' background.scaling: type: string 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' background.seed: type: number description: Seed used to generate the background. Can be used to get similar looking results for the same prompt. beautify.mode: type: string 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.' beautify.seed: type: number description: Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject. describeAnyChange.mode: type: string 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.' describeAnyChange.prompt: type: string description: '(DEPRECATED) Use `editWithAI.prompt` instead. The natural language prompt describing the change to apply to the image.' describeAnyChange.seed: type: number description: '(DEPRECATED) Use `editWithAI.seed` instead. Seed used for the generation. Can be used to get similar looking results for the same prompt.' editWithAI.additionalImages.{key}.imageFile: type: string format: binary description: Bytes of an additional reference image. Only available in the POST request. editWithAI.mode: type: string description: 'Edit with AI mode to use on the main image used by the API. Currently, only `ai.auto` is supported.' editWithAI.prompt: type: string description: The natural language prompt describing the change to apply to the image. editWithAI.seed: type: number description: Seed used for the generation. Can be used to get similar looking results for the same prompt. expand.mode: type: string 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.' expand.seed: type: number description: Seed used to generate the background. Can be used to get similar looking results for the same prompt. export.dpi: type: number description: 'The pixel density of the result image. Pixel density can be set to any value between 72 and 1200 dpi.' export.format: type: string 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.' flatLay.mode: type: string description: Must be set to `ai.auto` to enable flat lay generation. flatLay.prompt: type: string description: Optional text prompt to guide the generation style. flatLay.size: type: string description: The output size of the generated image. ghostMannequin.mode: type: string description: Must be set to `ai.auto` to enable ghost mannequin generation. ghostMannequin.prompt: type: string description: Optional text prompt to guide the generation style. ghostMannequin.size: type: string description: The output size of the generated image. horizontalAlignment: type: string 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.' ignorePaddingAndSnapOnCroppedSides: type: boolean description: '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)' imageFile: type: string format: binary description: '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`.' imageFromPrompt.prompt: type: string description: The prompt to use for generating the image. imageFromPrompt.seed: type: number description: Seed used to run the AI image generator. Can be used to get similar looking results for the same prompt. imageFromPrompt.size: type: string description: Supported sizes for AI image generation keepExistingAlphaChannel: type: string description: If set to `auto` and if the image has transparency, the existing transparency will be used to cutout the subject. layers: type: object lighting.mode: type: string description: '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' margin: type: - number - string description: '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](https://docs.photoroom.com/image-editing-api-plus-plan/positioning).' marginBottom: type: - number - string description: Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as `margin`. marginLeft: type: - number - string description: Left Margin, overrides general margin on the left side. Accepts the same formats as `margin`. marginRight: type: - number - string description: Right Margin, overrides general margin on the right side. Accepts the same formats as `margin`. marginTop: type: - number - string description: Top Margin, overrides general margin on the top side. Accepts the same formats as `margin`. maxHeight: type: number description: 'Maximum output height. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: redimensioning while keeping the aspect ratio' maxWidth: type: number description: 'Maximum output width. Can only be provided if `outputSize` is `originalImage` or `croppedSubject`. Useful for: resizing an image while keeping the aspect ratio' outline.blurRadius: type: number description: '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' outline.color: type: string description: '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`)' outline.width: type: number description: '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' outputSize: type: string description: 'Output size of the image. In the form of either: - `auto` to keep the template dimensions when templateId is defined, or behave like `originalImage` when templateId isn''t defined (default) - `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' padding: type: - number - string description: '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](https://docs.photoroom.com/image-editing-api-plus-plan/positioning).' paddingBottom: type: - number - string description: Bottom padding, overrides general padding on the bottom side. Accepts the same formats as `padding`. paddingLeft: type: - number - string description: Left padding, overrides general padding on the left side. Accepts the same formats as `padding`. paddingRight: type: - number - string description: Right padding, overrides general padding on the right side. Accepts the same formats as `padding`. paddingTop: type: - number - string description: Top padding, overrides general padding on the top side. Accepts the same formats as `padding`. preserveMetadata: type: string description: "Controls which metadata from the original image will\ \ be preserved in the output image.\n\n- `never`: No metadata\ \ preservation (default)\n- `xmp`: Preserve XMP metadata including\ \ camera settings, copyright information, and other embedded metadata\n\ - `exifSubset`: Preserve EXIF Copyright (IFD0) and UserComment\ \ (ExifIFD) fields only. **Deprecated** \u2014 use `exifSubsetWithXmpCompatibility`\ \ instead. Will be removed in a future release.\n- `exifSubsetWithXmpCompatibility`:\ \ Same as `exifSubset` but 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)." referenceBox: type: string description: '[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)' removeBackground: type: boolean description: If enabled (default), the background of the image will be removed using PhotoRoom's award-winning algorithm scaling: type: string description: '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' segmentation.mode: type: string description: Controls whether or not the salient object should be kept or ignored by the segmentation model. segmentation.negativePrompt: type: string description: A textual description of what the segmentation should remove. segmentation.prompt: type: string description: 'Warning: Text-Guided Segmentation is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. A textual description of what the segmentation should keep.' shadow.directionOverride: description: 'Override for the direction of the shadow. Can be provided either as an angle in degrees or as one of the following presets: - `behind` = 0 - `behindLeft` = 45 - `left` = 90 - `frontLeft` = 135 - `front` = 180 - `frontRight` = 225 - `right` = 270 - `behindRight` = 315 When using degrees, 0 means the shadow is behind the subject, 90 means the shadow is at the left of the subject, 180 means the shadow is in front of the subject, and 270 means the shadow is at the right of the subject. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' shadow.intensityOverride: type: number description: 'Override for the intensity of the shadow. 0 means a very faint shadow, 1 means a very dark shadow. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' shadow.mode: type: string description: Shadow generation mode to use on the main image used by the API. If set to `ai.soft`, a soft shadow will be generated. Only compatible with legacy AI Shadows models If set to `ai.hard`, a hard shadow will be generated. Only compatible with legacy AI Shadows models If set to `ai.floating`, a floating shadow will be generated. Not compatible with the `2026-04-15` AI Shadows model If set to `ai.preset-soft`, a soft shadow will be generated. Only compatible with the `2026-04-15` AI Shadows model If set to `ai.preset-hard`, a hard shadow will be generated. Only compatible with the `2026-04-15` AI Shadows model If set to `ai.auto-with-overrides`, a shadow with most natural appearance for the input image will be generated. Override parameters can be provided to gain full control over the appearance of that shadow. Only compatible with the `2026-04-15` AI Shadows model shadow.softnessOverride: type: number description: 'Override for the softness of the shadow. 0 means a very hard shadow, 1 means a very soft shadow. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' shadow.spreadOverride: description: 'Override for the spread of the shadow. Can be provided either as an angle in degrees or as one of the following presets: - `short` = 10 - `medium` = 45 - `long` = 90 When using degrees, 0 means a very short shadow and 90 means a very long shadow. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' shadow.subjectPoseOverride: description: 'Override for the pose of the subject. Can be provided either as an angle in degrees or as one of the following presets: - `flatlay` = 0 - `upright` = 90 When using degrees, 0 means the subject is laying flat and 90 means the subject is placed upright. This option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.' templateId: type: string format: uuid description: The ID of the template to render textRemoval.mode: type: string description: '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: type: string description: '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.' uncrop.seed: type: number description: Seed used to generate the background. Can be used to get similar looking results for the same prompt. upscale.downscaleIfNeeded: type: string description: 'Optional input downscaling strategy applied before AI Upscale when the selected model rejects the current input size. `never`: keep the current behavior and return an error when the image is too large. `always`: downscale oversized images to the largest input size accepted by the selected model before upscaling. `skipUpscaleIfNotNeeded`: only downscale oversized images when the 4x upscaled result can still be at least as large as the original input.' upscale.mode: type: string description: 'Warning: AI Upscale is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. If enabled, the input image will be upscaled (imageFile or imageUrl) Input limits depend on the model selected for AI Upscale. With the default model: - `ai.fast`: maximum 1,000,000 input pixels - `ai.slow`: maximum 262,144 input pixels 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.' verticalAlignment: type: string description: '[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.' virtualModel.additionalProductImages: type: array description: 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. virtualModel.mode: type: string description: Must be set to `ai.auto` to enable virtual model generation. virtualModel.model: description: The model (person) to use for the virtual try-on. Either a preset model name or a custom image. virtualModel.pose: type: string description: The pose of the model in the generated image. virtualModel.prompt: type: string description: Optional text prompt to guide the generation style. virtualModel.quality: type: string description: The output quality of the generated image. Higher quality produces larger images. `standard` outputs ~1K, `advanced` ~2K, and `premium` ~4K resolution. virtualModel.scene: description: The scene (background/environment) to use. Either a preset scene name or a custom image. virtualModel.size: type: string description: The output size of the generated image. responses: '200': description: OK content: image/png: schema: $ref: '#/components/schemas/image-response' 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. pr-ai-background-seed: schema: summary: The seed used when generating the background description: This is the seed used when generating the background. Can be used to get similar looking results for the same prompt. pr-texts-detected: schema: summary: The number of texts detected in the image description: When removing texts from an image, it will return the number of texts detected. pr-unsupported-attributes: schema: summary: 'Unsupported Attributes (example: pr-unsupported-attributes=''Unsupported attributes: background.inner'')' description: '[Temporary] If the request contains attributes that are not supported by the API, this header will be returned with a list of the unsupported attributes. Soon to be replaced by a 400 Bad Request response.' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/edit-image-bad-request' '402': description: Payment Required content: application/json: schema: $ref: '#/components/schemas/payment-error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/unknown-error' /v1/render: get: operationId: edit-image-get summary: '[LEGACY] Image Editing v1 (Plus plan)' description: 'Deprecated: use /v2/edit instead. This is a legacy endpoint, it is not recommended for new integrations. For new integrations, please use /v2/edit which offers all the same functionalities, plus additional AI features.' servers: - url: https://image-api.photoroom.com description: Production server (Plus plan) parameters: - schema: type: string title: API Key description: The API key to authenticate the request example: 4a5b60936c3a934hqb3cf5838b390dc3d4dfc9da required: false description: The API key to authenticate the request name: apiKey in: query - schema: type: string description: The ID of the template to render title: Template ID example: 592dd982-4a1b-4cd9-ab11-21481d5a0064 required: true description: The ID of the template to render name: templateId in: query - schema: type: string format: uri title: Image URL description: The image URL to render example: https://s3.amazonaws.com/a.storyblok.com/f/191576/1024x1024/d25e1a99d7/sample-05.png required: false description: The image URL to render name: imageUrl in: query - schema: type: string format: uri title: Concept URL description: Deprecated, use `imageUrl` instead. example: https://s3.amazonaws.com/a.storyblok.com/f/191576/1024x1024/d25e1a99d7/sample-05.png deprecated: true required: false description: Deprecated, use `imageUrl` instead. name: conceptUrl in: query responses: '200': description: OK content: image/png: schema: type: string title: Resulting image description: The resulting image after rendering format: binary '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: 'imageUrl: must be provided' required: - message required: - error title: Field Missing Error '402': description: Payment Required content: application/json: schema: 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 '403': description: Forbidden '500': description: Internal Server Error content: application/json: schema: 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 post: operationId: edit-image-post summary: '[LEGACY] Image Editing v1 (Plus plan)' description: 'Deprecated: use /v2/edit instead. This is a legacy endpoint, it is not recommended for new integrations. For new integrations, please use /v2/edit which offers all the same functionalities, plus additional AI features.' servers: - url: https://image-api.photoroom.com description: Production server (Plus plan) requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/render-image-post-params' responses: '200': description: OK content: image/png: schema: type: string title: Resulting image description: The resulting image after rendering format: binary '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: 'imageFile: must be provided' required: - message required: - error title: Field Missing Error '402': description: Payment Required content: application/json: schema: 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 '403': description: Forbidden '500': description: Internal Server Error content: application/json: schema: 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