# Introduction {% hint style="info" %} You can download the API Reference (OpenAPI specification), which contains the full list of endpoints, parameters and authentication [here](https://image-api.photoroom.com/openapi). {% endhint %} Here's a walkthrough of the latest API feature: {% embed url="" %} ## How does the API work? The Photoroom API enables you to easily create high-quality images. It allows you to separate a subject from its background, [re-light](/image-editing-api-plus-plan/ai-relight) this subject, add a [realistic shadow](/image-editing-api-plus-plan/ai-shadows), generate a [new background](/image-editing-api-plus-plan/ai-backgrounds), [resize](/image-editing-api-plus-plan/positioning) to given requirements, and more. Our models are specialized in photo editing using AI. The API was designed with the goal of being extremely easy to use and integrate. All endpoints follow the same logic: they take an image as their input, apply edits to it, and return their result as a new edited image. ## Which API should I use? The Photoroom API consists of two API endpoints, which are available in [two different plans](https://www.photoroom.com/api/pricing). If you want to **apply edits** to your image, such as resizing, replacing the background, re-lighting the subject or adding a realistic shadow, then you'll want to call the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide): {% content-ref url="/pages/thC1at2oJWyT9L4jvKI0" %} [Image Editing API (Plus plan)](/image-editing-api-plus-plan/quickstart-guide) {% endcontent-ref %} However, if you **only need to remove the background** from an image and don't need to perform any additional edits, then you'll want to call the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide): {% content-ref url="/pages/STCMyGVNGraHTMkLfQGo" %} [Remove Background API (Basic plan)](/remove-background-api-basic-plan/quickstart-guide) {% endcontent-ref %} {% hint style="warning" %} Please keep in mind that 1 call to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) is worth 5 calls to the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). More details about how API calls are billed is [available here](/getting-started/pricing). {% endhint %} ## Which AI features are available in the API? The Photoroom API enables you to create great looking images through a collection of state-of-the-art AI features. Here's a list of all the AI features that are available in the Photoroom API: **Background and scene** * AI Background Removal (available in both the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) and the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Shadows](/image-editing-api-plus-plan/ai-shadows) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Relight](/image-editing-api-plus-plan/ai-relight) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Create Any Image](/image-editing-api-plus-plan/create-any-image) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) **Framing and geometry** * [Positioning](/image-editing-api-plus-plan/positioning) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Smart Cropping](/image-editing-api-plus-plan/smart-cropping) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Perspective Correction](/image-editing-api-plus-plan/perspective-correction) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide), Enterprise plans only) **Image edits** * [AI Text Removal](/image-editing-api-plus-plan/ai-text-removal) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Expand](/image-editing-api-plus-plan/ai-expand) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Upscale](/image-editing-api-plus-plan/preview-ai-upscale) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Edit With AI](/image-editing-api-plus-plan/edit-with-ai) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) **Clothing and fashion** * [AI Ironing](/image-editing-api-plus-plan/ai-ironing) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Virtual Model](/image-editing-api-plus-plan/virtual-model) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Virtual Try-On](/image-editing-api-plus-plan/virtual-try-on) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Flat Lay](/image-editing-api-plus-plan/flat-lay) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) * [Ghost Mannequin](/image-editing-api-plus-plan/ghost-mannequin) (available in the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide)) ## Will the API make alterations to my products? No, for most use cases the API will not make alterations to your products. By default, the API will: 1. Remove the background of the original image to isolate its main subject. 2. Reposition and add effects around that main subject. With this approach, it's simply not possible to introduce alterations, such as modifying a logo or a brand name. The API does offer some features that can, however, introduce alterations. Here's their exhaustive list. ### Features that alter the framing or geometry of the image No generative AI is involved, so hallucinations are impossible by design. * [Positioning](/image-editing-api-plus-plan/positioning), which can crop the edges of the main subject when `scaling` is set to `fill` * [Smart Cropping](/image-editing-api-plus-plan/smart-cropping), which crops the original image around its main subject * [Perspective Correction](/image-editing-api-plus-plan/perspective-correction), which geometrically straightens rectangular products ### Features that alter the content of the image using an AI model * [AI Relight](/image-editing-api-plus-plan/ai-relight) and [Green Screen Despill](/remove-background-api-basic-plan/green-screen-despill), which can alter colors * [AI Text Removal](/image-editing-api-plus-plan/ai-text-removal), which removes text from the main subject * [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) and [AI Expand](/image-editing-api-plus-plan/ai-expand), which generate the missing parts of the original image * [AI Upscale](/image-editing-api-plus-plan/preview-ai-upscale), which increases the resolution of the original image * [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier), which creates a re-imagined version of the main subject * [Edit With AI](/image-editing-api-plus-plan/edit-with-ai), which edits the original image using an AI model * [AI Ironing](/image-editing-api-plus-plan/ai-ironing), [Virtual Model](/image-editing-api-plus-plan/virtual-model), [Virtual Try-On](/image-editing-api-plus-plan/virtual-try-on), [Flat Lay](/image-editing-api-plus-plan/flat-lay), and [Ghost Mannequin](/image-editing-api-plus-plan/ghost-mannequin), which edit clothing images using an AI model {% hint style="warning" %} If you use one of these features and product accuracy is important for you, then we recommend that you have a human validation of the images produced by the API. {% endhint %} ## How can I get my API key? In order to use the Photoroom API, you'll first need to activate the API for your account and obtain your unique API key. Here's how to do it: 1. **Activate the API for your account**: This can be done by [visiting your account settings](https://app.photoroom.com/api-dashboard) on the Photoroom website. Make sure that you're logged into your account. {% hint style="info" %} We recommend that you use a generic email address (e.g. **) to create the Photoroom account that will own your API key. Not using a personal email address (e.g. ) allows you to retain ownership over your details and API key(s) even if members of your team leave your organization. {% endhint %} 2. **Copy your API key**: Once you've activated the API for your account, you'll be provided with a unique API key. This key is essentially your password to make API calls, so it's important to keep it safe and secure. You can retrieve your API key by following the [same link used for the activation](https://app.photoroom.com/api-dashboard). {% hint style="danger" %} Keep in mind that your API key is tied to your account and should be kept secret. It should not be shared publicly or with others. If you believe your API key has been compromised, you can revoke it yourself on the [API dashboard](https://app.photoroom.com/api-dashboard) and create a new one. If you need more help or believe your key has been used maliciously, you can [contact our support](/getting-started/support) for assistance​. {% endhint %} 3. **Use your API key**: The key must be passed in the `x-api-key` HTTP header on every request. If you have multiple teams or applications, you can create **multiple API keys** [in your account settings](https://app.photoroom.com/api-dashboard) and use one key per use case. For example, you can have separate keys for your development and production environments, or create keys for individual services. ## How do I make my first API call? Once you've [created your API key](/#how-can-i-get-my-api-key), you're all set to make your first API call! From there, there are two ways to start using the API: 1. If you already know which feature you're looking for, then you can simply use the *Try it now!* button that's available on the documentation page of that feature:
2. If not, then you can use the search bar at the top of the documentation and simply describe the output that you want to achieve:
{% hint style="info" %} Please note that you can make API calls for free using our [Sandbox mode](/getting-started/pricing#can-i-get-free-api-calls). {% endhint %} ## How do I integrate the API into my project? The Photoroom API uses standard HTTP calls, which makes it easy to integrate with any programming language or networking framework. For the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide), we provide API wrappers for [JavaScript](/remove-background-api-basic-plan/code-samples/web-integration), [Python](/remove-background-api-basic-plan/code-samples/python-integration), [Node.js](/remove-background-api-basic-plan/code-samples/node.js-integration), and [iOS](/remove-background-api-basic-plan/code-samples/ios-swift-integration). For the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) and the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide), we also provide integration tutorials that explain how to process images from: * [Local File System](/integrations/how-to-process-images-from-a-local-directory) * [Google Drive](/integrations/how-to-process-images-from-google-drive) & [Google Sheets](/integrations/how-to-process-images-from-google-sheets) * [Excel spreadsheets](/integrations/how-to-process-images-from-an-excel-spreadsheet) * [Zapier](/integrations/how-to-process-images-from-google-drive-using-zapier) & [Make.com](/integrations/how-to-process-images-from-google-drive-using-make.com) * [iOS & macOS Shortcuts](/integrations/how-to-process-images-using-an-ios-or-macos-shortcut) ## Recommended workflows by use case Before diving deeper into the details of the Photoroom API, we recommend reading the tutorials that best match your use cases. Each tutorial contains tested parameter combinations that produce high-quality results: * [How to improve images for second-hand item marketplaces](/tutorials/how-to-improve-images-for-second-hand-item-marketplaces) * [How to create e-commerce images with consistent brand guidelines](/tutorials/how-to-create-e-commerce-images-with-consistent-brand-guidelines) * [How to create food delivery images with consistent brand guidelines](/tutorials/how-to-create-food-delivery-images-with-consistent-brand-guidelines) * [How to create compliant product images for Google Shopping](/tutorials/how-to-create-compliant-product-images-for-google-shopping) * [How to create listing images for clothing and apparel](/tutorials/how-to-create-listing-images-for-clothing-and-apparel) * [How to create a selfie generator](/tutorials/how-to-create-a-selfie-generator) # Integrating with Claude Code or Codex AI coding agents such as [Claude Code](https://claude.com/claude-code) or [Codex](https://openai.com/codex/) are a fast way to integrate the Photoroom API: you describe the result you want and the agent writes, runs and debugs the code for you. To get good results, the agent needs to know how the Photoroom API works. This page gives you a pre-made prompt that contains everything the coding agent needs: endpoints, authentication, the most useful parameters, limits, and where to look for more details. {% hint style="info" %} This documentation is built to be read by agents. Every page is available as Markdown by appending `.md` to its URL, the full index is at [llms.txt](https://docs.photoroom.com/llms.txt), and the [OpenAPI specification](https://image-api.photoroom.com/openapi) lists every parameter. The prompt below teaches the agent to use these sources on its own. {% endhint %} ### Step 1: Get an API key If you don't have an API key yet, follow the [steps to create yours](/#how-can-i-get-my-api-key). While the agent is prototyping, we recommend using Sandbox mode: prepend `sandbox_` to your API key and calls are free (results are watermarked). Store the key in an environment variable rather than pasting it into the conversation, so that it never ends up in your code or in your Git history: ```bash export PHOTOROOM_API_KEY="sandbox_xxxxxxxxxxxxxxxx" ``` ### Step 2: Copy the prompt Copy the prompt below and paste it into Claude Code or Codex, followed by a description of what you want to build (see the examples in Step 3). {% code title="Photoroom API prompt for coding agents" overflow="wrap" %} ``` You are going to integrate the Photoroom API. Everything you need to know is below. Read it fully before writing code. # 1. Documentation sources (use them when you need details not covered here) - Full index of the documentation: https://docs.photoroom.com/llms.txt - Any documentation page is available as Markdown by appending `.md` to its URL, for example https://docs.photoroom.com/image-editing-api-plus-plan/ai-shadows.md - Ask the documentation a question in natural language: GET https://docs.photoroom.com/getting-started/introduction.md?ask= - OpenAPI specification with every endpoint and parameter: https://image-api.photoroom.com/openapi - Do not guess parameter names or values: if a parameter is not listed in this prompt, fetch the relevant documentation page or the OpenAPI spec first. # 2. Authentication - Every request needs the header `x-api-key: `. - The API key is in the environment variable PHOTOROOM_API_KEY. Never hardcode it, never print it, never commit it. - Sandbox mode: an API key prefixed with `sandbox_` makes free calls (1,000 per month, 100 per day) that return a watermarked image. Use it for all tests and development. The production key (without the prefix) consumes credits. - A missing or invalid key returns HTTP 401; a key that is not allowed (or a credit balance of zero) returns HTTP 403 with body {"error":{"message":"Unauthorized"}}. - Check the account and remaining credits with GET https://image-api.photoroom.com/v2/account (returns {"images":{"available":N,"subscription":N},"plan":"..."}). # 3. The two APIs ## Image Editing API (Plus plan) — use this by default POST https://image-api.photoroom.com/v2/edit (multipart/form-data, input as a file in `imageFile`) GET https://image-api.photoroom.com/v2/edit (query string, input as a public URL in `imageUrl`) Both endpoints accept the same parameters. Use POST for local files, GET for images already hosted online. - Input: PNG, JPEG or WEBP, max 30 MB, max 5,000 px on the widest side (larger images are downscaled). - Output: the response body is the image bytes (PNG by default). Save the body directly to a file; do not try to parse it as JSON unless the status code is not 200. - One image per call. Edits can be combined in a single call. - Response headers worth reading: `x-uncertainty-score` (0 = confident cutout, 1 = unsure, -1 = image contains humans). ## Remove Background API (Basic plan) — only if the user has a Basic plan or only needs background removal POST https://sdk.photoroom.com/v1/segment (multipart/form-data, input as a file in `image_file`) - Parameters: format (png|jpg|webp, default png), channels (rgba|alpha), bg_color (hex like #FFFFFF or color name), size (preview|medium|hd|full), crop (true|false), despill (true|false). - Input: PNG, JPEG, WEBP or HEIC, max 50 MB, max 6,000 px on the widest side. - Output: image bytes. EXIF metadata is not preserved, so apply EXIF rotation to the input before sending it. - Base64 input is also accepted as JSON: {"image_file_b64": "..."} with Content-Type: application/json. # 4. Image Editing API — parameters you will use most Parameters are grouped by feature using dot notation. Send them as form fields (POST) or query parameters (GET). Booleans are the strings `true`/`false`. Input - imageFile (POST) or imageUrl (GET): the image to edit. Required unless imageFromPrompt.prompt is used. - removeBackground: true (default) | false. Set to false to keep the original background and only apply other edits. Feature headers (HTTP headers, NOT form fields — send them next to x-api-key) Some features select a model or enable a mode through a request header. These are headers on the HTTP request, not parameters in the body or query string. - pr-ai-background-model-version: selects the AI Backgrounds model used with background.prompt. Values: 3 (current default), background-studio-beta-2025-03-17 (recommended: more photorealistic, better textures and props, a bit slower), 2 (deprecated; the only model that honours background.negativePrompt). - pr-ai-shadows-model-version: 2026-04-15 selects the new AI Shadows model. Required to use shadow.mode=ai.auto-with-overrides and the shadow.*Override parameters (softnessOverride, intensityOverride, spreadOverride, directionOverride, subjectPoseOverride). Without this header, only the legacy modes ai.soft | ai.hard | ai.floating work; with it, use ai.auto-with-overrides, ai.preset-soft or ai.preset-hard. - pr-hd-background-removal: auto enables HD Background Removal, recommended for high-resolution inputs (≥ 2K) to get more detailed subject edges. - pr-ai-upscale-model-version: ai-upscale-2025-07-29 gives early access to the newer model for upscale.mode=ai.fast. Headers and parameters must match: sending shadow.*Override parameters without the shadows header, or ai.soft with the header, will fail or be ignored. When copying an example from a documentation page, copy its --header lines too. Background (only when removeBackground=true) - background.color: hex without `#` (FFFFFF, FF0000EE) or color name (white, red). Omit for a transparent background. - background.prompt: text prompt to generate an AI background (e.g. "on a marble kitchen counter, soft morning light"). Add background.expandPrompt=ai.auto to let the API enrich short prompts. background.seed for reproducible results. For best results also send the header pr-ai-background-model-version: background-studio-beta-2025-03-17. - background.imageUrl (GET) / background.imageFile (POST): use a static image as background. background.scaling: fill (default) | fit. - background.blur.mode: gaussian | bokeh, with background.blur.radius (0 to 0.05). Shadows and lighting - shadow.mode: recommended — set header pr-ai-shadows-model-version: 2026-04-15 and shadow.mode=ai.auto-with-overrides (the model picks the best shadow; optionally fine-tune with shadow.softnessOverride 0–1, shadow.intensityOverride 0–1, shadow.spreadOverride short|medium|long or degrees, shadow.directionOverride behind|behindLeft|left|frontLeft|front|frontRight|right|behindRight or degrees, shadow.subjectPoseOverride flatlay|upright or degrees). Legacy modes without the header: ai.soft | ai.hard | ai.floating. - lighting.mode: ai.auto | ai.preserve-hue-and-saturation | ai.optimize-portrait (AI Relight). Size and positioning - outputSize: originalImage (default) | croppedSubject | WIDTHxHEIGHT (e.g. 1000x1000). - padding: 0 to 0.49, or "15%", or "100px". Space around the subject; per-side variants paddingTop/paddingBottom/paddingLeft/paddingRight. - margin: same formats as padding, but never ignored on cropped sides; per-side variants marginTop/etc. - scaling: fit (default) | fill. - horizontalAlignment: left | center | right. verticalAlignment: top | center | bottom. - maxWidth / maxHeight: resize while keeping aspect ratio (only with outputSize originalImage or croppedSubject). - ignorePaddingAndSnapOnCroppedSides: true (default) | false. Other edits - textRemoval.mode: ai.artificial (watermarks, prices, logos added in post) | ai.natural (text physically in the scene) | ai.all. - expand.mode: ai.auto — fills transparent/padding areas by extending the background (use with removeBackground=false or a static background and a larger outputSize). - uncrop.mode: ai.auto — regenerates the missing parts of a cropped subject. - upscale.mode: ai.fast | ai.slow (preview feature, up to 4x; input limits apply). - beautify.mode: ai.auto (packshot) | ai.food | ai.car — improves product/food/car images; not for humans or pets. - editWithAI.mode=ai.auto with editWithAI.prompt: free-form natural-language edit of the image. - imageFromPrompt.prompt: generate an image from text instead of editing an input image. - Other features (flatLay.*, ghostMannequin.*, virtualModel.*, ironing.mode, outline.*, segmentation.*, templateId, layers) are documented at https://docs.photoroom.com/llms.txt — fetch the page before using them. Export - export.format: png (default) | jpeg | webp | avif. JPEG does not support transparency: always set background.color when exporting to JPEG. - export.dpi: 72 to 1200. - preserveMetadata: never (default) | xmp. Reference example (product packshot on white with a soft shadow): curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header "x-api-key: $PHOTOROOM_API_KEY" \ --header "pr-ai-shadows-model-version: 2026-04-15" \ --form imageFile=@/absolute/path/to/image.jpg \ --form background.color=FFFFFF \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form outputSize=1600x1600 \ --form export.format=jpeg \ --output result.jpg # 5. Errors, limits and behaviour to implement - HTTP 200: body is the image. Any other status: body is a JSON error, usually {"error":{"message":"..."}} (the Remove Background API may return {"detail":"..."} instead). Always check the status code before writing the body to disk, and log the error message. - 400: invalid parameter or incompatible combination (e.g. JPEG export with transparency, background.imageUrl with removeBackground=false). Fix the request; do not retry as-is. - 401/403: authentication problem or no credits left. Do not retry. - 402: payment required (no credits). Do not retry. - 429: rate limit. Default limit is 60 images per minute. Back off and retry with exponential delay. - 500 or network timeout: retry up to 3 times with exponential backoff (e.g. 2s, 4s, 8s). - AI features (backgrounds, relight, shadows, uncrop, expand, upscale) take longer than plain background removal; set the HTTP client timeout to at least 60 seconds. Large images take longer. - Bulk processing: the API handles one image per call; run calls in parallel but stay under the rate limit (e.g. a worker pool of 5 to 10 with a token bucket). - Never overwrite the original images; write results to a separate output directory, keeping the original file names. - Each successful production call consumes credits, so avoid re-processing images that already have a result (check for an existing output file first). # 6. How to work 1. Confirm the API key is present in PHOTOROOM_API_KEY and check it with GET /v2/account before doing anything else. 2. Use a sandbox_ key for all development and tests. Ask before switching to a production key. 3. Test on a single image first, save the result, and verify it (open it or check that it is a valid image of the expected dimensions) before processing more. 4. Prefer the platform's standard HTTP client (curl, fetch, requests, URLSession…) with multipart/form-data; no SDK is required. 5. When a result does not look right, read the relevant feature page (append .md to its URL) or ask the documentation using the ?ask= query before changing parameters at random. ``` {% endcode %} ### Step 3: Describe what you want to build Right after the prompt, tell the agent what you need. The more precise you are about the input, the desired output, and the language or framework, the better. For example: * "Write a Python script that processes every JPEG in `./products`, removes the background, puts the subject on a white background with 15% padding and a soft shadow, and saves the results as 1600x1600 JPEGs in `./output`." * "Add an API route to this Next.js app that accepts an uploaded image, sends it to the Photoroom API to generate an AI background from a prompt provided by the user, and returns the resulting image." * "Create a Swift function for my iOS app that calls the Remove Background API and returns a `UIImage` with a transparent background." * "I need product images that comply with Google Shopping requirements: white background, the product filling 75 to 90% of the frame, no text. Write a script that does this for a CSV of image URLs." A few features (the newest [AI Shadows](/image-editing-api-plus-plan/ai-shadows) and [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) models, [HD Background Removal](/image-editing-api-plus-plan/hd-background-removal), the early-access [AI Upscale](/image-editing-api-plus-plan/preview-ai-upscale) model) are selected with an HTTP header such as `pr-ai-shadows-model-version` rather than a parameter. The prompt above covers them, but if you point the agent at a specific feature page, ask it to reproduce the `--header` lines of the examples, not just the `--form` parameters. ### Step 4 (optional): Make the instructions permanent If you plan to work on your Photoroom integration over several sessions, save the prompt in your repository so the agent loads it automatically: {% tabs %} {% tab title="Claude Code" %} Save the prompt as a file in your project (for example `docs/photoroom-api.md`) and reference it from your `CLAUDE.md`: ```markdown # Photoroom API When working with the Photoroom API, read and follow @docs/photoroom-api.md ``` Alternatively, save it as a skill in `.claude/skills/photoroom-api/SKILL.md` with a short frontmatter, so that Claude Code loads it only when the task involves the Photoroom API: ```markdown --- name: photoroom-api description: How to call the Photoroom Image Editing API and Remove Background API. Use whenever the task involves editing images, removing backgrounds, or the Photoroom API. --- (paste the prompt here) ``` {% endtab %} {% tab title="Codex" %} Save the prompt as a file in your project (for example `docs/photoroom-api.md`) and reference it from your `AGENTS.md`: ```markdown # Photoroom API When working with the Photoroom API, read and follow the instructions in docs/photoroom-api.md ``` Codex reads `AGENTS.md` at the root of the repository (and in subdirectories) at the start of each session. {% endtab %} {% endtabs %} {% hint style="warning" %} Never write your API key into `CLAUDE.md`, `AGENTS.md`, or any committed file. Keep it in the `PHOTOROOM_API_KEY` environment variable, or in a `.env` file that is listed in your `.gitignore`. {% endhint %} ### Prefer a no-code approach? If you want to edit images from a conversation rather than write code, the Photoroom API is also available as an MCP server that you can add as a custom connector in Claude. See the instructions at [photoroom.com/api/claude](https://www.photoroom.com/api/claude). # Pricing ## How are API calls billed? API usage is billed by the amount of images processed. Images are bought through a monthly subscription and consumed on each successful API call. Pricing details are [available here](https://www.photoroom.com/api/pricing). {% hint style="info" %} Calls that result in an error will **not** consume an image. {% endhint %} You can track how many images you have left in your [API dashboard](https://app.photoroom.com/api-dashboard):
{% hint style="warning" %} Please keep in mind that 1 call to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) is worth 5 calls to the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). This means that: * if you are on the Basic plan, a call to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will consume 5 images * if you are on the Plus plan, a call to the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) will consume 0.2 image {% endhint %} The API dashboard also contains a history of your recent credit consumption, accessible by clicking on the button *View usage details:*
If you want to monitor your credit balance with your own tools, you can do it [through this endpoint](/getting-started/api-reference-openapi#get-v2-account). {% hint style="info" %} Please note that API subscriptions are independent of the Pro subscription that gives access to the Photoroom app on iOS, Android, and the web. {% endhint %} ## Can I get free API calls? For testing and prototyping, you can use Sandbox mode on both the [Image Editing API](/image-editing-api-plus-plan/sandbox-mode) and the [Remove Background API](/remove-background-api-basic-plan/sandbox-mode), which allows you to make free API calls (but will produce a result with a watermark). If you're in the process of integrating the Photoroom API into your codebase and need additional free credits to test your integration, please [join our online API community](https://photoroom.discourse.group/) and ask our engineers. ## Do you offer Enterprise pricing? Yes, for large volumes (from 200K images/year) we do offer Enterprise pricing. For more details, please [contact our sales team](https://www.photoroom.com/contact-sales?utm_source=apidoc\&utm_medium=getting-started-pricing). Contact Sales ## How can I check my API usage? You can check your API usage by calling the endpoint: ```http GET https://image-api.photoroom.com/v2/account ``` This endpoint works for both the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) and the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). Here's an example of a call to this endpoint: ```shell curl --location 'https://image-api.photoroom.com/v2/account' \ --header 'x-api-key: YOUR_API_KEY' ``` And here's an example of the response you'll receive: ```json { "images": { "available": 83, "subscription": 100 }, "plan": "basic" } ``` {% hint style="info" %} You can use this endpoint to setup an automated monitoring of your API usage. {% endhint %} # Support If you encounter any technical issues integrating the API, you can join our [API community](https://photoroom.discourse.group/), this is a space our technical team closely monitors and would be happy to assist you. 1. If it's a technical question, please share with us: * A code sample to reproduce the bug * The original input image you used * The output image returned by Photoroom API * A detailed description or visual example of the expected image you would have liked to get\ We will then investigate the issue and come back to you shortly. 2. If it's a billing related question with sensitive information, please use the DM function on our community and start a chat with Photoroom. # Frequently Asked Questions ## Q: Will the API make alterations to my products? A: No, for most use cases the API will **not make** alterations to your products. By default, the API will: 1. Remove the background of the original image to isolate its main subject. 2. Reposition and add effects around that main subject. With this approach, it's simply not possible to introduce alterations, such as modifying a logo or a brand name. The API does offer some features that can, however, introduce alterations. Here's their exhaustive list. ### Features that alter the framing or geometry of the image No generative AI is involved, so hallucinations are impossible by design. * [Positioning](/image-editing-api-plus-plan/positioning), which can crop the edges of the main subject when `scaling` is set to `fill` * [Smart Cropping](/image-editing-api-plus-plan/smart-cropping), which crops the original image around its main subject * [Perspective Correction](/image-editing-api-plus-plan/perspective-correction), which geometrically straightens rectangular products ### Features that alter the content of the image using an AI model * [AI Relight](/image-editing-api-plus-plan/ai-relight) and [Green Screen Despill](/remove-background-api-basic-plan/green-screen-despill), which can alter colors * [AI Text Removal](/image-editing-api-plus-plan/ai-text-removal), which removes text from the main subject * [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) and [AI Expand](/image-editing-api-plus-plan/ai-expand), which generate the missing parts of the original image * [AI Upscale](/image-editing-api-plus-plan/preview-ai-upscale), which increases the resolution of the original image * [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier), which creates a re-imagined version of the main subject * [Edit With AI](/image-editing-api-plus-plan/edit-with-ai), which edits the original image using an AI model * [AI Ironing](/image-editing-api-plus-plan/ai-ironing), [Virtual Model](/image-editing-api-plus-plan/virtual-model), [Virtual Try-On](/image-editing-api-plus-plan/virtual-try-on), [Flat Lay](/image-editing-api-plus-plan/flat-lay), and [Ghost Mannequin](/image-editing-api-plus-plan/ghost-mannequin), which edit clothing images using an AI model {% hint style="warning" %} If you use one of these features and product accuracy is important for you, then we recommend that you have a human validation of the images produced by the API. {% endhint %} *** ## Q: Does the Photoroom API support MCP? A: Yes, the Photoroom API supports MCP and can be added as a custom connector in Claude. Here are the instructions: *** ## Q: **How can I monitor my credit balance?** A: You can track your current credit balance in your [API dashboard](https://app.photoroom.com/api-dashboard):
If you want to monitor your credit balance with your own tools, you can do it through [this endpoint](/getting-started/api-reference-openapi#get-v2-account). Please note that the credit system used by the API is independent of the Pro subscription that gives access to the Photoroom app on iOS, Android, and the web. *** ## Q: Do you offer Enterprise pricing? A: Yes, for large volumes (from 200K images/year) we do offer Enterprise pricing. For more details, please [contact our sales team](https://www.photoroom.com/contact-sales?utm_source=apidoc\&utm_medium=getting-started-pricing). *** ## **Q: What is the latency to return the processed image?** A: The median latency (number of seconds it will take to remove the background) to return the processed image is 350ms for the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). *** ## Q: Does the API have anti-spam / DDoS protection? Yes, the Photoroom API uses Cloudflare for DDos protection. *** ## **Q: Is there a rate-limiting?** A: The default rate limit is 60 images per minute. When the rate limit has been reached, an error code `429` will be returned. To avoid hitting the rate limit, we recommend that you add logic to your code to either: * send a maximum of 60 API calls per minute * set a 1-second delay between API calls If you need to process a very large amount of images and need a higher rate limit to speed up that process, it is possible for Enterprise plans. If you're interested in a higher rate limit, please [contact our sales team](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Contact Sales *** ## Q: Can I process several images at once, in bulk? A: Yes, it's possible to process several images in bulk. While the Photoroom API only processes one image per call, it's possible to perform several API calls in parallel. The only limit is our rate limiting, which is of 60 images per minute by default (and can be [increased for Enterprise plans](#q-is-there-a-rate-limiting)) *** ## **Q: Are the images sent to the API stored by Photoroom? Can I ask to delete them?** A: Photoroom doesn’t save the images that are processed through the Photoroom API. *** ## **Q: Where are your servers located?** A: Our servers are located in Eastern USA. *** ## **Q: What are the max resolution and size of the image?** A: We recommend limiting images to 25 megapixels for optimal performance. * [**Remove Background API**](/remove-background-api-basic-plan/quickstart-guide)**:** * **Maximum File Size**: 50MB * **Maximum Resolution**: 6,000 pixels on the widest side * [**Image Editing API**](/image-editing-api-plus-plan/quickstart-guide): * **Maximum File Size**: 30MB * **Maximum Resolution**: 5,000 pixels on the widest side * Images with a larger resolution are supported (if they stay below 30MB), but will be resized down to 5,000 pixels on the widest side. {% hint style="warning" %} Please note that large images will result in API calls taking a longer time to complete. If you experience timeouts, please try to increase the default timeout of your networking library. {% endhint %} *** ## **Q: Which image formats are supported?** A: All APIs accept images in PNG, JPEG and WEBP format. Images in HEIC format are supported only by the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). Other formats are not supported. *** ## **Q: Which colorspaces are supported?** A: The API supports images using the sRGB colorspace. If you need to process images using a different colorspace (P3, CMYK, etc.) we recommend that you [contact us](https://photoroom.discourse.group/) beforehand. *** ## **Q: Can I train a machine learning model using images edited with the API or Photoroom?** A: No, according to [our terms](https://www.photoroom.com/legal/terms-and-conditions), you can’t train a machine learning model using the Photoroom API. *** ## **Q: What should the Photoroom logo look like within your app with the API partner plan?** A: Below are a few examples of a well-done partnership on an upload image interface. Typically users benefiting from the background removal must see the Photoroom logo and be able to click on it. From a technical standpoint: 1. Where should you put the logo in your app?\ The best place to show the Photoroom logo is on your upload-images UI if you have one. This way creators and resellers can learn about Photoroom. If you don't have such a UI, you can display the attribution logo next to the images you're showing on your application.
2. Which logo should you use? The Photoroom logo to add is the following one: We offer several versions of the logo (.svg for Android & Web, .pdf for iOS, and .png), a version with no tagline so you can localize "Background Removed by" and a dark version. They are available here: [All Photoroom API attributions version](https://photoroom.notion.site/All-PhotoRoom-API-attributions-version-2-b6c90dad9188427bbe6a44c05a91db1b).\ \ You can add a thin layer with white background and transparency behind our logo, so it works well on all images. 3. Which link should you set? Always wrap those images with a link to: * [https://photoroom.com](https://www.photoroom.com/) for web and email * for iOS apps * for Android apps *** ## **Q: I have another question** A: For a question on pricing, please check our dedicated [pricing FAQ](https://www.photoroom.com/api#faq-block). For any other questions, you can reach out to our engineers on our [API community.](https://photoroom.discourse.group/) 1. If its a technical question, share with us: * A standalone code to reproduce the bug * The original input image you used * The output image returned by Photoroom API * A detailed description or visual example of the expected image you would have liked to get\ We will then investigate the issue and come back to you shortly. 2. If it's a billing related question with sensitive information, use the DM function on our community and start a chat with Photoroom. # Troubleshooting On this page, you will find some common questions or issues you might encounter when integrating the Photoroom API, along with their answer. *** ## Q: Why do I get the error `"Unauthorized"` when calling the API? A: If your call is resulting in this error: ```json {"error":{"message":"Unauthorized"}} ``` Then it's likely that you either forgot to put your apiKey in the headers of your call or that your credit balance has reached zero. You can learn how to get your apiKey [here](/#how-can-i-get-my-api-key) and how to monitor your credit balance [here](/getting-started/frequently-asked-questions#q-how-can-i-monitor-my-credit-balance). *** ## Q: Can I send my image in Base64 format? A: Yes, sending your image in Base64 format is possible for the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). Here's are some sample codes in JavaScript and Python: {% tabs %} {% tab title="JavaScript" %} ```javascript const removeBackground = async (base64Image) => { const options = { method: "POST", headers: { "x-api-key": YOUR_API_KEY, "Content-Type": "application/json", Accept: "application/json", }, body: JSON.stringify({ image_file_b64: base64Image.split(",")[1], }), }; fetch("https://sdk.photoroom.com/v1/segment", options) .then((response) => response.json()) .then((response) => { console.log(response); }) .catch((err) => console.error(err)); }; ``` {% endtab %} {% tab title="Python" %} ```python import requests import json import base64 def encode_image_to_base64(image_path): """Reads an image file and converts it to a base64-encoded string.""" with open(image_path, "rb") as image_file: return base64.b64encode(image_file.read()).decode("utf-8") def remove_background(base64_image, api_key): url = "https://sdk.photoroom.com/v1/segment" headers = { "x-api-key": api_key, "Content-Type": "application/json", "Accept": "application/json", } data = { "image_file_b64": base64_image } try: response = requests.post(url, headers=headers, data=json.dumps(data)) response_data = response.json() print(response_data) except requests.exceptions.RequestException as err: print(f"Error: {err}") # Usage api_key = "YOUR_API_KEY" base64_image = encode_image_to_base64("/path/to/your/image.jpg") remove_background(base64_image, api_key) ``` {% endtab %} {% endtabs %} *** ## Q: When I call the Remove Background API, the result image gets rotated A: An image can be rotated through a value set inside the EXIF metadata of the image. Because the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) doesn’t carry over EXIF metadata into the result image, the rotation will then get lost in the process. The best solution to this problem is to physically perform the rotation by rotating the image itself before making the API call. Here’s an example of how to do it when using the JavaScript library `sharp`: ```javascript async function removeImageBackground (imageBuffer) { // Normalize the image orientation based on its EXIF Orientation tag // Then reset the EXIF Orientation tag to 1 const normalizedImageBuffer = await sharp (imageBuffer) .rotate() // Automatically adjust rotation based on EXIF data .withMetadata({ orientation: 1 }) // Reset EXIF Orientation tag to 1 .toBuffer(); // Convert back to buffer for further processing console. log ('Image orientation normalized to EXIF rotation value 1.'); // Make the API call } ``` {% hint style="info" %} This problem should not happen when using the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). {% endhint %} *** ## Q: I'm using Axios to make the API call, but I can't decode the result image A: Calls to the Photoroom API will return a binary image in the body of the HTTP response. In order to properly decode the image when using Axios to make the API call, you'll need to configure the call with the option `{ responseType: 'arraybuffer' }` : ```javascript const url = /* create the URL for your API call */ const options = { responseType: 'arraybuffer' } const result = await axios.get(url, options) ``` *** ## Q: I'm using `requests` in Python and I get a 500 error A: If you're using the `requests` library in Python to make your API call and you're getting a 500 error, please make sure that you are **not** manually setting the HTTP header `Content-Type: multipart/form-data`. This header is already being automatically added by the `requests` library, so adding it a second time in your code will lead to a malformed request. ```python import os import requests def process_image(input_image_path, output_image_path): try: url = "https://sdk.photoroom.com/v1/segment" with open(input_image_path, 'rb') as image_file: files = { "image_file": image_file } headers = { "Accept": "image/png, application/json", "x-api-key": API_KEY, 'Content-Type': 'multipart/form-data', # 👈 this line need to be removed } response = requests.post(url, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") ``` ## Q: Photoroom API has stopped working/answering A: The Photoroom API is used by the Photoroom iOS, Android, and Web apps. Timeouts are unlikely to happen or would impact our own products in a critical way. If Photoroom API has stopped working on your side, please check the following points: 1. Do you still have credits? Visit your [dashboard](https://app.photoroom.com/api-dashboard) and check your remaining credits, you can buy more credits directly from your dashboard if needed. 2. Is the API returning an error or an erroneous image? Report your technical bug or issue using the procedure explained in the following question. *** ## Q: I have a technical issue/bug with Photoroom API A: We currently don't provide technical support for implementing the API over email. In case of an integration issue or of a bug on Photoroom's side: 1. [Join our online community](https://photoroom.discourse.group/) 2. Share with us: * A standalone code to reproduce the bug * The original input image you used * The output image returned by Photoroom API * A detailed description or visual example of the expected image you would have liked to get We will investigate the issue and come back to you shortly. # Changelog History of the changes made to the Photoroom API Here's a walkthrough of the latest API feature: {% embed url="" %} ### 2026-04-21 #### Updated The feature [AI Shadows](/image-editing-api-plus-plan/ai-shadows) now supports new parameters that give you complete control over the appearance of the shadow:

shadow.mode=ai.auto-with-overrides
shadow.softnessOverride=0.3
shadow.intensityOverride=0.8
shadow.spreadOverride=medium
shadow.directionOverride=behindLeft
shadow.subjectPoseOverride=upright

shadow.mode=ai.auto-with-overrides
shadow.softnessOverride=0.3
shadow.intensityOverride=0.8
shadow.spreadOverride=medium
shadow.directionOverride=behindRight
shadow.subjectPoseOverride=upright

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.softnessOverride=0.3 \ --form shadow.softnessOverride: 0.3 \ --form shadow.intensityOverride: 0.8 \ --form shadow.spreadOverride: medium \ --form shadow.directionOverride: behindLeft \ --form shadow.subjectPoseOverride: upright \ --output result-with-deterministic-shadow.png ``` Try it now! More details about the new parameters are available on [this page](/image-editing-api-plus-plan/ai-shadows). ### 2026-03-23 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports placing clothing onto [Virtual Models](/image-editing-api-plus-plan/virtual-model):
(original image)(edited image)
If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form virtualModel.mode=ai.auto \ --form virtualModel.model.preset.name=avery \ --form virtualModel.scene.preset.name=street \ --form virtualModel.pose=standing \ --output result.png ``` Try it now! More details about this feature are available on [this page](/image-editing-api-plus-plan/virtual-model). #### Updated The features [Flat Lay](/image-editing-api-plus-plan/flat-lay) and [Ghost Mannequin](/image-editing-api-plus-plan/ghost-mannequin) have been moved to their own documentation pages. ### 2026-03-19 #### Updated The features [Edit With AI](/image-editing-api-plus-plan/edit-with-ai), [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier) and [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) now support 2K and 4K resolutions. These resolutions are available only for Enterprise plans: if you're interested to use the 2K or 4K resolutions, please [contact our sales team](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Contact Sales ### 2026-03-16 #### Updated The feature [Create Any Image](/image-editing-api-plus-plan/create-any-image) is no longer in [*Alpha*](#user-content-fn-1)[^1] status. ### 2026-02-27 #### Updated The features [Edit With AI](/image-editing-api-plus-plan/edit-with-ai) and [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier) are no longer in [*Alpha*](#user-content-fn-1)[^1] status. ### 2026-02-26 #### Updated The feature Describe Any Change has been renamed to [Edit With AI](/image-editing-api-plus-plan/edit-with-ai). ### 2026-01-19 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports adding a colored outline around the main subject: | *(original image)* | `outline.color=white` | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | | To add an outline, set the parameter `outline.color` to a solid color value. Here's an example of how to use this new feature: {% code overflow="wrap" %} ```bash curl --request POST \ --url 'https://image-api.photoroom.com/v2/edit' \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form 'imageFile=@"/path/to/image.png"' \ --form 'outline.color="white"' \ --form 'referenceBox="originalImage"' \ --form 'removeBackground="false"' \ --output result.png ``` {% endcode %} More details about this feature are available on [this page](/image-editing-api-plus-plan/subject-outline). ### 2026-01-06 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports automatically editing the input image by providing a textual description of the changes that you want to make. To use this feature, set the parameter `describeAnyChange.mode` to `ai.auto` **and** use the parameter `describeAnyChange.prompt` to describe the changes:
(original image)(edited image)


describeAnyChange.prompt="Change the shoes color to red"


describeAnyChange.prompt="Remove all the objects on the table"


describeAnyChange.prompt="Remove all the people"
Here's an example of how to use this new feature: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form describeAnyChange.mode=ai.auto \ --form describeAnyChange.prompt='Change the shoes color to red' \ --output result.png ``` More details about this feature are available on [this page](/image-editing-api-plus-plan/edit-with-ai). ### 2025-11-06 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports blurring the background of any image: | | | | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *(original image)* | `background.blur.mode=bokeh` | `background.blur.mode=gaussian` | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQb4CVQZhXwIcKlzxQ9Qp%2Fshoes.jpeg?alt=media\&token=5369cf82-c842-4444-9ab7-1e749b0c4742) |
|
| To blur the background, set the parameters `background.blur.mode=bokeh` and `removeBackground=false`. Here's an example of how to use this new feature: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form background.blur.mode=bokeh \ --form removeBackground=false \ --output result.png ``` More details about this feature are available on [this page](/image-editing-api-plus-plan/background-blur). #### Updated The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now offers a new [AI Relight](/image-editing-api-plus-plan/ai-relight) mode with stronger color accuracy. To use this new mode, set the parameter `lighting.mode=ai.preserve-hue-and-saturation`: | *Original* | `lighting.mode=ai.auto` | `lighting.mode=ai.preserve-hue-and-saturation` | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBXwWQt1XsvEOGvTaQe1M%2Fm43233153640_1.jpg?alt=media\&token=9f48c27c-38af-4fd9-8aff-91291373d0f3) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FgvtEHzukKeAYQefnLIif%2Fold.png?alt=media\&token=0fda2e47-127b-4487-a68c-8c95d1151584) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FCCP27LiwsEj16GadhnMQ%2Fnew.png?alt=media\&token=ca4b3063-018e-464c-a5da-acb0edefdc61) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fwp0p30v9CVVbGpBNSC7Q%2Fm42770846513_1.jpg?alt=media\&token=e589891f-fccc-4fe7-a5aa-3180dbae58d2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FoGH7PKtEqmcQ7Q2c3IOI%2Fm42770846513_1.png?alt=media\&token=3d11ecfb-a50a-4f9e-af35-07b21ec7844a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FkgINLXF3qoE2U3HbkV43%2Fm42770846513_1.png?alt=media\&token=fd49f0aa-fc37-4a9d-bcdb-4a5703ad2758) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FcYyU6flKP8ARTJtuadRH%2Fm63703188619_1%20\(1\).jpg?alt=media\&token=8cc24c3c-3b84-4625-8ea0-4fcf471d02b2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FezLGijQb2hihrjasrwTg%2Fm63703188619_1%20\(1\).png?alt=media\&token=a108a7f7-45d6-4e19-8403-6e2cd9dae415) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fmi94UYhBHPbMzhWHdlSq%2Fm63703188619_1%20\(1\).png?alt=media\&token=cc7f28ec-b265-4a8c-84f2-93dd8a59469c) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FdfM0951WkWmBpTskwoIl%2Fm84390327592_1.jpg?alt=media\&token=8919997a-d67c-4d97-8201-31bb6361f8a3) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F6OFjybEH4X3lJJI8kTub%2Fm84390327592_1.png?alt=media\&token=3e0d35b1-8450-45c1-9b7b-15af38680305) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FgKKrdp2hv0BnD6zZPsxJ%2Fm84390327592_1.png?alt=media\&token=c79d4e11-d925-4970-bc43-3ab44ca487af) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUzAdpQlqhyWMfI012OPN%2Fm38165968726_1.jpg?alt=media\&token=c0ac1949-3872-46cd-a423-9db98ade14f7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FncgQDJfvsDRECtXpY6MG%2Fm38165968726_1.png?alt=media\&token=aa437710-07bd-4e39-8b63-2698881e15d5) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FrOiF44wJEgv32PyiXeu4%2Fm38165968726_1.png?alt=media\&token=330d6df5-291d-4105-a71b-dc7e82f58c2d) | Here's an example of how to use this new feature: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form referenceBox=originalImage \ --form maxWidth=2000 \ --form maxHeight=2000 \ --form removeBackground=false \ --form lighting.mode=ai.preserve-hue-and-saturation \ --output with-re-lighting.png ``` ### 2025-05-30 #### Added [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) now supports our new *Studio* model for background generation. This model is better at generating photorealistic images: object shapes are more defined and textures look better. It is also great at generating props such as cutlery or surrounding objects for your scene. While it's slower than our current model, the increase in visual realism and detail make this a worthwhile trade-off for users seeking the highest quality results. Add the `pr-ai-background-model-version: background-studio-beta-2025-03-17` HTTP header to use it, for example: ```bash curl -X POST https://image-api.photoroom.com/v2/edit \ --header 'pr-ai-background-model-version: background-studio-beta-2025-03-17' \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/image.jpg \ --form referenceBox=originalImage \ --form 'background.prompt=On the counter of a rustic, artisanal coffee shop' \ --form background.expandPrompt.mode=ai.never \ --output result.jpg ``` Here's a comparison of the new Studio model and the current model:
### 2025-05-19 Updated The default rate limit was updated from 500 to 60 per minute, for new users only. Existing users keep their current rate limit settings. Reach out to request a rate limit update. ### 2025-02-04 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports exporting images in WebP format. To export a WebP image, set the argument `export.format` with the value `webp`. Here's an example of how to use this new feature: {% code overflow="wrap" %} ```bash curl 'https://image-api.photoroom.com/v2/edit?background.color=FFFFFF&outputSize=1000x1000&padding=0.1&export.format=webp&imageUrl=URL_OF_YOUR_IMAGE' \ --header 'x-api-key: YOUR_API_KEY' \ --output result.jpeg ``` {% endcode %} More details about this feature are available on [this page](/image-editing-api-plus-plan/file-size-resolution-and-format). ### 2024-12-19 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) allows you to control the pixel density of the result image. To control the pixel density, set the argument `export.dpi` to a value between `72` and `1200` (included). More details about this feature are available on [this page](/image-editing-api-plus-plan/pixel-density-dpi). #### Updated The interface of [Text-Guided Segmentation](/image-editing-api-plus-plan/preview-text-guided-segmentation) has been modified: * the property `segmentation.keepSalientObject=true|false` has been removed * it’s been replaced by the new property `segmentation.mode=keepSalientObject|ignoreSalientObject` ### 2024-09-10 #### Updated [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) now improves its text prompt by default. To opt-out, set the argument `background.expandPrompt` to `never`. More details about this feature are available on [this page](https://docs.photoroom.com/getting-started/pages/HApfqZOrLZgScroTLTtk#background.expandprompt). ### 2024-09-02 #### Updated [AI Relighting](/image-editing-api-plus-plan/ai-relight) is no longer limited to a maximum image size of 10MB. ### 2024-08-26 #### Added [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) now supports using both Text and Image prompts at the same time. To use both type of prompts together, set the arguments `background.prompt` and `background.guidance.imageFile` (or `background.guidance.imageUrl`) in your API call:

background.guidance.imageFile=@"/path/to/guidance-image.jpeg"

and

background.prompt="A bottle of perfume 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."

background.guidance.imageFile=@"/path/to/guidance-image.jpeg"

and

background.prompt="the image displays a small bottle with a pink substance on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry."

More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-backgrounds#using-text-and-image-prompts-together). ### 2024-08-23 #### Added [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) now supports automatically improving short prompts. To automatically expand your prompt, set the argument `background.expandPrompt` to `auto`:

background.prompt="on a beach"

background.expandPrompt=never

background.prompt="on a beach"

background.expandPrompt=auto

(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.")

More details about this feature are available on [this page](https://docs.photoroom.com/getting-started/pages/HApfqZOrLZgScroTLTtk#background.expandprompt). #### Updated [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) now uses our most recent model (version 3) by default. If you prefer to keep using our previous model (version 2), you can do it by adding the following header to your API call: `pr-ai-background-model-version: 2`. ### 2024-07-23 #### Experiment We’ve started an A/B test of a new [AI Backgrounds v3 model](/image-editing-api-plus-plan/ai-backgrounds#important-model-selection). The new model should produce better results and is currently being tested on one of our instances. This means that during the day some API calls will use the new model, while others will not. {% hint style="info" %} This only concerns the AI Backgrounds feature, there’s no impact on all the other features. {% endhint %} ### 2024-07-02 #### Added [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) now supports using an image as a prompt. To use an image prompt, set either the argument `background.guidance.imageFile` or `background.guidance.imageUrl`: | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FlR2xKxVU3FOeO9TsBSOO%2Foriginal.jpeg?alt=media\&token=1fa53df3-8c38-4a3a-a7c9-8a59c3a66f8c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FPvUi6y7FqySznoAUf27M%2Finspiration.jpg?alt=media\&token=1080133a-e69d-4917-95cf-fdb06b364f2d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FN9zt58DQJn7NWo1xWk27%2Fresponse-4.png?alt=media\&token=1b9b3b70-dc40-4c8a-a17d-99d986dae65b) | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | o*riginal image* | *guidance image* | *result* | More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-backgrounds#image-prompt). #### Updated * Users will no longer lose remaining images when upgrading to a bigger plan. * The [API Playground](https://www.photoroom.com/api/playground) now uses the [latest AI Background model](/image-editing-api-plus-plan/ai-backgrounds#model-selection). ### 2024-06-12 #### Added * **Use your own background image file**: You can now send your own image file for your backgrounds using `background.imageFile` on the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). #### Updated * **Higher resolution**: Previously, the Image Editing API supported image resolutions up to 2000×2000, resulting in a loss of quality. We have enhanced this capability, now allowing images up to 5000×5000 resolution without any quality loss. (Up to 25 Megapixels) * **Margin and Padding**: The API now supports both percentage string values (e.g., "20%") and pixel string values (e.g., "100px"), in addition to the existing percentage values ranging from 0 to 0.49. * **Zapier integration**: AI expand mode has been added. ### 2024-05-30 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports expanding (or un-cropping) an image. To expand an image, set the argument `expand.mode` to the value `ai.auto`. This enables you, for example, to re-use an existing image but with a different aspect ratio: | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fspe7s1H6t3zi9YYktv7o%2Finput.png?alt=media\&token=da2cf808-1949-4874-9ea2-49e625cd76a9) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FNk3rLrl1InSZ69BTS5bI%2Fai-expand.png?alt=media\&token=a9733a75-4ef3-4b08-a165-e9e834463247) | | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *(original image)* | *(expanded image)* | More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-expand). ### 2024-05-22 #### Added * **Sandbox Mode**: You can now make up to 1,000 free API calls by month using our new sandbox mode (100 max per day). Sandbox mode is meant to be used for testing and prototyping, and will produce an image with a watermark. To use sandbox mode, prepend `sandbox_` to your API key. (Example: `sandbox_xxxxxxxxxxxxxxxxxxx`) {% hint style="danger" %} Sandbox mode currently only works with the [Image Editing API](broken://pages/sYF796CaXvK7stuRaSNG) (`v2/edit`) {% endhint %} * **Reworked Zapier Integration**: We've completely reworked our [Zapier integration](/integrations/how-to-process-images-from-google-drive-using-zapier) for a more seamless and efficient experience. This update adds support of the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) and improves the reliability of workflows. * **New AI Backgrounds Model**: Switch to the new [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) model by adding the following HTTP header in your request when calling the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide):
```http pr-ai-background-model-version=3 ``` | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FigT7dlN9cmlpBHRfeJCr%2Fold-model.png?alt=media\&token=fa81d8e5-00d2-47b3-ace7-b713955f41f2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F3wuEmxd58RxHaWLrxFIL%2Fnew-model.png?alt=media\&token=e905f558-5c46-4e2f-9316-a76af7eb5495) | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *current model* | *new model* | #### Updated * **Improved `imageUrl` Parsing**: Improved the parsing of `imageUrl` when using GET on the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) (`v2/edit)`, allowing for a wider range of URLs to be handled correctly. * **Improved Cutout Results**: Enhanced the cutout results for PNG images with significant transparency, providing a cleaner and more accurate outcome. ### 2024-04-03 #### Image Editing API is out of Beta ![:tada:](https://a.slack-edge.com/production-standard-emoji-assets/14.0/apple-medium/1f389.png) We've made an update to the base URL of the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). The previous base URL `beta-sdk.photoroom.com` has been updated to `image-api.photoroom.com`. This change aims to enhance the clarity and consistency of our image API services. * **Old base URL:** `beta-sdk.photoroom.com` * **New base URL:** `image-api.photoroom.com` **Required Actions** * **Update the base URL:** Please update all instances of the old base URL in your projects to the new base URL: `image-api.photoroom.com`. * **Test and Validate:** After updating, make sure to test your integrations to confirm everything is working as expected with the new base URL. * **Deadline:** The transition should be completed by the 5th of July 2024, after which the old base URL will no longer be operational. ### 2024-04-02 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) can now automatically remove text from an image. To remove text from the input image, set the argument `textRemoval.mode` with one of the following values: * `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, discounts, etc. * `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. * `ai.all`: all text (natural and artificial) will be automatically removed.
(original image)
ai.artificial
ai.natural
ai.all
More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-text-removal). ### 2024-03-14 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now allows you to manually control the horizontal and/or vertical alignments of the subject. Manually controlling the alignment is very useful when you want to position subjects with different aspect ratios is a harmonious way, like here where the subjects have been vertically aligned at the bottom:
More details about manually controlling the subject alignments are available on [this page](/image-editing-api-plus-plan/positioning#horizontal-and-vertical-alignments). ### 2024-03-04 #### Updated The [API Dashboard](https://app.photoroom.com/api-dashboard) in the Photoroom Web App has been moved. The API Dashboard used to be accessible from *Your personal space*, and it has now been moved to *My Photoroom API team*. To switch to *My Photoroom API team*, use the *Team Switcher* that's on the top left of the app:
Moving the API Dashboard to *My Photoroom API team* makes it possible for you to share access to your API Dashboard with your teammates. {% hint style="info" %} Please note that this change has no effect on existing API Keys. Existing API Keys are still valid and you don't need to make any change to your code. {% endhint %} ### 2024-02-22 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports exporting images in JPEG format. To export a JPEG image, set the argument `export.format` with the value `jpeg`. Here's an example of how to use this new feature: {% code overflow="wrap" %} ```bash curl 'https://image-api.photoroom.com/v2/edit?background.color=FFFFFF&outputSize=1000x1000&padding=0.1&export.format=jpeg&imageUrl=URL_OF_YOUR_IMAGE' \ --header 'x-api-key: YOUR_API_KEY' \ --output result.jpeg ``` {% endcode %} More details about this feature are available on [this page](/image-editing-api-plus-plan/file-size-resolution-and-format). ### 2024-02-01 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) now supports a `POST` route, which allows you to directly upload an image file rather than sending the URL of an image. Here's an example how to call this new route: ```sh curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'Accept: image/png, application/json' \ --header 'Content-Type: multipart/form-data' \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/absolute/path/to/image.jpg \ --form shadow.mode=ai.soft \ --form background.color=FFFFFF \ --form padding=0.1 \ --output res.png ``` Detailed specifications are available in the [API reference](https://www.photoroom.com/api/docs/reference/bdfb80d8bcd00-beta-edit-image-v2). #### Updated The “Edit Image API” has been renamed to “Image Editing API”. Please note that this is only a change of the commercial name: all of the technical identifiers (HTTP endpoint, argument names, etc.) are still the same. ### 2024-01-05 #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) can now generate realistic shadows. To add a realistic shadow, set the argument `shadow.mode` with one of the following values:
(original image)ai.softai.hardai.floating
More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-shadows). #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) can now generate realistic backgrounds.
To use this feature set the argument `background.prompt`. More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-backgrounds). #### Added The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) can now re-light the subject of an image. To re-light the subject of an image, set the argument `lighting.mode=ai.auto`. | *Original* | *Re-lighted* | | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FNkhQrGGLHn7fbFUuhgox%2Foverexposed-1.jpg?alt=media\&token=7cb6f836-8e3d-4e5a-a1fb-a74833fca0fa) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fzv02r2UtPi0SktXoNrxb%2Foverexposed-1.png?alt=media\&token=6d223863-2678-4b2c-b7bd-baf2c58cd8ef) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FMkGu8Kmh2eks1Kx0b2oW%2Funderexposed-1.jpg?alt=media\&token=60a1c5f1-08d7-4931-b5bc-93d0b30e45be) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F6l6TBwPfrys7a2hX31Oe%2Funderexposed-1.png?alt=media\&token=8994905f-9f5d-4656-b6c9-b8e26ee63de3) | More details about this feature are available on [this page](/image-editing-api-plus-plan/ai-relight). ### 2023-12-11 #### Added The [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) now returns an uncertainty score. The score reflects the confidence of the model in the cutout and is returned through the HTTP header `x-uncertainty-score` of the response. More details about the uncertainty score are available on [this page](/remove-background-api-basic-plan/uncertainty-score). ### 2023-11-30 #### Added The [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) now supports WebP format for the result image. To output a WebP image, set the argument `format` to `webp`. Detailed specifications and usage instructions are available on our [API reference](https://www.photoroom.com/api/docs/reference/71f4c26e59e43-remove-background). ### 2023-10-16 #### Added New Endpoint - Edit Image v2: We have introduced a new beta endpoint `GET /v2/edit` that enables you to apply complex edits to an image. This new endpoint comes with an interactive playground that lets you configure your API call and preview the result in real time: ![](https://a.storyblok.com/f/191576/800x433/1366e24029/edit-image-api-playground-demo.gif) Details about this new API are available in our [documentation](broken://pages/sYF796CaXvK7stuRaSNG) and [API reference](https://www.photoroom.com/api/docs/reference/87e1c15260b1f-beta-edit-image-v2). ### 2023-06-26 #### Added New Endpoint - Account Details: We have introduced a new endpoint `GET /v1/account` which provides detailed information about the current state of your account. This includes your current credit consumption and the total monthly credits available for your subscription. This new endpoint is aimed at giving users a better understanding of their account status and managing their credit usage effectively. The response from the endpoint will be in JSON format, as shown in the example below: ```json { "credits": { "available": 9912, "subscription": 10000 } } ``` In this sample, `available` denotes the remaining credits for the current month and `subscription` indicates the total monthly credits associated with the user's subscription. Detailed specifications and usage instructions are available on our [API reference](https://www.photoroom.com/api/docs/reference/611c03dbcec67-account-details). ### 2023-06-05 #### Added Image Upload Enhancement: We have made improvements to our API's image upload functionality to offer a more flexible experience. In addition to passing an `imageUrl` as a URL parameter, users are now also able to send the image binary directly in a `POST` request using the new `imageFile` field. This added capability simplifies the process of uploading images, especially for those who have the images available locally and not hosted online. The previous method using `imageUrl` remains functional and backward compatibility is maintained. Users are free to choose the method most convenient to their needs. Please refer to our updated documentation for detailed instructions on using the new `imageFile` field: * [Edit Image API reference documentation](https://www.photoroom.com/api/docs/reference/2fffa859aa344-beta-edit-image-v1) * [Generate Background API reference documentation](https://www.photoroom.com/api/docs/reference/24964ec492226-beta-generate-background) ### 2023-06-04 #### Added Add a Changelog page on the documentation [^1]: Features in Alpha status might be deprecated with two week warning. # What we're working on Photoroom's goal is to deliver the AI image editing solution that offers the strongest possible level of product fidelity. To achieve this goal, we have a dedicated in-house Machine Learning team that actively conducts research to determine what type of AI models are able to edit images with minimal risk of hallucinations. Right now this team is exploring a new idea: training a model that operates directly in *pixel space*. ### What does *pixel space* mean? Current state-of-the-art AI image editing models don't operate directly on the pixels of the image. Instead they operate on a learned representation of the image that lives in what is called a *latent space*. It's a fairly technical topic but here's the gist of it: First, a separate model compresses your image into a much smaller grid of numbers (called *tokens*). Think of it like a zip file — smaller, but with all the important information preserved. The editing model then uses that compressed version as a reference when performing the editing. Finally, another model decompresses it back into a full image. But here's the important tradeoff: that compressed format is an **interpretation** of your image, not a perfect copy. When the model edits it and decompresses it back, it's essentially reconstructing the image from an approximation, which means it can sometimes fill in details that weren't there originally. This is where hallucinations come from: the model confuses what was in the image with what it *expects* to be there.
To avoid this issue, the team at Machine Learning team at Photoroom is currently working on training a model that operates directly in the *pixel space*, without using any intermediary representation of the image. If you're interested to learn more about this process, here's an article that explains how the training works: {% embed url="" %} You can also try an early version of the model [here](https://huggingface.co/spaces/Photoroom/PRX-Pixel) and even download its weights [here](https://huggingface.co/Photoroom/prxpixel-t2i). # API Reference (OpenAPI) ## Image Editing v2 (Plus plan) > 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.\*), Ironing (ironing.mode), Virtual Model (virtualModel.\*), AI expand (expand.mode), AI uncrop (uncrop.mode), AI upscale (upscale.mode), and positioning/resizing (padding, margin, outputSize).\ > \ > Parameters 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, ironing.\* for wrinkle removal, 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.\ > \ > Edits can be combined in a single call.\ > \ > 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: > \ > For the simplest integration (recommended for no-code tools like Lovable), use this GET endpoint with imageUrl — no file upload handling required.\ > \ > Example of a request: GET with header x-api-key: YOUR\_API\_KEY\ > \ > The response is the edited image as binary data (image/png by default). To change format, set export.format to jpeg, webp or avif.\ > \ > Full documentation: > \ > Feature documentation:\ > \- \[HD Background Removal]\( > \- \[Positioning (padding, margin, scaling)]\( > \- \[Output Size]\( > \- \[Static Background]\( > \- \[Background Blur]\( > \- \[Subject Outline]\( > \- \[AI Shadows]\( > \- \[AI Backgrounds]\( > \- \[AI Relight]\( > \- \[AI Text Removal]\( > \- \[AI Expand]\( > \- \[AI Uncrop]\( > \- \[AI Beautifier]\( > \- \[Flat Lay]\( > \- \[Ghost Mannequin]\( > \- \[Virtual Model]\( > \- \[AI Upscale]\( > \- \[Describe Any Change]\( > \- \[Create Any Image]\( > \- \[Text-Guided Segmentation]\( > \- \[Sandbox Mode (free testing)]\() ```json {"openapi":"3.1.0","info":{"title":"Photoroom API","version":"1.0.0"},"servers":[{"url":"https://image-api.photoroom.com","description":"Production server (Plus plan)"}],"security":[{}],"paths":{"/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.*), Ironing (ironing.mode), 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, ironing.* for wrinkle removal, 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 — 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, webp or avif.\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)","parameters":[{"name":"background.blur.mode","in":"query","description":"Type of blur to apply to the background.\n- `gaussian`: Applies a gaussian blur to the background.\n- `bokeh`: Applies a bokeh blur to the background.","schema":{"enum":["gaussian","bokeh"],"type":"string"}},{"name":"background.blur.radius","in":"query","description":"Radius of the blur effect. Higher values mean the result will be blurrier.\n\nMinimum: 0, Maximum: 0.05","schema":{"default":0.01,"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`)\n\nWhen `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","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.\n\n`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.\n\nExample: 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.\"`\n\n(Note: `background.expandPrompt.mode` only affects `background.prompt`)","enum":["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\n\nCan't be provided if `removeBackground` is set to `false`\n\nThe 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.\n\nCan't be provided if `removeBackground` is set to `false`\n\nThe maximum size of the image is 30MB.","schema":{"type":"string"}},{"name":"background.guidance.scale","in":"query","description":"How closely the generated background will be matching the guiding image, between 0 and 1.\n\nA 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.\n\n(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,"maximum":1,"type":"number"}},{"name":"background.imageUrl","in":"query","description":"URL of the image to use as a background.\n\nCan't be provided if `removeBackground` is set to `false`\n\nThe maximum size of the image is 30MB.\n\nIf `background.imageUrl` is provided, neither `background.imageFile` nor `background.prompt` can be provided, and vice versa.","schema":{"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`\n\nA 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":{"type":"string"}},{"name":"background.prompt","in":"query","description":"Prompt to use for guiding the background generation process.\n\nTips 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).\n\nIf `background.prompt` is provided, neither `background.imageUrl` nor `background.imageFile` can be provided, and vice versa.","schema":{"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\n\nCan only be provided if `background.imageUrl` or `background.imageFile` is provided","schema":{"default":"fill","enum":["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":{"type":"number"}},{"name":"beautify.mode","in":"query","description":"If enabled, the input image will be beautified (imageFile or imageUrl).\n\nThis is intended to enhance product images by automatically improving the aesthetics of the image, such as the lighting, background, and overall appearance.\n\nIf set to `ai.auto`, the input image will be beautified to match the aesthetic of a packshot product image.\n\nIf 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.\n\nIf set to `ai.car`, the input image will be beautified in a way that's specific to car images, such as removing reflections.\n\nImportant:\n- the beautifier will not preserve the original background: we recommend using this option along with `removeBackground` set to `true`\n- 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"],"type":"string"}},{"name":"beautify.onSubjectMismatch","in":"query","description":"Controls what happens when the image doesn't match the subject expected by `beautify.mode`. The subject check is only available for `beautify.mode` `ai.food`.\n\nIf set to `error`, the request is rejected with HTTP 400: for `ai.food`, when the provided image is not detected as food (before any processing happens) — use this to fail fast instead of beautifying a non-food image; for any other mode, because the check is not supported there.\n\nIf set to `ignore` (the default), no subject check is performed and the image is beautified as-is.","schema":{"enum":["ignore","error"],"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":{"type":"number"}},{"name":"colorSpace","in":"query","description":"Controls the colour space of the output image.\n\n- `sRGB` (default): the output is encoded in sRGB (current behaviour).\n- `original`: the input's embedded ICC profile is preserved in the output. Only valid when the request is a background removal with PNG output, optionally positioned relative to the original image box: `referenceBox: \"originalImage\"` combined with `padding` (and its side-specific variants) and/or an explicit `outputSize` (\"widthxheight\"). Note that a non-zero padding or a size-changing outputSize resamples the pixels (never a colour conversion — the ICC profile and gamut are untouched). Combining `original` with any other operation (background, shadow, other geometry changes, non-PNG export, `export.dpi`, `keepExistingAlphaChannel: \"auto\"`, EXIF-subset `preserveMetadata` modes, ...) returns a 400 error naming the conflicting parameter.","schema":{"default":"sRGB","enum":["original","sRGB"],"type":"string"}},{"name":"describeAnyChange.mode","in":"query","description":"(DEPRECATED) Use `editWithAI.mode` instead.\n\nDescribe any change mode to use on the main image used by the API.\n\nCurrently, only `ai.auto` is supported.","schema":{"const":"ai.auto","type":"string"}},{"name":"describeAnyChange.prompt","in":"query","description":"(DEPRECATED) Use `editWithAI.prompt` instead.\n\nThe natural language prompt describing the change to apply to the image.","schema":{"minLength":1,"type":"string"}},{"name":"describeAnyChange.seed","in":"query","description":"(DEPRECATED) Use `editWithAI.seed` instead.\n\nSeed used for the generation. Can be used to get similar looking results for the same prompt.","schema":{"type":"number"}},{"name":"editWithAI.additionalImages.{key}.imageUrl","in":"query","description":"URL of an additional reference image.","schema":{"type":"string"}},{"name":"editWithAI.mode","in":"query","description":"Edit with AI mode to use on the main image used by the API.\n\nCurrently, only `ai.auto` is supported.","schema":{"const":"ai.auto","type":"string"}},{"name":"editWithAI.prompt","in":"query","description":"The natural language prompt describing the change to apply to the image.","schema":{"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":{"type":"number"}},{"name":"expand.mode","in":"query","description":"Expand mode to use on the main image used by the API.\n\nIf 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)\n\nExpand will rely on output size, subject position, and fitting mode.","schema":{"const":"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":{"type":"number"}},{"name":"export.dpi","in":"query","description":"The pixel density of the result image.\n\nPixel density can be set to any value between 72 and 1200 dpi.","schema":{"maximum":1200,"minimum":72,"type":"number"}},{"name":"export.format","in":"query","description":"The format of the result image.\n\nDefault value is \"png\".\n\nJpeg exports with a quality of 80, WebP and AVIF export with a quality of 90.","schema":{"default":"png","enum":["png","jpeg","jpg","webp","avif"],"type":"string"}},{"name":"flatLay.mode","in":"query","description":"Must be set to `ai.auto` to enable flat lay generation.","schema":{"const":"ai.auto","type":"string"}},{"name":"flatLay.prompt","in":"query","description":"Optional text prompt to guide the generation style.","schema":{"type":"string"}},{"name":"flatLay.size","in":"query","description":"The output size of the generated image.","schema":{"default":"SQUARE_HD","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","type":"string"}},{"name":"ghostMannequin.prompt","in":"query","description":"Optional text prompt to guide the generation style.","schema":{"type":"string"}},{"name":"ghostMannequin.size","in":"query","description":"The output size of the generated image.","schema":{"default":"SQUARE_HD","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.\n\nSpecifying a custom horizontal alignment will implicitly set `ignorePaddingAndSnapOnCroppedSides` to `false` for the horizontal direction.","schema":{"enum":["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)\n\nCan't be provided if `removeBackground` is set to `false`\n\n(See positioning section of the documentation for more information)","schema":{"default":true,"type":"boolean"}},{"name":"imageFromPrompt.prompt","in":"query","description":"The prompt to use for generating the image.","schema":{"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":{"type":"number"}},{"name":"imageFromPrompt.size","in":"query","description":"Supported sizes for AI image generation","schema":{"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.\n\nThe maximum size of the image is 30MB.\n\nIf you want to directly upload an image file, please instead use the POST endpoint with the argument `imageFile`.","schema":{"type":"string"}},{"name":"ironing.mode","in":"query","description":"Must be set to `ai.auto` to enable ironing.","schema":{"const":"ai.auto","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"],"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.\n\nThe maximum size of the image is 30MB.\n\nIf you want to send the URL of an image, please instead use the GET endpoint with the argument `imageUrl`.","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.","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.","type":"number"},"size":{"description":"Supported sizes for AI image generation","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.\n\nThe maximum size of the image is 30MB.\n\nIf you want to directly upload an image file, please instead use the POST endpoint with the argument `imageFile`.","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.","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.","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.\n\nIf set to `ai.auto`, the lighting will be automatically adjusted\n\nIf 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\n\nIf set to `ai.optimize-portrait`, the lighting will be adjusted using a model optimized for portrait subjects","schema":{"enum":["ai.auto","ai.preserve-hue-and-saturation","ai.optimize-portrait"],"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.\n\nTips to assist with positioning are available [in our documentation](https://docs.photoroom.com/image-editing-api-plus-plan/positioning).","schema":{"default":0,"type":["number","string"]}},{"name":"marginBottom","in":"query","description":"Bottom Margin, overrides general margin on the bottom side. Accepts the same formats as `margin`.","schema":{"type":["number","string"]}},{"name":"marginLeft","in":"query","description":"Left Margin, overrides general margin on the left side. Accepts the same formats as `margin`.","schema":{"type":["number","string"]}},{"name":"marginRight","in":"query","description":"Right Margin, overrides general margin on the right side. Accepts the same formats as `margin`.","schema":{"type":["number","string"]}},{"name":"marginTop","in":"query","description":"Top Margin, overrides general margin on the top side. Accepts the same formats as `margin`.","schema":{"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":{"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":{"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.\n\nMinimum: 0, Maximum: 0.025","schema":{"default":0,"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":{"type":"string"}},{"name":"outline.width","in":"query","description":"Width of the outline relative to the image size. Suggested values:\n- 0.01-0.02: Subtle/thin outline\n- 0.03-0.05: Standard/medium outline (default: 0.03)\n- 0.06-0.1: Bold/thick outline The value represents a ratio where 0.1 (10%) is the maximum thickness.\n\nMinimum: 0, Maximum: 0.1","schema":{"default":0.03,"maximum":0.1,"minimum":0,"type":"number"}},{"name":"outputSize","in":"query","description":"Output size of the image. In the form of either:\n- `auto` to keep the template dimensions when templateId is defined, or behave like `originalImage` when templateId isn't defined (default)\n- `widthxheight` for a custom size (example: `200x400`)\n- `originalImage` to keep the original image dimensions\n- `croppedSubject` to use the size of the foreground dimensions after cropping around it","schema":{"default":"auto","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.\n\nTips to assist with positioning are available [in our documentation](https://docs.photoroom.com/image-editing-api-plus-plan/positioning).","schema":{"default":0,"type":["number","string"]}},{"name":"paddingBottom","in":"query","description":"Bottom padding, overrides general padding on the bottom side. Accepts the same formats as `padding`.","schema":{"type":["number","string"]}},{"name":"paddingLeft","in":"query","description":"Left padding, overrides general padding on the left side. Accepts the same formats as `padding`.","schema":{"type":["number","string"]}},{"name":"paddingRight","in":"query","description":"Right padding, overrides general padding on the right side. Accepts the same formats as `padding`.","schema":{"type":["number","string"]}},{"name":"paddingTop","in":"query","description":"Top padding, overrides general padding on the top side. Accepts the same formats as `padding`.","schema":{"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** — 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"],"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.\n\nIt 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.\n\nMost use cases don't require this option. It is useful if you'd like to maintain subject positioning in the original image.\n\nCan't be provided if `removeBackground` is set to `false`\n\n(See positioning section of the documentation for more information)","schema":{"default":"subjectBox","enum":["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,"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\n\nCan only be provided if `imageUrl` or `imageFile` is provided","schema":{"default":"fit","enum":["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":{"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":{"type":"string"}},{"name":"shadow.directionOverride","in":"query","description":"Override for the direction of the shadow.\n\nCan be provided either as an angle in degrees or as one of the following presets:\n- `behind` = 0\n- `behindLeft` = 45\n- `left` = 90\n- `frontLeft` = 135\n- `front` = 180\n- `frontRight` = 225\n- `right` = 270\n- `behindRight` = 315\n\nWhen 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.\n\nThis 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"}]}},{"name":"shadow.intensityOverride","in":"query","description":"Override for the intensity of the shadow.\n\n0 means a very faint shadow, 1 means a very dark shadow.\n\nThis option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.","schema":{"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"],"type":"string"}},{"name":"shadow.softnessOverride","in":"query","description":"Override for the softness of the shadow.\n\n0 means a very hard shadow, 1 means a very soft shadow.\n\nThis option is only supported by the `2026-04-15` AI Shadows model. It requires setting `shadow.mode` to `ai.auto-with-overrides`.","schema":{"maximum":1,"minimum":0,"type":"number"}},{"name":"shadow.spreadOverride","in":"query","description":"Override for the spread of the shadow.\n\nCan be provided either as an angle in degrees or as one of the following presets:\n- `short` = 10\n- `medium` = 45\n- `long` = 90\n\nWhen using degrees, 0 means a very short shadow and 90 means a very long shadow.\n\nThis 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"}]}},{"name":"shadow.subjectPoseOverride","in":"query","description":"Override for the pose of the subject.\n\nCan be provided either as an angle in degrees or as one of the following presets:\n- `flatlay` = 0\n- `upright` = 90\n\nWhen using degrees, 0 means the subject is laying flat and 90 means the subject is placed upright.\n\nThis 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"}]}},{"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.\n\nIf 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.\n\nIf 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.\n\nIf set to `ai.all`, all text (natural and artificial) will be automatically removed.","schema":{"enum":["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.\n\nCurrently, only `ai.auto` is supported. With `ai.auto`, the subject will be automatically detected and uncropped.","schema":{"const":"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":{"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.\n\n`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"],"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.\n\nIf enabled, the input image will be upscaled (imageFile or imageUrl)\n\nInput limits depend on the model selected for AI Upscale. With the default model:\n- `ai.fast`: maximum 1,000,000 input pixels\n- `ai.slow`: maximum 262,144 input pixels\n\nThe 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.\n\nai.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"],"type":"string"}},{"name":"verticalAlignment","in":"query","description":"[Advanced] Defines the vertical alignment of the cutout subject within its bounding box.\n\nSpecifying a custom vertical alignment will implicitly set `ignorePaddingAndSnapOnCroppedSides` to `false` for the vertical direction.","schema":{"enum":["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.","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","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"],"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.","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"],"type":"string"}},{"name":"virtualModel.prompt","in":"query","description":"Optional text prompt to guide the generation style.","schema":{"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"],"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"],"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.","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","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":{"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"}}}}}}}},"components":{"schemas":{"image-response":{"type":"string","title":"Resulting image","description":"The resulting image after rendering","format":"binary"},"edit-image-bad-request":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"The message describing the error","title":"Message"}},"required":["message"]}},"required":["error"],"title":"Invalid value"},"payment-error":{"type":"object","properties":{"error":{"type":"object","properties":{"detail":{"type":"string","description":"The details of the error","title":"Details"}},"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"}},"required":["message"]}},"required":["error"],"title":"Unknown Error"}}}} ``` ## Image Editing v2 (Plus plan) > 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.\*), Ironing (ironing.mode), Virtual Model (virtualModel.\*), AI expand (expand.mode), AI uncrop (uncrop.mode), AI upscale (upscale.mode), and positioning/resizing (padding, margin, outputSize).\ > \ > Parameters 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, ironing.\* for wrinkle removal, 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.\ > \ > Edits can be combined in a single call.\ > \ > It 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: > \ > If you only have a URL for your image (not a local file), use the GET endpoint instead — it is simpler to integrate. Use this POST endpoint when you need to upload image files directly as multipart/form-data.\ > \ > For 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.\ > \ > Full documentation: > \ > Feature documentation:\ > \- \[HD Background Removal]\( > \- \[Positioning (padding, margin, scaling)]\( > \- \[Output Size]\( > \- \[Static Background]\( > \- \[Background Blur]\( > \- \[Subject Outline]\( > \- \[AI Shadows]\( > \- \[AI Backgrounds]\( > \- \[AI Relight]\( > \- \[AI Text Removal]\( > \- \[AI Expand]\( > \- \[AI Uncrop]\( > \- \[AI Beautifier]\( > \- \[Flat Lay]\( > \- \[Ghost Mannequin]\( > \- \[Virtual Model]\( > \- \[AI Upscale]\( > \- \[Describe Any Change]\( > \- \[Create Any Image]\( > \- \[Text-Guided Segmentation]\( > \- \[Sandbox Mode (free testing)]\() ```json {"openapi":"3.1.0","info":{"title":"Photoroom API","version":"1.0.0"},"servers":[{"url":"https://image-api.photoroom.com","description":"Production server (Plus plan)"}],"security":[{}],"paths":{"/v2/edit":{"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.*), Ironing (ironing.mode), 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, ironing.* for wrinkle removal, 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 — 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)","requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"background.blur.mode":{"type":"string","description":"Type of blur to apply to the background.\n- `gaussian`: Applies a gaussian blur to the background.\n- `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.\n\nMinimum: 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`)\n\nWhen `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.\n\n`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\n\nCan't be provided if `removeBackground` is set to `false`\n\nThe 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.\n\nA 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.\n\n(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\n\nCan't be provided if `removeBackground` is set to `false`\n\nThe maximum size of the image is 30MB.\n\nIf `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`\n\nA 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.\n\nTips 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).\n\nIf `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\n\nCan 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).\n\nThis is intended to enhance product images by automatically improving the aesthetics of the image, such as the lighting, background, and overall appearance.\n\nIf set to `ai.auto`, the input image will be beautified to match the aesthetic of a packshot product image.\n\nIf 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.\n\nIf set to `ai.car`, the input image will be beautified in a way that's specific to car images, such as removing reflections.\n\nImportant:\n- the beautifier will not preserve the original background: we recommend using this option along with `removeBackground` set to `true`\n- 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.onSubjectMismatch":{"type":"string","description":"Controls what happens when the image doesn't match the subject expected by `beautify.mode`. The subject check is only available for `beautify.mode` `ai.food`.\n\nIf set to `error`, the request is rejected with HTTP 400: for `ai.food`, when the provided image is not detected as food (before any processing happens) — use this to fail fast instead of beautifying a non-food image; for any other mode, because the check is not supported there.\n\nIf set to `ignore` (the default), no subject check is performed and the image is beautified as-is."},"beautify.seed":{"type":"number","description":"Seed used to run the subject beautifier. Can be used to get similar looking results for the same subject."},"colorSpace":{"type":"string","description":"Controls the colour space of the output image.\n\n- `sRGB` (default): the output is encoded in sRGB (current behaviour).\n- `original`: the input's embedded ICC profile is preserved in the output. Only valid when the request is a background removal with PNG output, optionally positioned relative to the original image box: `referenceBox: \"originalImage\"` combined with `padding` (and its side-specific variants) and/or an explicit `outputSize` (\"widthxheight\"). Note that a non-zero padding or a size-changing outputSize resamples the pixels (never a colour conversion — the ICC profile and gamut are untouched). Combining `original` with any other operation (background, shadow, other geometry changes, non-PNG export, `export.dpi`, `keepExistingAlphaChannel: \"auto\"`, EXIF-subset `preserveMetadata` modes, ...) returns a 400 error naming the conflicting parameter."},"describeAnyChange.mode":{"type":"string","description":"(DEPRECATED) Use `editWithAI.mode` instead.\n\nDescribe any change mode to use on the main image used by the API.\n\nCurrently, only `ai.auto` is supported."},"describeAnyChange.prompt":{"type":"string","description":"(DEPRECATED) Use `editWithAI.prompt` instead.\n\nThe natural language prompt describing the change to apply to the image."},"describeAnyChange.seed":{"type":"number","description":"(DEPRECATED) Use `editWithAI.seed` instead.\n\nSeed 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.\n\nCurrently, 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.\n\nIf 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)\n\nExpand 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.\n\nPixel density can be set to any value between 72 and 1200 dpi."},"export.format":{"type":"string","description":"The format of the result image.\n\nDefault value is \"png\".\n\nJpeg exports with a quality of 80, WebP and AVIF export 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.\n\nSpecifying 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)\n\nCan't be provided if `removeBackground` is set to `false`\n\n(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.\n\nThe maximum size of the image is 30MB.\n\nIf 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"},"ironing.mode":{"type":"string","description":"Must be set to `ai.auto` to enable ironing."},"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.\n\nIf set to `ai.auto`, the lighting will be automatically adjusted\n\nIf 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\n\nIf set to `ai.optimize-portrait`, the lighting will be adjusted using a model optimized for portrait subjects"},"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.\n\nTips 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.\n\nMinimum: 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:\n- 0.01-0.02: Subtle/thin outline\n- 0.03-0.05: Standard/medium outline (default: 0.03)\n- 0.06-0.1: Bold/thick outline The value represents a ratio where 0.1 (10%) is the maximum thickness.\n\nMinimum: 0, Maximum: 0.1"},"outputSize":{"type":"string","description":"Output size of the image. In the form of either:\n- `auto` to keep the template dimensions when templateId is defined, or behave like `originalImage` when templateId isn't defined (default)\n- `widthxheight` for a custom size (example: `200x400`)\n- `originalImage` to keep the original image dimensions\n- `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.\n\nTips 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** — 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.\n\nIt 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.\n\nMost use cases don't require this option. It is useful if you'd like to maintain subject positioning in the original image.\n\nCan't be provided if `removeBackground` is set to `false`\n\n(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\n\nCan 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.\n\nCan be provided either as an angle in degrees or as one of the following presets:\n- `behind` = 0\n- `behindLeft` = 45\n- `left` = 90\n- `frontLeft` = 135\n- `front` = 180\n- `frontRight` = 225\n- `right` = 270\n- `behindRight` = 315\n\nWhen 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.\n\nThis 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.\n\n0 means a very faint shadow, 1 means a very dark shadow.\n\nThis 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.\n\n0 means a very hard shadow, 1 means a very soft shadow.\n\nThis 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.\n\nCan be provided either as an angle in degrees or as one of the following presets:\n- `short` = 10\n- `medium` = 45\n- `long` = 90\n\nWhen using degrees, 0 means a very short shadow and 90 means a very long shadow.\n\nThis 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.\n\nCan be provided either as an angle in degrees or as one of the following presets:\n- `flatlay` = 0\n- `upright` = 90\n\nWhen using degrees, 0 means the subject is laying flat and 90 means the subject is placed upright.\n\nThis 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.\n\nIf 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.\n\nIf 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.\n\nIf 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.\n\nCurrently, 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.\n\n`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.\n\nIf enabled, the input image will be upscaled (imageFile or imageUrl)\n\nInput limits depend on the model selected for AI Upscale. With the default model:\n- `ai.fast`: maximum 1,000,000 input pixels\n- `ai.slow`: maximum 262,144 input pixels\n\nThe 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.\n\nai.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.\n\nSpecifying 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":{"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"}}}}}}}},"components":{"schemas":{"image-response":{"type":"string","title":"Resulting image","description":"The resulting image after rendering","format":"binary"},"edit-image-bad-request":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"The message describing the error","title":"Message"}},"required":["message"]}},"required":["error"],"title":"Invalid value"},"payment-error":{"type":"object","properties":{"error":{"type":"object","properties":{"detail":{"type":"string","description":"The details of the error","title":"Details"}},"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"}},"required":["message"]}},"required":["error"],"title":"Unknown Error"}}}} ``` ## Remove Background (Basic plan) > Remove background from an image ```json {"openapi":"3.1.0","info":{"title":"Photoroom API","version":"1.0.0"},"servers":[{"url":"https://sdk.photoroom.com","description":"Production server (Basic plan)"}],"security":[{}],"paths":{"/v1/segment":{"post":{"operationId":"remove-background","summary":"Remove Background (Basic plan)","description":"Remove background from an image","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/remove-background-post-params"}}}},"responses":{"200":{"description":"OK","headers":{},"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"},"status_code":{"type":"number","description":"The status code of the error","title":"Status Code"},"type":{"type":"string","description":"The type of the error","title":"Type"}},"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"},"status_code":{"type":"number","description":"The status code of the error","title":"Status Code"},"type":{"type":"string","description":"The type of the error","title":"Type"}},"required":["detail","status_code","type"],"title":"Field Missing Error"}}}},"403":{"description":"Forbidden"}}}}},"components":{"schemas":{"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"}}}} ``` ## Account Details v2 > Get current account details, including remaining image edits and monthly quota ```json {"openapi":"3.1.0","info":{"title":"Photoroom API","version":"1.0.0"},"servers":[{"url":"https://image-api.photoroom.com","description":"Production server (Plus plan)"}],"security":[{}],"paths":{"/v2/account":{"get":{"operationId":"account-details-v2","summary":"Account Details v2","description":"Get current account details, including remaining image edits and monthly quota","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"},"subscription":{"type":"number","description":"The total number of image available in the subscription","title":"Subscription","minimum":0}},"required":["available","subscription"]},"plan":{"type":"string","description":"The name of the pricing plan","title":"Plan"}},"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"}},"required":["message"]}},"required":["error"],"title":"Field Missing Error"}}}},"403":{"description":"Forbidden"}}}}}} ``` # How to improve images for second-hand item marketplaces In this tutorial you will find real-world examples of how the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) can be used to improve the quality of listing images on a second-hand market place. ## Introduction Let's take the example of this listing page:
As you can see, the images have been taken by the sellers when they listed their item for sale. These images are doing a good job of showing what the items look like, however: 1. the images come in varying aspect ratios ⇒ it leads to some items being cropped after the images have been fit into a in square ratio 2. the backgrounds have very different textures and colors ⇒ it makes the page visually heavy 3. the items don't always immediately stand-out from their background ⇒ it requires more effort from the user So let's go over two different approaches to improve these images and solve these 3 problems. ## White Background + Realistic Shadows Using the Image Editing API, you can automatically edit the images to: * remove the original background and replace it with a white background * center the subject and add some margins * add an ai-generated realistic shadow This is how the listing page looks like after that the images have been edited:
Notice how the page now looks much clearer, with the items now easily identifiable at a glance. If you want to reproduce these results, here's the exact API call that was used to edit the images: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form outputSize=2000x2000 \ --form removeBackground=true \ --form background.color=FFFFFF \ --form margin='10%' \ --form shadow.mode='ai.soft' \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Blurred Background Depending on the context, you might decide that fully removing the original background isn't the right fit, because doing so makes the images look a bit too professional. In this case you can use a different approach to improve the images: instead of removing their backgrounds you can simply blur them. This is how the listing page looks like after that the images have been edited:
As you can see, the backgrounds are now less distracting and the items stand out more, while the images still retain a very authentic appearance. If you want to reproduce these results, here's the exact API call that was used to edit the images: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form referenceBox=originalImage \ --form removeBackground=false \ --form background.blur.mode=gaussian \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Conclusion The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) allows you to significantly improve the quality of second-hand item images. And it's not a one-size-fits-all approach: you have the choice between different editing options, allowing you to pick the one that best matches your guidelines. If you want to learn more, here's the details of the API features used in this tutorial: * [Positionning](/image-editing-api-plus-plan/positioning) * [Solid Color Background](/image-editing-api-plus-plan/static-background) * [AI Shadow](/image-editing-api-plus-plan/ai-shadows) * [Blurred Background](#blurred-background) ## Book a demo If you'd like more information about how the Photoroom API can help you improve the quality of your images, don't hesitate to [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # How to create e-commerce images with consistent brand guidelines In this tutorial you will find the details of how the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) enables you to edit your product images so that their look-and-feel is consistent across your entire catalog. ## Introduction If you’re running an e-commerce website, you know how important it is to have product images that follow the same brand guidelines, so that the look-and-feel is consistent from one image to the next. But if you're getting your product images from different sources, it's very likely that you receive them in very different aspect ratios, product positioning or even background color:
However what you want is to have all your images follow the same brand guidelines, such as: * 1920x1080 pixels * white background * centered product * 10% of padding So let's go over how we can implement these guidelines using the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). ## Implementation ### Output Size Let's start by making sure that the result images all have the same resolution. We can configure the resolution through the parameter `outputSize`, by setting its value to `1920x1080`. ### White Background By default, the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will remove the background of the input image, so there's no need to set a specific argument for it to happen. However, we do need to specify that we want to result image to be on a white background. To achieve this, we'll use the parameter `background.color` which allows us to [replace the background with a solid color](/image-editing-api-plus-plan/static-background#solid-color) and set its value to `white`. ### Centered Product By default, the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will automatically center the product in the result image. However, if some sides of the product are cropped, then by default the API will snap these sides of the product to the corresponding edges of the result image. The goal of this behavior is to avoid having empty whitespace between the cropped edges of the product and the edges of the result image: But if needed, this behavior can be disabled by setting the parameter `ignorePaddingAndSnapOnCroppedSides` to `false`. {% hint style="info" %} If needed, it's also possible to [manually control the horizontal and/or vertical alignment of the product](/image-editing-api-plus-plan/positioning#horizontal-and-vertical-alignments). This can be very useful to display products that have different aspect ratios is a harmonious way, like in this example: ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fu7VtYKmQaq2KmZq1Nvaj%2Fimage.jpeg?alt=media\&token=94304d4a-c614-481d-8e4a-642613b3295b) {% endhint %} ### Padding Finally, we need to configure the [positionning of the product](/image-editing-api-plus-plan/positioning), so that there's 10% of padding between the product and the edges of the result image. For this, we'll set the parameter `padding` to the value `10%`. ## API Call Using the parameters `outputSize`, `background.color`, `ignorePaddingAndSnapOnCroppedSides` and `padding` we're now ready to automatically edit the product images to make them compliant with the brand guidelines. Here's the API call we'll use: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form outputSize=1920x1080 \ --form background.color=white \ --form padding='10%' \ --form ignorePaddingAndSnapOnCroppedSides=false \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Results Here's a before/after of the results this API call produces: | *(original image)* | *(edited image)* | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FeN2mc0vlWTURfpKWNWDc%2F1_7G_6RKDSqZ6E1BvULOxMleRakOiGsQ9.jpg?alt=media\&token=c7dd93f7-a13d-4b06-861c-61ee889c8ea5) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUq6A0vxiGKtFd7sUg9Rh%2F1_7G_6RKDSqZ6E1BvULOxMleRakOiGsQ9.png?alt=media\&token=5f017432-aef4-4daa-bc83-95576e801b62) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F4tX20Yg4udv3i8xQbuGP%2F1UyUSkCzFfE8GDp6NajYl8OH6dC3bYdTa.jpg?alt=media\&token=0097e5a4-e697-46f4-95ce-9d440a622afe) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FZqNegQHfCdPuFFEHQEtl%2F1UyUSkCzFfE8GDp6NajYl8OH6dC3bYdTa.png?alt=media\&token=376c2c3b-25cb-41f4-af60-e885c31e0629) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fn9z58Vv82UQziYFPlz5S%2F1uqPLMWWYYBnMNuW3wrF5nR7XsWIAicaN.jpg?alt=media\&token=d36873f9-7eb1-4cf9-9f17-1143c9e2e3b6) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FDAigd2FuEHulFTLdTGJG%2F1uqPLMWWYYBnMNuW3wrF5nR7XsWIAicaN.png?alt=media\&token=17a1b2fe-833c-402d-9db6-21cd56d665da) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBDCerhJsJYsKafN9NbTo%2F1a_6N688DYGi9ia3YimyCmUnOkExV84XF.jpg?alt=media\&token=391aef67-4f99-4bdc-b5e7-caecc7afb496) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fv5327xNlXD4v6ql6lDz8%2F1a_6N688DYGi9ia3YimyCmUnOkExV84XF.png?alt=media\&token=5dc715f6-0f10-4da5-80fe-59f29358be09) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FdFx0Xbak1pqmrH6wMi4d%2F1-uJ6DnpzNC6A_10wGV2lZRIBF4879yHs.jpg?alt=media\&token=3336d2a7-e473-4afc-bd99-9f48fca36fdf) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F2616JVbcS3Q2ujLI3KaX%2F1-uJ6DnpzNC6A_10wGV2lZRIBF4879yHs.png?alt=media\&token=6f4e3e6d-efcd-4c99-9435-44668686f6d9) | ## Conclusion The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) allows you to easily edit your product images so that they comply with your brand guidelines and that you have a consistent look-and-feel across your entire catalog. If you want to learn more, here's the details of the API features used in this tutorial: * [Output Size](/image-editing-api-plus-plan/output-size) * [Solid Color Background](/image-editing-api-plus-plan/static-background#solid-color) * [Positioning](/image-editing-api-plus-plan/positioning) ## Book a demo If you'd like more information about how the Photoroom API can help you improve the quality of your images, don't hesitate to [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # How to create food delivery images with consistent brand guidelines In this tutorial you will find the details of how the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) enables you to edit food images so that their look-and-feel is consistent across your entire delivery app. ## Introduction If you’re running a food delivery app, you know how important it is to have food images that follow the same brand guidelines, so that the look-and-feel is consistent from one image to the next. But if you're getting your images from different restaurant owners, it's very likely that the images you receive have been taken at very different angles, with distracting backgrounds and sometimes without having the full dish in view:
However what you want is to have all your images follow the same brand guidelines, such as: * 2000x2000 pixels * white background * dish is centered, with 10% of padding * realistic shadow * no cropped dish (including plates) So let's go over how we can implement these guidelines using the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). ## Implementation ### Output Size Let's start by making sure that the result images all have the same resolution. We can configure this resolution through the parameter `outputSize`, by setting its value to `2000x2000`. ### Centering + Padding By default, the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will automatically center the dish in the result image. But we also need to configure the [positionning of the dish](/image-editing-api-plus-plan/positioning), so that there's 10% of padding between the dish and the edges of the result image. For this, we'll set the parameter `padding` to the value `10%`. ### White Background By default, the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will remove the background of the input image, so there's no need to set a specific argument for it to happen. However, we do need to specify that we want to result image to be on a white background. To achieve this, we'll use the parameter `background.color` which allows us to [replace the background with a solid color](/image-editing-api-plus-plan/static-background#solid-color) and set its value to `white`. ### Realistic Shadow Next we want to add a realistic shadow to the dish, so that it blends nicely with its new background. The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) offers a feature called [AI Shadows](/image-editing-api-plus-plan/ai-shadows) that allows you to add a realistic shadow around the main subject of the input image. To add an AI Shadow with a soft shadow preset to the dish, set the parameter `shadow.mode` to the value `ai.soft`. {% hint style="info" %} Additional shadow presets are available, more details can be found in the [documentation of AI Shadows](/image-editing-api-plus-plan/ai-shadows). {% endhint %} ### No Cropped Dish Finally, we need to make sure that if the dish (or its plate) has been cropped in the original image, it is uncropped in the result image. For this we'll use the feature [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) of the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). To use uncrop the dish if needed, set the parameter `uncrop.mode` to the value `ai.auto`. ## API Call Using the parameters `outputSize`, `background.color`, `padding`, `shadow.mode` and `uncrop.mode` we're now ready to automatically edit the product images to make them compliant with the brand guidelines. Here's the API call we'll use: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form outputSize=2000x2000 \ --form background.color=white \ --form padding='10%' \ --form shadow.mode=ai.soft \ --form uncrop.mode=ai.auto \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Results Here's a before/after of the results this API call produces: | *(original image)* | *(edited image)* | | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBoEtpe4hhPXHhR0nOue1%2FFood_00001.jpeg?alt=media\&token=e8f273c1-e1a0-4771-ad6c-28a68e24a6e0) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fm1KwlLkeC4iYazmKBcMZ%2FFood_00001.png?alt=media\&token=2694089a-0aa1-498d-85e0-efb54ebfa883) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FSiMAg7TeuLhwV605YidZ%2FFood_00002.jpeg?alt=media\&token=7adf17c8-2ba2-4b7f-954b-01d28fdf9a67) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FVj7scTtbAq0kvm0bPblp%2FFood_00002.png?alt=media\&token=7ac38f38-9c9e-436f-a359-38f266dfb185) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FgGzgnqpfBwX40MkrOppA%2FFood_00003.jpeg?alt=media\&token=0ee7a17d-de27-49c0-9510-4260ba863451) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FM1ccbrppflvxz70JZsVY%2FFood_00003.png?alt=media\&token=4ff723b1-36aa-40d8-808e-789005251a46) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FwGuVhInxGXvs26yMoq4S%2FFood_00004.jpeg?alt=media\&token=d2a50d3f-a870-4c3b-8e92-d48fbb91b272) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FEAHRhRHSrHMbRyoeNIjy%2FFood_00004.png?alt=media\&token=e3971233-1c22-43d3-89da-bbd42afed48a) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F4lHW5MBsiC9GoYNIbsF0%2FFood_00005.jpeg?alt=media\&token=19945b87-fbea-4f0c-9fdf-c2e9251d8b50) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FGgjafQ4PmjBD4c5KDPsH%2FFood_00005.png?alt=media\&token=e0d6e404-1d00-4f2f-9e6a-df07b3a4319b) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FJogG9vmxJ4D8HliDqBxG%2FFood_00006.jpeg?alt=media\&token=77ee9c88-bfee-4213-8e6d-7d4cf6909623) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FsJA6m4IrnfZv1hMXoSlZ%2FFood_00006.png?alt=media\&token=301693ea-3eec-4a3c-913b-db9be77e54e0) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F50RpVrfYnQBxCoDvRIdE%2FFood_00007.jpeg?alt=media\&token=3beda4ab-2d1b-4922-ae50-9dd97a3f2f83) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F4fdXsnKjsWgzBQfE8D7k%2FFood_00007.png?alt=media\&token=4d4e3d50-c9f2-4430-a384-d86088014dea) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FVzbanGPOclIbSNKHxbg5%2FFood_00008.jpeg?alt=media\&token=2f1e4dee-90a1-452f-8cbb-4567f5ff3c0e) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FDvFWqj9sum4DTH3B1zsc%2FFood_00008.png?alt=media\&token=af2e427c-3463-4842-b9ec-0f892a35a485) | ## Conclusion The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) allows you to easily edit food images so that they become compliant with your brand guidelines, enabling you to have a consistent look-and-feel across your entire food delivery app. If you want to learn more, here's the details of the API features used in this tutorial: * [Output Size](/image-editing-api-plus-plan/output-size) * [Solid Color Background](/image-editing-api-plus-plan/static-background#solid-color) * [Positioning](/image-editing-api-plus-plan/positioning) * [AI Shadows](/image-editing-api-plus-plan/ai-shadows) * [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) ## Book a demo If you'd like more information about how the Photoroom API can help you improve the quality of your images, don't hesitate to [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # How to create listing images for clothing and apparel In this tutorial you will find the details of how the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) enables you to create the different type of images that are needed to properly list clothing and apparel items. ## Introduction If you’re selling clothing online, you know how important it is to have good images that will showcase your items in the most favorable way possible. Typically, you'll want to have these type visuals: * a clean flat lay top-down shot of the item * a ghost mannequin shot that captures fit and drape * a lifestyle shot of the item worn by a model, showing how it looks on a real body So let's take the example of these clothing items and see how we can use the [Image Editing API](https://docs.photoroom.com/image-editing-api-plus-plan/quickstart-guide) to generate all the images needed to properly list them:
## Implementation ### Flat Lay Let's start by generating the flat lay images. The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) comes with a built-in feature to generate such images. We just need to set the parameter `flatLay.mode=ai.auto` and it will produce these results:
(original image)(edited image)

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form flatLay.mode=ai.auto \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ### Ghost Mannequin Next we'll generate the ghost mannequin images. The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) also comes with a built-in feature to generate them. We just need to set the parameter `ghostMannequin.mode=ai.auto` and it will produce these results:
(original image)(edited image)

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form ghostMannequin.mode=ai.auto \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ### Lifestyle Finally, we'll create lifestyle images where the items are worn on a real body. The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) provides a built-in feature that lets us create images where the clothing is worn by a model. We can either use pre-set models or re-use the likeness if an existing model:
(original image)(edited image)


+




+



+

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form virtualModel.mode=ai.auto \ --form virtualModel.model.preset.name=avery \ --form virtualModel.scene.preset.name=street \ --form virtualModel.pose=standing \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Results Combining all the features of the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide), we can generate the full set of images needed in order to list the items:
## Conclusion The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) allows you to easily generate all the images needed to properly list clothing items, even if you're starting point is just an image taken from a smartphone. If you want to learn more, here's the details of the API features used in this tutorial: * [Flat Lay](/image-editing-api-plus-plan/flat-lay) * [Ghost Mannequin](/image-editing-api-plus-plan/ghost-mannequin) * [Virtual Model](/image-editing-api-plus-plan/virtual-model) ## Book a demo If you'd like more information about how the Photoroom API can help you improve the quality of your images, don't hesitate to [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # How to create compliant product images for Google Shopping In this tutorial you will find the details of how the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) enables you to edit your product images to make them compliant with the guidelines of Google Shopping. ## Introduction If you’re running an e-commerce website or managing digital advertising campaigns for customers, you already know how important it is to have great-looking images of your products. But if you want to list your products on Google Shopping, you must deal with an additional constraint: you’ll have to comply with the platform’s guidelines. More specifically, [Google Shopping expects your product images to](https://www.youtube.com/watch?v=sbJKkbmPZf4): 1. show the product over a white background 2. have a square aspect-ratio, with at least 800 pixels per side 3. have the product occupy between 75% and 90% of the image
So let's go over how these guidelines can be implemented using the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). ## Implementation ### Square Aspect-Ratio Let's start by making sure the result image has a square aspect ratio. We can configure the resolution of the result image through the parameter `outputSize`. Here we need a square aspect-ratio, so we can set its value to, for example, `2000x2000`. ### White Background By default, the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will remove the background of the input image, so there's no need to set a specific argument for it to happen. However, we do need to specify that we want to result image to be on a white background. To achieve this, we'll use the parameter `background.color` which allows us to [replace the background with a solid color](/image-editing-api-plus-plan/static-background#solid-color) and set its value to `white`. ### Padding Finally, we need to configure the [positionning of the product](/image-editing-api-plus-plan/positioning), so that it occupies between 75% and 90% of the result image. For this, we'll set the parameter `padding` to a value between `10%` and `25%`. {% hint style="info" %} By default, `padding` will be [ignored when a side of a product is cropped](/image-editing-api-plus-plan/positioning#cropped-subject). If needed, this behavior can be disabled by setting the parameter `ignorePaddingAndSnapOnCroppedSides` to `false`. {% endhint %} ## API Call Using the parameters `outputSize`, `background.color` and `padding` we're now ready to automatically edit product images to make them compliant with the guidelines of Google Shopping. Here's the API call we'll use: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form outputSize=2000x2000 \ --form background.color=white \ --form padding='10%' \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Results Here's a before/after of the results this API call produces: | *(original image)* | *(edited image)* | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FPwfI67B5eF4UnEAhWHzX%2Fm66901106936_1.jpg?alt=media\&token=c577b36a-5d59-47d8-b6e0-77a53a342742) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FIUMItIctCMLtgnEmyYC7%2Fm66901106936_1.png?alt=media\&token=3c0266dd-2786-4d58-946d-3dbaa23d7f24) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FmyRGz9voB8WAXOK08LaQ%2Fm58155757072_1.jpg?alt=media\&token=cc482694-bacc-4d75-81e2-ec25c0af4835) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FbWMctbSB8otWhJo8v6Wj%2Fm58155757072_1.png?alt=media\&token=67ed0d47-45fb-4659-af03-fce1e83b4371) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F6bfRiLQcZth8Qc2UqFj7%2Fm84390327592_1.jpg?alt=media\&token=e6861500-bbcd-4c1e-84f3-c43e469867b1) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FbhsJ3xMd7EEIHEV3NPR6%2Fm84390327592_1.png?alt=media\&token=8ebec8df-0e26-4342-ad9c-22eca1f56c46) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F27c2JrxXg2tg49IbCGPM%2Fgiorgio-trovato-K62u25Jk6vo-unsplash.jpg?alt=media\&token=d4d82ede-6464-42cb-bd5f-4277f61f8612) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F8tpVzfaXZbfS9Li6phuG%2Fgiorgio-trovato-K62u25Jk6vo-unsplash.png?alt=media\&token=00f71870-f31c-4acb-8948-2b7a30118d41) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FDP9Cx3NW61p1ogmx3f7s%2Fjoan-tran-reEySFadyJQ-unsplash.jpg?alt=media\&token=ad035226-8719-47a0-8834-67ec40f6ac79) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F33M1J57xH37GkSYMSVQo%2Fjoan-tran-reEySFadyJQ-unsplash.png?alt=media\&token=4993efbf-dea0-4a7d-94dc-47b6cc3c0d5c) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F1vSudzosp3jEDgNdHFz6%2Fvarun-gaba-dcgB3CgidlU-unsplash.jpg?alt=media\&token=87abfb9b-82f0-4f99-808d-b2f47a823683) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F2EDPbaaoXsrKeXVB65KX%2Fvarun-gaba-dcgB3CgidlU-unsplash.png?alt=media\&token=5d408e70-994b-4d11-aaff-fa3dea683569) | ## Conclusion The [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) allows you to easily create product images that are compliant with the guidelines of Google Shopping. This tutorial took the example of Google Shopping, but you can of course also use the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) to create compliant images for other advertising networks, such as [Amazon Advertising](https://advertising.amazon.com/) or [Meta (Facebook/Instagram) Shopping](https://business.meta.com/). If you want to learn more, here's the details of the API features used in this tutorial: * [Output Size](/image-editing-api-plus-plan/output-size) * [Solid Color Background](/image-editing-api-plus-plan/static-background#solid-color) * [Positioning](/image-editing-api-plus-plan/positioning) ## Book a demo If you'd like more information about how the Photoroom API can help you improve the quality of your images, don't hesitate to [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # How to create sticker images Stickers are small background-less images that users can use, for example, to react in a conversation or to decorate their profile page:
The Photoroom API makes it easy to add this feature to your app. Here's a before/after example of the kind of high-quality sticker the API can create:
There are two different ways to create a sticker through the Photoroom API, depending on whether the image you want to process is stored locally (in a file or a temporary variable) or hosted remotely. ## Case 1: the orginal image is stored locally If the image you want to process is stored locally, you can turn it into a sticker by calling our [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). Here's how the call looks like: ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form 'image_file=@/absolute/path/to/image.jpg' \ --form 'crop=true' \ --output sticker.png ``` {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} Notice how, additionally to sending the `image_file`, we also set the argument `crop=true`. As its name suggests, this argument crops the size of the result image to that of the cutout subject. ## Case 2: the original image is hosted remotely If the image you want to process is stored remotely, you can turn it into a sticker using the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). Here's how the call looks like: ```bash curl --request GET \ --url 'https://image-api.photoroom.com/v2/edit?background.color=transparent&background.scaling=fill&outputSize=croppedSubject&imageUrl=IMAGE_URL_GOES_HERE' \ --header 'x-api-key: API_KEY_GOES_HERE' \ --output sticker.png ``` {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} Notice how the URL of the image is passed through the query string argument `imageUrl`. This URL must be accessible publicly over the Internet. {% hint style="warning" %} Make sure to [URL encode](https://www.w3schools.com/tags/ref_urlencode.ASP) the value you set for the argument `imageUrl`. {% endhint %} ## Conclusion As we’ve seen, the Photoroom API makes it easy to create high-quality stickers, whether the image that you want process is stored locally or remotely. Please note that there's no difference in quality between the two approaches: both will yield the exact same cutout of the subject. # How to create a selfie generator Over the past years, several major marketing campaigns used the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) to create selfie generators that allowed users to share personalized branded selfies on their social media. Among them were [the Barbie Movie](https://www.barbieselfie.ai/fr/), [Netflix's Black Mirror](https://youareawful.com) and [Taylor Swift's 1989 album](https://presave.umusic.com/1989taylorsversion). In this tutorial, I want to show you how easy it is to build a web app that offers the same set of features, simply by leveraging the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) and a bit of JavaScript. If you're curious to see a demo of the web app we're going to build, one is available here: [https://photoroom-api-web-demo.vercel.app](https://photoroom-api-web-demo.vercel.app/).
{% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} **Important:** This tutorial focuses on the key parts of the implementation. If you want to experiment with the code, I recommend you check out the full codebase, which is [open-source and available on GitHub](https://github.com/PhotoRoom/api-demo-apps/tree/main/Web%20Demo%20App). ## Step 1: Uploading an image to the Remove Background API To allow users to pick the image they want to use, we can use a standard `` tag: ```html ``` Then, we need to upload the file to the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). The implementation is pretty straightforward since the API call is a standard HTTP POST request: ```javascript async function removeBackground() { const formData = new FormData() formData.append("image_file", imageInput.files[0]) formData.append("format", "png") const response = await fetch("https://sdk.photoroom.com/v1/segment", { method: "POST", headers: { "X-Api-Key": apiKey, }, body: formData, }) if (!response.ok) throw new Error("Failed to remove background") const blob = await response.blob() return await loadImage(blob) } ``` {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Step 2: Compositing the image After we have received the image with the background removed, we need to use it to compose the final image. The trick to getting to the final image is to place the background-less image between a background and an overlay layer:
The code that implements this process is inside the function `drawImageWithOverlay()`: ```javascript async function drawImageWithOverlay(image, text, scaleFactor = 1, rotation = 0) { // load the backround and overlay images const background = await loadLocalImage("assets/background.png") const overlay = await loadLocalImage("assets/overlay.png") const canvasHeight = 1920 const canvasWidth = 1080 const scale = Math.min(canvasWidth / image.width, canvasHeight / image.height) const scaledWidth = image.width * scale const scaledHeight = image.height * scale // create the canvas to compose the images const canvas = document.createElement("canvas") canvas.width = canvasWidth canvas.height = canvasHeight const ctx = canvas.getContext("2d") // Draw the background ctx.drawImage(background, 0, 0, canvasWidth, canvasHeight) // Adjust offsetX and offsetY to keep the image centered const offsetX = (canvasWidth - scaledWidth) / 2 const offsetY = (canvasHeight - scaledHeight) / 2 // Draw the image with the removed background ctx.drawImage(image, offsetX, offsetY, scaledWidth, scaledHeight) // Draw overlay on top ctx.drawImage(overlay, 0, 0, canvasWidth, canvasHeight) return canvas } ``` This function contains a bit of code, but the gist of it is pretty simple: 1. we create a canvas and draw the background image 2. then, we scale the user’s image and draw it on top 3. finally, we draw the overlay image on top of everything else ## Step 3: Adding the text We’re almost there, we only need one last thing: allowing the user to input some text and overlaying it on the image. Allowing users to set the text is simple: once again we use a standard `` tag: ```html ``` The more challenging part is to draw the text on the canvas, with the curvature taken into account. For this, we need to add some code to the function `drawImageWithOverlay():` ```javascript // Add text overlay const fontSize = 58 // Increased font size const curveRadius = 400 // Adjusted curve radius for less curvature const centerX = canvasWidth / 2 const centerY = canvasHeight / 2 - 300 const whiteSpaceWidth = 15 const lineHeight = 58 ctx.font = `bold ${fontSize}px 'DM Sans', sans-serif` ctx.fillStyle = "#000000" const lines = ['This person is ', text] let cursorPositionY = 0 // Iterate over each line of text for (const line of lines) { const lineWidth = ctx.measureText(line).width const words = line.split(" ") const totalAngle = lineWidth / curveRadius const startAngle = (-Math.PI - totalAngle) / 2 const endAngle = startAngle + totalAngle let cursorPositionX = 0 // Iterate over each word in the line for (let i = 0; i < words.length; i++) { const word = words[i] // Iterate over each character in the word for (let j = 0; j < word.length; j++) { const char = word.charAt(j) const charWidth = ctx.measureText(char).width const x = cursorPositionX / lineWidth const angle = startAngle + x * (endAngle - startAngle) ctx.save() ctx.translate( centerX + curveRadius * Math.cos(angle), centerY + curveRadius * Math.sin(angle) + cursorPositionY ) ctx.rotate(Math.PI / 2 + angle) ctx.fillText(char, 0, 0) ctx.restore() cursorPositionX += charWidth } cursorPositionX += whiteSpaceWidth } cursorPositionY += lineHeight } ``` As you can see, this code is quite complex. But here’s the logic behind it: 1. We iterate over the lines of text 2. For each line, we compute the coordinates of the semi-circle that we will use as a baseline 3. Then, we iterate over each word and each character in order to draw each character on that baseline with the correct rotation ## Step 4: Downloading the image We’re almost finished, all that’s left to do is add a button that will allow users to download the final image so that they can share it on their social media. To do this we’re first going to add a ` ``` And then we will add the code to handle the download: ```javascript const finalImage = await drawImageWithOverlay(segmentedPhoto, text) const downloadButton = document.getElementById("download-button") finalImage.toBlob((blob) => { const url = URL.createObjectURL(blob) downloadButton.href = url }) ``` Here the strategy is quite simple: 1. we take the content of the canvas 2. we turn it into a binary file representation 3. we set the `href` of the download tag to the URL of that binary representation ## Conclusion That’s it, thanks to the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) and a bit of 2D drawing code in JavaScript, we’ve been able to implement a simple web app that enables users to: 1. upload a selfie 2. customize it using pre-defined visual assets 3. overlay some text on top 4. download the result From that point, it would be pretty easy to reuse this web app for an actual marketing campaign. All you would need is to replace the background, overlay, and text font with the actual branded assets you want to use for the campaign. The full codebase is [open-source and available on GitHub](https://github.com/PhotoRoom/api-demo-apps/tree/main/Web%20Demo%20App). ## Book a demo If you'd like more information about how the Photoroom API can help you improve the quality of your images, don't hesitate to [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # Overview ## Who is this API for? The Visual Agent API lets you create automated agents that enhance your images by: 1. applying the relevant AI editing 2. verifying that no product alteration has been introduced 3. retrying the editing when an alteration has been detected Here are some examples of how the Visual Agent API can be used depending on the industry: ### Food Delivery Pictures of dishes taken by restaurant owners can be of varying quality and AI editing is a great way to improve their quality. However, it's important to ensure that the content of the dish stays the same and that no ingredients have been added or removed. The Visual Agent API solves this problem. The agent will create an automated workflow, that will automatically improve the image and verify product accuracy:
Then, by executing this workflow the agent will produce improved images with the guarantee that no ingredients have been added or removed. | *(original image)* | *(edited image)* | | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fg0YGYnK1oEuYRUwILF8x%2Ffood-demo-alitas.jpg?alt=media\&token=73ec4f96-91c5-4bdd-a88c-a649a0d44310) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FIEW9QhDAW55Dg7kxKAvh%2Ffood-demo-alitas.jpg?alt=media\&token=b5181cd0-acc6-45f1-8e58-9bb4187e7760) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FiJ53qptcUZVQvlXTGChR%2Ffood-demo-chicken-fries.png?alt=media\&token=b506719f-3c20-4af4-b5bb-6ed3cfc27319) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FtJ9UVQ4SZL92CJfmtQ3I%2Ffood-demo-chicken-fries.jpg?alt=media\&token=215f59de-f69f-457b-a27e-ee38e7b10a87) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FqJ7qQJRfKQDBdBev4Q0D%2Ffood-demo-churros.png?alt=media\&token=bbd50e6d-6bc5-4e92-8e3c-07f5d38ff179) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FIvuWoJOhwdmXPq8dOslL%2Ffood-demo-churros.jpg?alt=media\&token=8099b270-07f8-4651-8bc0-ea329cb4f129) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FE9X6zjT7iVGHBTQj6A05%2Ffood-demo-ensalada.jpg?alt=media\&token=f94f3898-8859-4fd1-9adb-d90ec3fac423) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FB5f0zPmghBnX11A5QyU7%2Ffood-demo-ensalada.jpg?alt=media\&token=71ebe700-c908-4328-a8d4-4a3d1c41d809) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FVz8YRsrSINXcP8qtxTO2%2Ffood-demo-taco-queso.jpg?alt=media\&token=1d2aa459-1bbb-4bec-9d00-e2bac2a7ab45) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FnU12AlOaEQsqKuhT7szt%2Ffood-demo-taco-queso.jpg?alt=media\&token=8ed4705b-6dca-4d80-b521-5eece78abb74) | ## How do I call the Visual Agent API? The Visual Agent API is only available for Enterprise plans. If you're interested to use the Visual Agent API, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # Overview ## Who is this API for? The Visual QA API lets you automatically compare an edited image with the original one, to ensure product fidelity. More specifically, this API outputs a score that tells you how much the product in the edited image is true to the one in the original image. This is particularly useful when using editing features powered by generative AI, because these features can create hallucinations on the product. Here are some examples of how the Visual QA API can be used depending on the industry: ### Fashion & Apparel Garments contain a lot of fine details that the best AI editing models will sometimes get wrong. The Visual QA API allows you to work around this problem: 1. instead of a generating a single edited image, generate three of them 2. use the Visual QA API to measure the amount of product fidelity in each 3. select the edited image with the highest fidelity score Here are examples of this approach applied to the [Virtual Model](/image-editing-api-plus-plan/virtual-model), [Flat Lay](/image-editing-api-plus-plan/flat-lay) and [AI Ironing](/image-editing-api-plus-plan/ai-ironing) features:

(the red arrows point to hallucinations)

(the red arrows point to hallucinations)

(the red arrows point to hallucinations)

{% embed url="" %} ### Food Delivery Pictures of dishes taken by restaurant owners can be of varying quality and AI editing is a great way to improve their quality. However, it's important to ensure that the content of the dish stays the same and that no ingredients have been added or removed. The Visual QA API solves this problem. It analyzes the edited image and validates it when the dish hasn't been altered:
And it flags the edited image when the dish has been altered in a way that would mislead buyers:

an extra recipient has been added

an extra sushi has been added

When an edited image is flagged, you can then retry the generation and re-evaluate the new output:

in the first attempt, extra sushis had been added

If after 2 retries the image still doesn't pass validation, it's then safe to assume that the input image is likely too low quality to be meaningfully improved. ## How do I call the Visual QA API? The Visual QA API is only available for Enterprise plans. If you're interested to use the Visual QA API, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # Overview ## Who is this API for? The Video API lets you transform images into videos. Multiple input images are supported for improved product fidelity. Here are some examples of what the Video API can produce. ### Fashion & Apparel {% columns %} {% column width="50%" valign="middle" %}
{% endcolumn %} {% column width="50%" valign="middle" %} {% embed url="" %} {% endcolumn %} {% endcolumns %} {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column %} {% embed url="" %} {% endcolumn %} {% endcolumns %} {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column %} {% embed url="" %} {% endcolumn %} {% endcolumns %} ### Food {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column valign="middle" %} {% embed url="" %} {% endcolumn %} {% endcolumns %} {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column valign="middle" %} {% embed url="" %} {% endcolumn %} {% endcolumns %} {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column valign="middle" %} {% embed url="" %} {% endcolumn %} {% endcolumns %} {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column valign="middle" %} {% embed url="" %} {% endcolumn %} {% endcolumns %} ### Retail {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column %} {% embed url="" %} {% endcolumn %} {% endcolumns %} ### Cars {% columns %} {% column valign="middle" %}
{% endcolumn %} {% column %} {% embed url="" %} {% endcolumn %} {% endcolumns %} ## How do I call the Video API? The Video API is only available for Enterprise plans. If you're interested to use the Video API, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # Quickstart Guide Here's a walkthrough of the latest API features: {% embed url="" %} ## Who is this API for? The Image Editing API enables anyone to easily create high-quality images. This is what a typical call to the API looks like: ```sh curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/absolute/path/to/image.jpg \ --form removeBackground=true \ --form background.color=FFFFFF \ --form padding=0.15 \ --form shadow.mode=ai.soft \ --output result.png ``` Try it now! {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} And these are examples of results that this API call produces: | *(original image)* | *(result image)* | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FF9aePxDAi87gxSXUI7q0%2Farno-senoner-oCXVxwTFwqE-unsplash.jpg?alt=media\&token=2bdd3141-664d-49fe-b0a9-5523e28d06b6) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F8AU7Zwk7FAJHKs0mw5Aj%2Farno-senoner-oCXVxwTFwqE-unsplash.png?alt=media\&token=3f5e262d-c5a1-4c6c-b0cc-a57f3ecffbad) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FzosfeByML0TIFxRcisuL%2Fdylan-shoemaker-P5tHZv-QTCA-unsplash.jpg?alt=media\&token=28f7ebcf-93dc-481c-9f7f-0d7954b04961) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fk8R35WdY4aFNBD5u7ypE%2Fdylan-shoemaker-P5tHZv-QTCA-unsplash.png?alt=media\&token=0589787b-f1d0-4677-a874-5b0d156cdd81) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FsKHxqVDsGHipUBBybOxG%2Fjon-tyson-aR6RjBC_bF0-unsplash.jpg?alt=media\&token=548edb41-c3dd-4c2e-9447-29e415d36a89) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F2xRqBNJXvHhR3GNuntdj%2Fjon-tyson-aR6RjBC_bF0-unsplash.png?alt=media\&token=38409992-83a0-4012-b492-f92be1e1a8b0) | Let's go over the parameters of this API call. #### `imageFile=@/absolute/path/to/image.jpg` This parameter represents the input image that you want to edit. This image can be provided either: * as a file, using the parameter `imageFile` * as a URL, using the parameter `imageUrl` More details about maximum file size, resolution and image formats are [available here](/image-editing-api-plus-plan/file-size-resolution-and-format). #### `removeBackground=true` This parameter specifies that the background of the input image should be removed. {% hint style="info" %} `removeBackground` is set to `true` by default, so you can omit it when you want the background to be removed {% endhint %} #### `background.color=FFFFFF` This parameter creates a new background that consists of a white solid color. Alternatively to using a solid color, you can also opt for: * having a transparent background (this is this the default behavior) * using a [static image](/image-editing-api-plus-plan/static-background) * creating an [AI Background](/image-editing-api-plus-plan/ai-backgrounds) #### `padding=0.15` This parameter adds 15% of padding around the subject, for a more visually pleasing result. The positioning of the subject in the result image is fully customizable, you can [read more about it here](/image-editing-api-plus-plan/positioning). #### `shadow.mode=ai.soft` This parameter adds a realistic shadow to the subject, which helps the result image look more natural. The look of the shadow can be customized, you can [read more about it here](/image-editing-api-plus-plan/ai-shadows). ## How do I configure my first API call? We designed the Image Editing API so that it’s both very powerful and very easy to use. There are two ways to start using the Image Editing API: 1. If you already know which feature you're looking for, then you can simply use the *Try it now!* button that's available on the documentation page of that feature:
2. If not, then you can use the search bar at the top of the documentation and simply describe the output that you want to achieve:
{% hint style="info" %} Please note that you can make API calls for free using our [Sandbox mode](/getting-started/pricing#can-i-get-free-api-calls). {% endhint %} ## Which endpoints are available? The Image Editing API exposes two endpoints. ### GET endpoint ```http GET https://image-api.photoroom.com/v2/edit ``` The `GET` endpoint expects you to: * configure the edits you want to apply through query string arguments * provide the input image as a URL, through the argument `imageUrl` This means that the images you process through that endpoint must already be hosted on the Internet. Here's an example of an API call made using the `GET` endpoint: {% code overflow="wrap" %} ```sh curl 'https://image-api.photoroom.com/v2/edit?shadow.mode=ai.soft&background.color=FFFFFF&padding=0.1&imageUrl=URL_OF_YOUR_IMAGE' \ --header 'x-api-key: YOUR_API_KEY' \ --output result-get-endpoint.png ``` {% endcode %} {% hint style="info" %} The full API reference documentation of this endpoint is [available here](/getting-started/api-reference-openapi#get-v2-edit) {% endhint %} ### POST endpoint ```http POST https://image-api.photoroom.com/v2/edit ``` The `POST` endpoint allows you to: * directly upload an image file, through the argument `imageFile` * configure the edits through the body of the request rather than the query string Here's an example of an API call made using the `POST` endpoint: ```sh curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/absolute/path/to/image.jpg \ --form shadow.mode=ai.soft \ --form background.color=FFFFFF \ --form padding=0.1 \ --output result-post-endpoint.png ``` Try it now! {% hint style="info" %} The full API reference documentation of this endpoint is [available here](/getting-started/api-reference-openapi#post-v2-edit) {% endhint %} ## Will the API make alterations to my products? No, for most use cases the Image Editing API will **not make** alterations to your products. By default, the API will: 1. remove the background of the original image, to isolate its main subject 2. reposition and add effects around that main subject With this approach, it's simply not possible to introduce alterations, such as modifying a logo or a brand name. The Image Editing API does offer some features that can, however, introduce alterations. Here's their exhaustive list: * [AI Relight](/image-editing-api-plus-plan/ai-relight), which can alter colors * [AI Text Removal](/image-editing-api-plus-plan/ai-text-removal), which removes text from the main subject * [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) and [AI Expand](/image-editing-api-plus-plan/ai-expand), which generates the missing part of the original image * [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier), which creates a re-imagined version of the main subject * [AI Upscale](/image-editing-api-plus-plan/preview-ai-upscale), which increases the resolution of the original image * [Describe Any Change](/image-editing-api-plus-plan/edit-with-ai), which edits the original image using an AI model If you use one of these features and product accuracy is important for you, then we recommend that you have a human validation of the images produced by the API. # Pricing The Image Editing API is part of our "Plus plan" and each API call is priced at $0.10. This means that an API call can include as many edit options as needed, **with no impact on the price**. For example, you can combine using [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier) along with other features, such as [AI Shadows](/image-editing-api-plus-plan/ai-shadows) or [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds), without having to worry about any variation in the price of the API call: | *(original image)* | *(beautified image)* | (*beautified image and* [*AI Shadows*](/image-editing-api-plus-plan/ai-shadows)*)* | (*beautified image and* [*AI Backgrounds*](/image-editing-api-plus-plan/ai-backgrounds)*)* | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FZrl3xPuZjV7Vgs4xmRP2%2Fa2bc94f05b46f9d1d023671c2cdca5289a7441aae43ae0fdff656e827f387b71.jpeg.webp?alt=media\&token=69b807d8-cd7b-4430-87f8-9227177de62c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FjVwNXEMRkcX9Q0r1mKey%2Fa2bc94f05b46f9d1d023671c2cdca5289a7441aae43ae0fdff656e827f387b71.jpeg.png?alt=media\&token=fdc5e1b5-51a5-4ff0-8982-0552a54cc672) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F5lVPZyqByH2OZyeWD8hB%2Fperfume_shadow.png?alt=media\&token=4b3181b8-f8b3-4826-943d-e6519ba05fa0) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FpgWaBvf2PvicN4tSmYAE%2Fperfume_backgound.png?alt=media\&token=dca05250-7dc6-4721-9e75-d779753761cc) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FiQ0bpH7KUaIO3stV9C70%2Fshirt.png?alt=media\&token=46d80010-b008-4633-a19f-fe213c56c7a8) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FeO3ldXQzhpVEe9p8MvBh%2Fshirt_beautifier.png?alt=media\&token=9eb3f2c2-ebf9-4b5d-8987-742871851fb7) |
|
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FF7jyrfnytwpfIlXn1QeP%2FScreenshot%202025-09-26%20at%2014.39.07.png?alt=media\&token=d50f167f-c6ff-4228-a04b-11de5988b28f) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUdUauzCEHpRZhblPth3c%2Fpasta_beautifer.png?alt=media\&token=d8fcdde9-8533-44d3-8072-133c465c7b6c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FyBjjIIW2rntYylNnfGjk%2Fpasta_shadow.png?alt=media\&token=3f38544f-a006-46c1-a789-ce1432e3f4d7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F4lRG3fRDIpKORL1S9Nuv%2Fpasta_background.png?alt=media\&token=38631822-5e65-46cc-a784-c01402ebd312) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FnNlJER2JYzo65ePr2tFE%2FScreenshot%202025-09-26%20at%2014.39.15.png?alt=media\&token=3fbdcc70-65a6-4e86-b9f4-7716330ac4ba) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FoaUgHaJ0gf5z3k0OeOcf%2Fpizza_beautifier.png?alt=media\&token=4304a574-e1e3-442c-80e7-cfd949994a6e) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUDvBc86nP5ZtiOc58Lcn%2Fpizza_shadow.png?alt=media\&token=926ff718-4be5-4257-b23f-cdcdd7dfdfc6) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fa5CvMZUDZxCBYcZIUp2u%2Fpizza_background.png?alt=media\&token=26895cb5-0857-40a0-80a7-f38ef6852566) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FiORYJfVqvN9cOIkOnWpw%2Fphoto-1648311975873-f920306ba958.jpg?alt=media\&token=21bcb837-1c97-4b58-989b-b027ccd9680d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FZy19bxR4IhOmDGLSC2XT%2Fphoto-1648311975873-f920306ba958.png?alt=media\&token=035ef41f-705f-4db1-846e-9d022ac3a85d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FeW9gNt6mZUzzZX3yJ1Qg%2Fphoto-1648311975873-f920306ba958.png?alt=media\&token=f73d2b01-3404-4111-a416-5befce68031a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FsnIOITWJiSDFg0k1UHeJ%2Fphoto-1648311975873-f920306ba958.png?alt=media\&token=4e313b0a-c5dd-4925-9db0-d7b132c92481) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fe9TgGPctZSJv6BLVTpRM%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.jpg?alt=media\&token=de938c37-c9d7-485e-9b9d-8976a979ef7b) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fd0Pa6hZtpsx4HnGTBcJ2%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.png?alt=media\&token=babf55b7-77a0-454d-a3c3-ed04226b4ad7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F3ZHD58NFpABMrOzA4KZc%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.png?alt=media\&token=b06845d8-a35d-42e9-a7cc-430d7bdc9970) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F7zriZ3OPUaMwQKnNX4OI%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.png?alt=media\&token=7ea3cdbe-3dc1-40e6-ad99-204813bdd074) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FCFLXnIS019iu0pha2xd2%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.jpg?alt=media\&token=b140875c-864b-43cb-8e5a-45b878cb508a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F03HU52cf9Mtb6h2SRHR1%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.png?alt=media\&token=19dab660-f5ac-4952-9dc4-49d44adb8fc7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FxK9XN882JV1aH6LogqrS%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.png?alt=media\&token=cce86b43-dbed-4903-adfd-c0978bf2d898) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FcfJVh5ROMvnFyujn2NZd%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.png?alt=media\&token=2702de03-e261-4ae8-9cc3-9fb4e011d064) | Edit options include: * Background Removal * [Smart Positioning](/image-editing-api-plus-plan/positioning) * [AI Shadows](/image-editing-api-plus-plan/ai-shadows) * [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) * [AI Relighting](/image-editing-api-plus-plan/ai-relight) * [AI Text Removal](/image-editing-api-plus-plan/ai-text-removal) * [AI Expand](/image-editing-api-plus-plan/ai-expand) * [AI Uncrop](/image-editing-api-plus-plan/ai-uncrop) * [AI Beautifier](/image-editing-api-plus-plan/ai-beautifier) * [Describe Any Change](/image-editing-api-plus-plan/edit-with-ai) Details of the pricing are [available here](https://www.photoroom.com/api/pricing). {% hint style="info" %} For testing and prototyping, you can use [sandbox mode](/image-editing-api-plus-plan/sandbox-mode), which allows you to make free calls to the Image Editing API. {% endhint %} {% hint style="warning" %} Calling the API twice with the same input image and the same edit options will be billed as 2 separate calls. We plan on adding caching but it’s not available yet. {% endhint %} # File size, resolution and format ## **Which image formats are supported?** For the input and result images, the Image Editing API supports four formats: PNG, JPEG, WEBP and AVIF. By default, the result image will be in PNG format. To configure the format of the result image, set the argument `export.format` with one of the following values: * `png` is the lossless PNG format (biggest file size, zero quality loss, transparency is saved) * `jpeg` or `jpg` for JPEG format (smaller file size, transparency is ***not*** saved) * `webp` for WebP format (even smaller file size, transparency is saved) * `avif` for AVIF format (smallest file size, takes a few seconds longer to create, transparency is saved) {% hint style="info" %} JPEG, WebP export with a quality of 90. AVIF uses 75 which has the same or higher fidelity according to [benchmarks](https://tsev.dev/posts/2023-11-10-should-avif-be-the-dominant-image-format/) {% endhint %} {% hint style="warning" %} JPEG format does **not** support transparency. Asking the Image Editing API to export in JPEG while also setting a background color with transparency will result in an error. {% endhint %} If you want to give it a try, here's the code to export an image in JPEG format: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1000x1000 \ --form padding=0.1 \ --form 'export.format=jpeg' \ --output result.jpeg ``` {% endcode %} Try it now! And here's the code to export an image in WebP format: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1000x1000 \ --form padding=0.1 \ --form 'export.format=webp' \ --output result.webp ``` {% endcode %} Try it now! And the code to export an image in AVIF format: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1000x1000 \ --form padding=0.1 \ --form 'export.format=avif' \ --output result.avif ``` {% endcode %} Try it now! ## Preserving the input colour space (`colorSpace: "original"`) By default the Image Editing API returns results in **sRGB**. Set `colorSpace: "original"` on `/v2/edit` to keep the input image's **own colour space and embedded ICC profile** (e.g. Adobe RGB, Display P3) in the output — preserved with no conversion to sRGB. This applies to **background removal** (including HD): the cutout is returned as a PNG carrying the original ICC profile. * **Default** (omit `colorSpace`, or `colorSpace=sRGB`): output is sRGB, exactly as before. * **`colorSpace=original`**: output keeps the input's colour space + ICC profile. #### When it works A **pure background removal** (no other edits), with **PNG output**, on an input that has an embedded colour profile. #### When it returns HTTP 400 `colorSpace: "original"` only applies to a plain background removal that outputs PNG. The request is rejected with a **400** (the error names the conflicting parameter) if it also includes: * Any operation **beyond background removal** — AI/replacement backgrounds, a background colour or image, shadows, relighting, templates, etc. * An **output format other than PNG** (e.g. JPG, WebP, AVIF). * **`export.dpi`**. * **`keepExistingAlphaChannel`** set to anything other than `never`. * **`preserveMetadata`** set to an EXIF-subset mode. ```bash curl -X POST https://image-api.photoroom.com/v2/edit \ -H "x-api-key: YOUR_API_KEY" \ -F "imageFile=@product.jpg" \ -F "removeBackground=true" \ -F "colorSpace=original" \ -F "export.format=png" \ -o cutout.png ``` ```json { "error": { "message": "colorSpace: \"original\" is only supported when the request is a pure background removal with PNG output. Conflicting parameter: \"background\"." } } ``` {% hint style="info" %} If the input image has no embedded colour profile, there's nothing to preserve — the output carries the image's native colour as-is. {% endhint %} ## **What are the max resolution and size of the image?** We recommend limiting images to 25 megapixels for optimal performance. * **Maximum File Size**: 30MB * **Maximum Resolution**: 5,000 pixels on the widest side Images with a larger resolution are supported (if they stay below 30MB), but will be resized down to 5,000 pixels on the widest side. {% hint style="info" %} Please note that large images will result in API calls taking a longer time to complete. If you experience timeouts, we recommend that you try to increase the default timeout of your networking library. {% endhint %} # Preserve metadata The Image Editing API allows you to choose whether metadata embedded in the original image should be preserved in the output. Use this setting if you want to retain XMP or EXIF metadata across processing workflows. To enable this, set the parameter `preserveMetadata` to: * `xmp`: [XMP metadata](https://en.wikipedia.org/wiki/Extensible_Metadata_Platform) will be preserved. * `exifSubsetWithXmpCompatibility` : Preserves the `Copyright` and `UserComment` EXIF tags in the output image. * **For `png` output**: These tags are written as both EXIF and XMP metadata. This dual-write ensures compatibility with tools that don't yet support the EXIF chunk in PNG, a location that was only standardized in the [PNG spec in June 2025](https://www.w3.org/TR/2025/REC-png-3-20250624/#eXIf) and may not yet be supported by all image readers. If your downstream tooling reads XMP, your metadata will be found regardless of EXIF chunk support. * **For `jpeg` and `webp` output**: Only EXIF tags are preserved. XMP copying is not performed, as EXIF is natively and widely supported in these formats. * `exifSubset` *(deprecated)*: **Use `exifSubsetWithXmpCompatibility` instead.** This older option preserves `Copyright` and `UserComment` as EXIF tags only, without the XMP compatibility layer needed for PNG outputs. * `never` *(default)*: all metadata will be stripped from the output image. {% hint style="warning" %} Other types of metadata, such as IPTC, will be **removed** regardless of the setting. {% endhint %} # Output Size The Image Editing API gives you control over the size of the result image. For this, set the parameter `outputSize` with one of the following values: * `auto` (default) * if `templateId` is set, keeps the size of the template * if `templateId` isn't set, behaves like `originalImage` * `{width}x{height}` sets a custom size (example: `1920x1080`) * `originalImage` keeps the dimensions of the input image * `croppedSubject` uses the dimensions of the cutout subject # Keep existing transparency When the input image already contains transparency information inside an alpha channel, the Image Editing API lets you decide whether to conserve or discard this information. For this, set the parameter `keepExistingAlphaChannel` to: * `never` (default): an existing alpha channel will be ignored and the image will be processed through Photoroom's background removal * `auto`: if the image has an alpha channel, its value will be used to create the cutout mask {% hint style="danger" %} It's possible for an image to contain an alpha channel and for that alpha channel to contain no transparency. (i.e. all pixels are 100% opaque) In such a case, if `keepExistingAlphaChannel` is set to `auto` then no cutout will happen. {% endhint %}
(original image)

keepExistingAlphaChannel=never

and

background.color=blue

keepExistingAlphaChannel=auto

and

background.color=blue

# HD Background Removal Using HD Background Removal is recommended when you want to remove the background of a high-resolution image (≥ 2K) to get more detailed subject edges:
To enable the feature, add this HTTP header to your API call: `pr-hd-background-removal: auto` If you want to give it a try, here's the code to reproduce the example above: {% code overflow="wrap" %} ```bash curl --location 'https://image-api.photoroom.com/v2/edit' \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-hd-background-removal: auto' \ --form imageFile=@/absolute/path/to/image.jpg \ --form referenceBox=originalImage \ --output result-hd-background-removal.png ``` {% endcode %} Try it now! Here are several examples of what HD Background Removal can achieve: {% hint style="info" %} Don't hesitate to download the images locally and zoom on the edges to better see the difference. {% endhint %} {% tabs %} {% tab title="1" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="2" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="3" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="4" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="5" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="6" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="7" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="8" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="9" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% tab title="10" %}

(original image)

(without HD Background Removal)

(with HD Background Removal)

{% endtab %} {% endtabs %} # Pixel Density (DPI) The Image Editing API allows you to control the pixel density of the result image. To control the pixel density, set the argument `export.dpi` to a value between `72` and `1200` (included). Here's an example of an API call to get a result image with a pixel density of 300 dpi: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/image.jpg \ --form export.dpi=300 \ --output result-with-300-dpi.png ``` Try it now! # Sandbox Mode You can make up to 1,000 free calls by month to the Image Editing API using sandbox mode (the max per day is 100 calls). Sandbox mode is meant to be used for testing and prototyping, and will produce an image with a watermark. {% hint style="info" %} All the features of the Image Editing API are available in sandbox mode, including AI features such as [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds), [AI Shadows](/image-editing-api-plus-plan/ai-shadows) or [AI Expand](/image-editing-api-plus-plan/ai-expand). {% endhint %} To use sandbox mode, prepend `sandbox_` to your API key. (Example: `sandbox_xxxxxxxxxxxxxxxx`) ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: sandbox_xxxxxxxxxxxxxxxx' \ --form imageFile=@/path/to/image.jpg \ --form shadow.mode=ai.soft \ --form background.color=FFFFFF \ --form padding=0.1 \ --output result-sandbox-mode.png ``` Try it now! | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FSfNyqw4ZvJfkjQhTrCtu%2Fshoes.jpeg?alt=media\&token=3d01688a-b234-4a5e-badf-5b99d4a3df53) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fo1fM80rxroasyKbU19Xn%2Fregular-call.jpeg?alt=media\&token=f233879f-b629-49e8-8ead-459d0ed5cecb) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fyy1Bz22OwlRKGHrNhZKR%2Fsandbox-call.jpeg?alt=media\&token=617655cb-7064-4e62-abd0-bea47715f498) | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *(original image)* | *regular API call* | *sandbox mode API call* | # Uncertainty score The API returns a confidence score of the cutout through the HTTP header `x-uncertainty-score`. 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):
High uncertainty score: between 0.6 and 1Low uncertainty score: between 0 and 0.3
{% hint style="warning" %} Please note that the uncertainty score is not guaranteed to be stable over time: the same image might yield a different uncertainty score in the future. {% endhint %} In some cases, we might not be able to able to return an uncertainty score (e.g. if an image contains humans), in that case the value `-1` will be returned. # Positioning The goal of the Image Editing API is to give you as much control as possible on how to position your subject in the result image, while also making it as easy as possible to implement the most common use cases. ## General Principle By default, the Image Editing API positioning system will `fit` the [`referenceBox`](#reference-box) inside the [`targetArea`](#target-area).
Original ImageResult Image
The next sections of this page will go into the details of how this system works and how you can control it to get exactly the result that you need. ## Target Area The `targetArea` (green square in the picture) represents the space available inside the result image to display the subject.
By default, the `targetArea` will take all the space available in the result image, and the subject will be: * resized to `fit` the `targetArea` * centered inside the `targetArea` If you prefer for the subject to fill as much space as possible inside the `targetArea`, this is possible by setting the argument `scaling` to `fill`:
If you prefer for the subject to be positioned somewhere else than at the center of the `targetArea`, this is also possible, please see the section [Horizontal and Vertical Alignments](#horizontal-and-vertical-alignments) for more details. ## Padding If you want to add some space between the target area and the borders of the result image, this can be controlled through the argument `padding`. The API supports two formats to specify the amount `padding`: * relative values, expressed in percentages (e.g., `0.2` or `20%`) * absolute values, expressed in pixels (e.g., `100px`) In this example, `padding` has been set to `0.1` (10%):
This results in the addition of empty space between each edge of the result image and the target area. Here, the size of this empty space is equal to 10% of the size of the corresponding side of the result image (i.e. 10% of the width for the left and right edges, and 10% of the height for the top and bottom edges). If needed, a different amount of padding can be set for each edge of the result image, trough the arguments `paddingLeft`, `paddingRight`, `paddingTop` and `paddingBottom`. In this example, the global `padding` is still set to `0.1` (10%), but additionally: * `paddingTop` has been overriden and set to `0.2` (20%) * `paddingLeft` has also been overriden and set to `0.2` (20%)
{% hint style="warning" %} Padding is computed with respect to the width and height of the result image. This means that a `paddingLeft` of 20% will be equal to 20% of the width of the result image. This also means that if the percentage of padding on two opposing sides is greater than or equal to 100%, it will lead to an error because it means that there's no space left to position the subject. (Because of this, since the argument `padding` applies to all sides, its value must be strictly less than `0.5`) {% endhint %} ## Cropped Subject In the previous sections, we saw that, by default, the Image Editing API will cut out the main subject of the input image, position it at the center of the result image, and apply the specified padding around it:
However, if some of the sides of the subject are cropped, then by default the API will not apply any padding to these sides. The goal of this behavior is to avoid having empty whitespace between the cropped edges of the subject and the edges of the result image:
{% hint style="warning" %} Snapping cropped edges to the side of the result image will only happen when a single edge has been cropped for a given direction. Here are some examples: * if the left edge of the subject is cropped: * snapping will happen for the horizontal direction and the subject will be snapped to the left edge of the result image * snapping will not happen for the vertical direction and the subject will be centered vertically in the result image * if the left and right edges of the subject are cropped * snapping will not happen for the horizontal dimension and the subject will be centered horizontally in the result image * snapping will not happen for the vertical dimension and the subject will be centered vertically in the result image * if the top and bottom edges of the subject are cropped: * snapping will not happen for the horizontal dimension and the subject will be centered horizontally in the result image * snapping will not happen for the vertical dimension and the subject will be centered vertically in the result image * if the left and top edges of the subject are cropped: * snapping will happen for the horizontal direction and the subject will be snapped to the left edge of the result image * snapping will happen for the vertical direction and the subject will be snapped to the top edge of the result image * if the left, top and right edges of the subject are cropped: * snapping will not happen for the horizontal dimension and the subject will be centered horizontally in the result image * snapping will happen for the vertical direction and the subject will be snapped to the top edge of the result image {% endhint %} If you want, you can disable this behavior by setting the parameter `ignorePaddingAndSnapOnCroppedSides` to `false` in your API call, which will produce this result:
## Margin In the previous section, we saw that, by default, padding will not be applied to cropped edges and that it's also possible to disable this behavior. However, there might be situations where you want to keep this behavior, but you also need to always have some amount of empty space between the subject and the border of the result image. A typical use case would when a background or an overlay will be added to the result image and you want to make sure that this background or overlay will not go over the subject. This behavior can be implemented through the argument `margin`. As with `padding`, two formats are supported to specify the amount `margin`: * relative values, expressed in percentages (e.g., `0.2` or `20%`) * absolute values, expressed in pixels (e.g., `100px`) Here's an example where `padding` has been set to `0.1` and `margin` set to `0.05`:
And just like with the padding, it's also possible to set different values for each edge, through the arguments `marginLeft`, `marginRight`, `marginTop`, and `marginBottom`. In this example, `margin` is still set to `0.1` and `marginBottom` has been set to `0.2`:
## Reference Box The `referenceBox` corresponds to either: * the `subjectBox`, which is the rectangle around the cutout subject * the `originalImage`, which is the entire input image
By default, the Image Editing API will: * set the `referenceBox` to the `subjectBox` * `fit` the `referenceBox` inside the `targetArea` However, if you want the cutout subject to retain the position it had in the original image, you can do it by setting the argument `referenceBox` to `originalImage`.
(original image)referenceBox=subjectBox
(default value)		referenceBox=originalImage
{% hint style="info" %} Retaining the original position of the subject can be useful when replacing an existing background by a new [AI Background](/image-editing-api-plus-plan/ai-backgrounds). {% endhint %} ## Horizontal and Vertical Alignments If needed, it's possible to manually control both the horizontal and vertical alignments of the subject. {% hint style="info" %} Manually controlling the alignment is very useful when you want to position subjects with different aspect ratios is a harmonious way, like here where the subjects have been vertically aligned at the bottom: ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FuTYrXOFuQBHxKnPpjreq%2FGroup.png?alt=media\&token=787aaa30-24d9-451f-9f87-535efdae3a94) {% endhint %} ### Controlling the Horizontal Alignment To control the horizontal alignment, you need to set the argument `horizontalAlignment` with one of the following values: `left`, `center` or `right`.
horizontalAlignment=lefthorizontalAlignment=centerhorizontalAlignment=right
### Controlling the Vertical Alignment To control the horizontal alignment, you need to set the argument `verticalAlignment` with one of the following values: `top`, `center` or `bottom`.
verticalAlignment=topverticalAlignment=centerverticalAlignment=bottom
# Perspective Correction {% embed url="" %} ## Overview The Image Editing API allow you to automatically correct the perspective of products that have a rectangular shape. Perspective correction doesn't involve generative AI: product fidelity is built-in, hallucinations are impossible by design. ## How do I use the feature? Perspective Correction is only available for Enterprise plans. If you're interested to use the feature, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Examples ### Trading Cards
(original image)(perspective correction + white background + AI Shadow + AI Relight)(perspective correction + blurred background + AI Relight)
### Books, Comics
(original image)(perspective correction + white background + AI Shadow + AI Relight)(perspective correction + blurred background + AI Relight)
### Video Game, DVD, Blu-Ray
(original image)(perspective correction + white background + AI Shadow + AI Relight)(perspective correction + blurred background + AI Relight)
# Smart Cropping ## Overview The Image Editing API allows you to automatically crop an image to put the focus on its main subject. To perform such a smart crop set the parameters: * `removeBackground` to `false` * `outputSize` to the desired result size and aspect ratio, for example `2000x2000` * `padding` to add some breathing room around the subject, for example `10%` * (*optional)* `segmentation.prompt` to focus on a specific element of the image, for example `product`
(original image)(result image)
If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form outputSize=2000x2000 \ --form padding=10% \ --form segmentation.prompt=product \ --output result-smart-crop.png ``` Try it now! ## Examples
(original image)(result image)
### Faceless / Headless Crop Some marketplaces require on-model imagery to be anonymized: the model's face must be cropped out, just below the nose, so the listing doesn't rely on a recognizable likeness. To produce a faceless crop, set the parameters: * `removeBackground` to `false` to keep the original background and apply only the crop * `referenceBox` to `subjectBox` to frame the crop relative to the model * `segmentation.mode` to `ignoreSalientObject` so the prompts drive the crop region instead of the most prominent object * `segmentation.prompt` to `garment,chin,lip,mouth`, the parts to keep * `segmentation.negativePrompt` to `head,nose,eye,forehead`, the parts to exclude * `padding` to `25px` to add a little breathing room around the subject
(original image)(result image)
If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.jpg \ --form removeBackground=false \ --form referenceBox=subjectBox \ --form segmentation.mode=ignoreSalientObject \ --form 'segmentation.prompt=garment,chin,lip,mouth' \ --form 'segmentation.negativePrompt=head,nose,eye,forehead' \ --form padding=25px \ --output result-faceless-crop.png ``` Try it now! **Tip:** You can chain this with subsequent Image Editing API calls to remove the background, add realistic shadows, or apply further enhancements. # Static Background ## Overview The Image Editing API allows you to replace the background of the input image with a new static background. This new static background can be created using either a solid color or another image. {% hint style="info" %} If you're looking to create ai-generated background, please check out the [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) feature. {% endhint %} ### Solid Color To replace the background with a solid color, set the argument `background.color` to an hexadecimal color code (e.g. `FF0000`): | *(original image)* | `background.color=D3D3D3` | `background.color=ADD8E6` | | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQb4CVQZhXwIcKlzxQ9Qp%2Fshoes.jpeg?alt=media\&token=5369cf82-c842-4444-9ab7-1e749b0c4742) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FPhrVtKhgOvuxWnClt2Pt%2Fresponse.png?alt=media\&token=e0e88a62-5b4f-4aca-a953-3a09023839f1) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FJU4YUMrRQR2TTw1CVSS3%2Fresponse.png?alt=media\&token=fbea7b1c-dbf7-48f1-adc7-ae16d157defe) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fe1Fdc6YnSsUXWr7JzyJu%2Fjonas-kakaroto-KIPqvvTOC1s-unsplash%20Large.jpeg?alt=media\&token=ccb1d7f9-ae15-4427-ab33-56ec7380606e) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fb8e6O4zmZJ04Atppeqou%2Fresponse.png?alt=media\&token=4a265d58-ecc8-408d-b4bb-24ea5fe36184) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBDCzkEGzsSj4yqdVXhNY%2Fresponse.png?alt=media\&token=c0849b6c-bfa4-4894-88ce-64510b2af248) | If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form padding=0.1 \ --form background.color=D3D3D3 \ --output result.png ``` Try it now! {% hint style="info" %} When replacing the background with a solid color, consider also adding an [AI Shadow](/image-editing-api-plus-plan/ai-shadows) for a more visually pleasing result: {% endhint %} ### Static Image To replace the background with a static image, set the either the argument `background.imageFile` (available only when [using the `POST` endpoint](broken://pages/xItuUNPEgAlIrn1G1dmE)) or `background.imageUrl`: | *(original image)* | *(static image)* | *(result)* | | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQb4CVQZhXwIcKlzxQ9Qp%2Fshoes.jpeg?alt=media\&token=5369cf82-c842-4444-9ab7-1e749b0c4742) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F9f5NF9YVpCbRNHX6DVJL%2Ftexture-2.jpg?alt=media\&token=dec785c5-c448-4714-a5a8-cbf851014bfc) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F9ElKTcZhBZSzzPbUwSFT%2Fresponse.png?alt=media\&token=8d92a614-5d31-4321-909b-b3687e08a5ef) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fe1Fdc6YnSsUXWr7JzyJu%2Fjonas-kakaroto-KIPqvvTOC1s-unsplash%20Large.jpeg?alt=media\&token=ccb1d7f9-ae15-4427-ab33-56ec7380606e) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FWP5tAoz93Var4UNCj1kl%2Ftexture-1.jpeg?alt=media\&token=d139610d-9c61-4f28-9e23-2a9abe1998ad) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fds8zVeYY9VT5GWIQlv29%2Fresponse.png?alt=media\&token=9688b6d7-4714-4388-a581-77391a46c97b) | If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form padding=0.1 \ --form background.imageFile=@/path/to/background.png \ --output result.png ``` {% hint style="info" %} When replacing the background with a static image, consider also adding an [AI Shadow](/image-editing-api-plus-plan/ai-shadows) for a more visually pleasing result: {% endhint %} # Background Blur ## Overview The Image Editing API allows you to easily blur the background of any image. To blur the background of an image, set the argument `background.blur.mode` to either the value: * `bokeh` A **bokeh blur** simulates the out-of-focus effect of a camera lens. Highlights and bright areas form soft, circular shapes, creating a natural depth-of-field look with smooth, cinematic background blur. * `gaussian` A **gaussian blur** applies a soft, even blur by averaging each pixel with its neighbors using a bell-curve weighting. This creates a smooth, natural blur that reduces fine detail and noise | | | | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *(original image)* | `background.blur.mode=bokeh` | `background.blur.mode=gaussian` | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQb4CVQZhXwIcKlzxQ9Qp%2Fshoes.jpeg?alt=media\&token=5369cf82-c842-4444-9ab7-1e749b0c4742) |
|
| {% hint style="warning" %} In order to blur the background, you need to also set `removeBackground` to `false` {% endhint %} If you want to give it a try, here's the code to reproduce the example above: 
curl --request POST \
  --url https://image-api.photoroom.com/v2/edit \
  --header 'x-api-key: YOUR_API_KEY_HERE' \
  --form imageFile=@/path/to/image.png \
  --form background.blur.mode=bokeh \
  --form removeBackground=false \
  --output result.png
Try it now! ## Additional parameters ### `background.blur.radius` To the control the strength of the blur, set the argument `background.blur.radius` to a value strictly greater than `0` and lower than or equal to `0.05`. Higher values mean the result will be blurrier. This argument is optional and has a default value of `0.01`. # Subject Outline ## Overview The Image Editing API allows you to easily add a **colored outline** around the subject of your images. ### `outline.color` To add a **colored outline** to the subject of an image, set the `outline.color` argument to a solid color value. It can be any hexadecimal color code **without** the # symbol (examples: `FF0000`, `FF0000EE`) or a supported color name (see list below). | *(original image)* | `outline.color=white` | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | |
List of supported color names * `aqua` * `black` * `blue` * `cyan` * `fuchsia` * `gray` * `green` * `lime` * `magenta` * `maroon` * `navy` * `olive` * `purple` * `red` * `silver` * `teal` * `white` * `yellow`
{% hint style="warning" %} To preserve the background, you must also set `removeBackground` to `false`. {% endhint %} If you want to give it a try, here is a code snippet to reproduce the example above: ```bash curl --request POST \ --url 'https://image-api.photoroom.com/v2/edit' \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form 'imageFile=@"/path/to/image.png"' \ --form 'outline.color="white"' \ --form 'referenceBox="originalImage"' \ --form 'removeBackground="false"' \ --output result.png ``` Try it now! ## Additional Parameters ### `outline.width` To control the width (thickness) of the outline, set the argument `outline.width` to a value between `0` and `0.1`. The value represents a ratio of the image size, where `0.1` (10%) is the maximum thickness. When this argument is not provided, the API applies a default value of `0.03`. **Suggested values:** * `0.01-0.02`: Subtle/thin outline * `0.03-0.05`: Standard/medium outline * `0.06-0.1`: Bold/thick outline | `outline.width=0.01` | `outline.width=0.03` | `outline.width=0.1` | | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBv8oW8RR5rfhBlQj5H8H%2Fshoes-outline-width-0-1.png?alt=media\&token=e38c6837-e0a8-44a6-9542-d4acedae1d29) | ### `outline.blurRadius` You can apply blur to the outline to create a glow or soft edge effect. To control the blur strength of the outline, set the `outline.blurRadius` argument to a value between `0` (no blur) and `0.025` (maximum blur). When this argument is not provided, the API applies a default value of `0`. | `outline.blurRadius=0` | `outline.blurRadius=0.01` | `outline.blurRadius=0.025` | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FlQkLReDW1TGbfXz3g8oU%2Fshoes-white-outline.png?alt=media\&token=86709449-1b15-4362-a30e-a612631d4efb) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F1EciKUsyYAcGU8hdqvdw%2Fshoes-outline-blur-0-01.png?alt=media\&token=6d3bf245-681a-4da5-a924-5477c514843a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F2EKuffxXjfprMUS8E6uT%2Fshoes-outline-blur-0-025.png?alt=media\&token=eb845380-fc0c-452d-a7b4-ace97ab4e4cb) | ## Examples
(original image)(edited image)


outline.color=white & outline.width=0.03 & removeBackground=false


outline.color=white & outline.width=0.02 & outline.blurRadius=0.02 & removeBackground=false


outline.color=black & outline.width=0.02 & removeBackground=true


outline.color=fcfc03 & outline.width=0.1 & outline.blurRadius=0.01 & removeBackground=false
# Create Any Image ## Overview Instead of starting from an existing image (by using the parameters `imageFile` or `imageUrl`), you can choose to generate a new AI image using a prompt. To create an AI image, use the parameter `imageFromPrompt`: ```sh curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form removeBackground=false \ --form 'imageFromPrompt.prompt=three mugs on a table in a rustic coffee shop in a realistic style' \ --form imageFromPrompt.seed=12345 \ --output result.png ``` Result:
{% hint style="info" %} Create Any Image generates an image with a background, but the API will perform a background removal by default: you can set `removeBackground=false` if you want to keep the generated background. {% endhint %} ## Parameters Create Any Image supports the following parameters: ### `imageFromPrompt.prompt` Your text prompt to create the image with, for example `three coffee mugs on rustic countertop`, `a red car in a baroque style`, or `a tent on a snowy mountain`. By default, a realistic style will be used, but you can specify the style you want in the prompt, like `in a cyberpunk style` to override it. ### `imageFromPrompt.seed` (optional) The seed to generate the image. The same prompt with the same seed will generate the same image. ### `imageFromPrompt.size`: (optional) The size and format of the generated. The following values are supported: * `SQUARE_HD` (default) * `LANDSCAPE_16_9` * `LANDSCAPE_4_3` * `PORTRAIT_16_9` * `PORTRAIT_4_3` # Edit With AI {% hint style="info" %} Edit With AI is the new name of the feature that used to be called Describe Any Change. {% endhint %} ## Overview Edit With AI allows you to automatically edit the input image by providing a textual description of the changes that you want to make. For example, you can ask to add or remove objects from the image, change a color, etc. To use Edit With AI, set the parameter `editWithAI.mode` to `ai.auto` **and** use the parameter `editWithAI.prompt` to describe the changes:
(original image)(edited image)


editWithAI.prompt="Change the shoes color to red"


editWithAI.prompt="Remove all the objects on the table"


editWithAI.prompt="Remove all the people"
If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form editWithAI.mode=ai.auto \ --form editWithAI.prompt='Change the shoes color to red' \ --output result.png ``` Try it now! ## Which resolutions are supported? By default, Edit With AI will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Examples of Use Cases ### Product Staging You can use Edit With AI to place an item into a realistic lifestyle scene, like being held, worn, or placed on a table. To do so, set the following value for the argument `editWithAI.prompt`: {% code overflow="wrap" %} ``` Make it a professional lifestyle photoshoot with the provided object or subject as the focus of the scene. Ensure the image highlights what is unique about the object, with the goal of advertising it and showing how it impacts everyday life. The lighting should be perfectly set to create a natural and elegant atmosphere. The image should feature excellent composition and a refined mood, achieving the look of high-end lifestyle photography. Integrate a human presence or a subtle interaction with the object to enhance authenticity and visual appeal. ``` {% endcode %} Here are examples of the results it can produce:
(original image)(edited image)

If you want to give it a try, here's the code to reproduce the results above: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form editWithAI.mode=ai.auto \ --form editWithAI.prompt='Make it a professional lifestyle photoshoot with the provided object or subject as the focus of the scene. Ensure the image highlights what is unique about the object, with the goal of advertising it and showing how it impacts everyday life. The lighting should be perfectly set to create a natural and elegant atmosphere. The image should feature excellent composition and a refined mood, achieving the look of high-end lifestyle photography. Integrate a human presence or a subtle interaction with the object to enhance authenticity and visual appeal.' \ --form editWithAI.seed=2016886668 \ --output result-product-staging.png ``` {% endcode %} Try it now! ### Other Angle You can use Edit With AI to create a new image from a different angle. To do so, set the following value for the argument `editWithAI.prompt`: {% code overflow="wrap" %} ``` Create a new photograph of this exact same scene or setting with creative variations. Change the camera angle and viewpoint (e.g., frontal to 3/4 view or side view, high to low angle, wide to tight), adjust composition and framing, and optionally vary the lighting or time of day (morning, golden hour, blue hour, overcast, or dramatic shadows). Try creative approaches such as closer details, wider establishing shots, or alternative focal points. Keep the exact same physical location and environment so it remains clearly recognizable, with the same main subjects, key elements, style, and overall mood. If there's a person, change their pose, position, or activity. If there's a product, show it from a different angle or in different use. The result should feel like a fresh, creative variation taken in the same location during the same shoot, offering a distinctly different perspective while maintaining scene continuity. ``` {% endcode %} {% hint style="info" %} If you need to create images from a specific angle, it can be achieved by editing the prompt to explicitly mention which angle should be used. For example, by replacing *"Change the camera angle and viewpoint (e.g., frontal to 3/4 view or side view, high to low angle, wide to tight)"* with *"Change the camera angle and viewpoint to a 3/4 view"*. {% endhint %} Here are examples of the results it can produce:
(original image)(edited image)

If you want to give it a try, here's the code to reproduce the results above: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form editWithAI.mode=ai.auto \ --form editWithAI.prompt="Create a new photograph of this exact same scene or setting with creative variations. Change the camera angle and viewpoint (e.g., frontal to 3/4 view or side view, high to low angle, wide to tight), adjust composition and framing, and optionally vary the lighting or time of day (morning, golden hour, blue hour, overcast, or dramatic shadows). Try creative approaches such as closer details, wider establishing shots, or alternative focal points. Keep the exact same physical location and environment so it remains clearly recognizable, with the same main subjects, key elements, style, and overall mood. If there's a person, change their pose, position, or activity. If there's a product, show it from a different angle or in different use. The result should feel like a fresh, creative variation taken in the same location during the same shoot, offering a distinctly different perspective while maintaining scene continuity." \ --form editWithAI.seed=2016886668 \ --output result-other-angle.png ``` {% endcode %} Try it now! ## Using Additional Reference Images In addition to the main input image, you can provide up to 4 extra reference images to guide the edit. This enables a multi-reference workflow where the model can combine elements from several source images into a single output — for example, placing a product from one image into the scene of another, or transferring a scene, style, or object across images. To provide additional reference images, use the `editWithAI.additionalImages.*` parameter group. Each reference image is given a name of your choice and must contain exactly one of `imageFile` (for local file uploads) or `imageUrl` (for remote URLs): * `editWithAI.additionalImages.myFirstImage.imageFile` * `editWithAI.additionalImages.mySecondImage.imageUrl` Array-style notation is also supported: `editWithAI.additionalImages[0].imageFile` or `editWithAI.additionalImages.0.imageUrl`. If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/main-image.png \ --form removeBackground=false \ --form editWithAI.mode=ai.auto \ --form editWithAI.prompt='Place the product from the main image into the scene shown in the reference image, matching the lighting and perspective of the reference.' \ --form editWithAI.additionalImages.Scene.imageFile=@/path/to/reference-scene.png \ --form editWithAI.seed=2016886668 \ --output result-multi-reference.png ``` You can also pass references by URL: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/main-image.png \ --form removeBackground=false \ --form editWithAI.mode=ai.auto \ --form editWithAI.prompt='Combine the style of the first reference with the subject of the main image.' \ --form editWithAI.additionalImages.styleRef.imageUrl=https://example.com/style-reference.jpg \ --form editWithAI.additionalImages.moodRef.imageUrl=https://example.com/mood-reference.jpg \ --output result-multi-reference.png ``` #### What are the Limits? Edit With AI currently support up to 5 total images per request, including the main input image. In practice, this means you can provide up to 4 additional reference images via `editWithAI.additionalImages.*`. If you need higher limits, please [contact our team](https://www.photoroom.com/contact-sales) to discuss your use case. ## Additional Parameters ### `editWithAI.seed` If you make several calls to the Image Editing API with the same image and prompt, you will notice that it will generate a different edited image image every time. In order to reduce the randomness, you can set a fixed value for the seed that the API's random generator will use. The value of the argument `editWithAI.seed` can be any positive integer. If you provide a value for `editWithAI.seed`, then the API should produce similar-looking outputs for the same image and prompt. # Flat Lay ## Overview Flat Lay allows you to automatically generate clean, top-down visuals ready for e-commerce and marketplaces. To use Flat Lay, set the parameter `flatLay.mode` to `ai.auto`:
(original image)(edited image)

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form flatLay.mode=ai.auto \ --output result.png ``` Try it now! {% hint style="info" %} Flat Lay is meant to be used with images that feature clothing items. {% endhint %} ## Which resolutions are supported? By default, Flat Lay will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Additional Parameters ### `flatLay.prompt` Optional text prompt to guide the generation style. Example: `a clean studio flat lay` ### `flatLay.size` The output size and aspect ratio of the generated image. Default: `SQUARE_HD` Possible values: `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` # Ghost Mannequin ## Overview Ghost Mannequin lets you show your clothing at its best with clean, mannequin-free visuals that clearly capture fit and drape. To use Ghost Mannequin, set the parameter `ghostMannequin.mode` to `ai.auto`:
(original image)(edited image)

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form ghostMannequin.mode=ai.auto \ --output result.png ``` Try it now! {% hint style="info" %} Ghost Mannequin is meant to be used with images that feature clothing items. {% endhint %} ## Which resolutions are supported? By default, Ghost Mannequin will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Additional Parameters ### `ghostMannequin.prompt` Optional text prompt to guide the generation style. Example: `ghost mannequin` ### `ghostMannequin.size` The output size and aspect ratio of the generated image. Default: `SQUARE_HD` Possible values: `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` # Virtual Model {% embed url="" %} ## Overview Virtual Model lets you automatically convert one or more clothing photos into a polished, lifestyle photoshoot image, using either pre-defined or custom models:
(original image)(edited image)


virtualModel.mode=ai.auto
virtualModel.model.preset.name=avery
virtualModel.scene.preset.name=street
virtualModel.pose=standing


+




virtualModel.mode=ai.auto
virtualModel.model.custom
virtualModel.scene.preset.name=random
virtualModel.pose=random


virtualModel.mode=ai.auto
virtualModel.model.preset.name=jackson
virtualModel.scene.preset.name=library
virtualModel.pose=crossedarms


+



virtualModel.mode=ai.auto
virtualModel.model.custom
virtualModel.scene.preset.name=random
virtualModel.pose=random


virtualModel.mode=ai.auto
virtualModel.model.preset.name=ava
virtualModel.scene.preset.name=bedroom
virtualModel.pose=seated


+



virtualModel.mode=ai.auto
virtualModel.model.custom
virtualModel.scene.preset.name=random
virtualModel.pose=random
{% hint style="warning" %} To keep the background around the virtual model, set the parameters `removeBackground=false` and `referenceBox=originalImage`. If not set, that background will be removed. {% endhint %} If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form virtualModel.mode=ai.auto \ --form virtualModel.model.preset.name=avery \ --form virtualModel.scene.preset.name=street \ --form virtualModel.pose=standing \ --output result.png ``` Try it now! {% hint style="info" %} Virtual Model is meant to be used with images that feature clothing items. {% endhint %} ## Main Parameters To use Virtual Model, you'll need to use the following parameters: ### `virtualModel.mode` To enable Virtual Model, set the parameter `virtualModel.mode` to `ai.auto`. ### `virtualModel.model` The parameter `virtualModel.model` lets you control the likeness of the model. You can either use a pre-set model or a custom one. To use a **pre-set model**, set the parameter `virtualModel.model.preset.name` to the name of the pre-set model that you want to use.
List of pre-set models
Cover image
avery01_avery.jpg
sam02_sam.jpg
taylor03_taylor.jpg
kendall04_kendall.jpg
jordan05_jordan.jpg
casey06_casey.jpg
maya08_maya.jpg
reece09_reece.jpg
lena10_lena.jpg
julia11_julia.jpg
jackson12_jackson.jpg
sophia13_sophia.jpg
emma14_emma.jpg
ava15_ava.jpg
zoe16_zoe.jpg
fiona17_fiona.jpg
To use a **custom model**, you will need to provide an image of that model using either the parameter `virtualModel.model.custom.imageFile` or `virtualModel.model.custom.imageUrl`. {% hint style="info" %} The parameter `virtualModel.model.custom.imageFile` is only available when using the [POST endpoint](/image-editing-api-plus-plan/quickstart-guide#post-endpoint). {% endhint %} By default, this parameter will be set to `virtualModel.model.preset.name=avery`. ### `virtualModel.scene` The parameter `virtualModel.scene` lets you control the environment in which the model will be placed. You can either use a pre-set scene or a custom one. {% hint style="warning" %} To keep the scene generated around the virtual model, please also set the parameters `removeBackground=false` and `referenceBox=originalImage`. {% endhint %} To use a **pre-set scene**, set the parameter `virtualModel.scene.preset.name` to the name of the pre-set scene that you want to use.
List of pre-set scenes
Cover image
random01_random.jpg
street02_street.jpg
bedroom03_bedroom.jpg
sunset04_sunset.jpg
factory05_factory.jpg
studio06_studio.jpg
coloredstudio07_coloredstudio.jpg
concretestudio08_concretestudio.jpg
beach09_beach.jpg
tropical10_tropical.jpg
library11_library.jpg
forest12_forest.jpg
businessdistrict13_businessdistrict.jpg
countryside14_countryside.jpg
flowers15_flowers.jpg
goldenlight16_goldenlight.jpg
mountain17_mountain.jpg
pool18_pool.jpg
latincity19_latincity.jpg
cafe20_cafe.jpg
asiancity21_asiancity.jpg
nightlights22_nightlights.jpg
desert23_desert.jpg
To use a **custom scene**, you will need to provide an image of that scene using either the parameter `virtualModel.scene.custom.imageFile` or `virtualModel.scene.custom.imageUrl`. {% hint style="info" %} The parameter `virtualModel.scene.custom.imageFile` is only available when using the [POST endpoint](/image-editing-api-plus-plan/quickstart-guide#post-endpoint). {% endhint %} By default, this parameter will be set to `virtualModel.scene.preset.name=random`. ### `virtualModel.pose` The parameter `virtualModel.pose` lets you control the pose of the model. You can pick between a list of pre-set poses:
List of pre-set poses
Cover image
random01_random.jpeg
standing02_standing.jpeg
34turn03_34turn.jpeg
powerstance04_powerstance.jpeg
walkingforward05_walkingforward.jpeg
handinpocket06_handinpocket.jpeg
crossedarms07_crossedarms.jpeg
back08_back.jpeg
overtheshoulder09_overtheshoulder.jpeg
seated10_seated.jpeg
adjustingclothing11_adjustingclothing.jpeg
playfulspin12_playfulspin.jpeg
By default, this parameter will be set to `virtualModel.pose=random`. ## Which resolutions are supported? By default, Virtual Model will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Additional Parameters ### `virtualModel.additionalProductImages[]` 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. To provide these images, use either the parameter `virtualModel.additionalProductImages[].imageFile` or `virtualModel.additionalProductImages[].imageUrl`. {% hint style="info" %} The parameter `virtualModel.additionalProductImages[].imageFile` is only available when using the [POST endpoint](/image-editing-api-plus-plan/quickstart-guide#post-endpoint). {% endhint %} ### `virtualModel.prompt` Optional text prompt to guide the generation style. Example: `street style` ### `virtualModel.size` The output size and aspect ratio of the generated image. Default: `PORTRAIT_HD_3_2` Possible values: `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` # Virtual Try-On {% embed url="" %} ## Overview Virtual Try-On lets you automatically place a piece of clothing on an a person:
(original image)(edited image)


+




+



+

{% hint style="info" %} Virtual Try-On is meant to be used with images that feature clothing items. {% endhint %} ## Main Parameters Virtual Try-On shares the same parameters than [Virtual Model](/image-editing-api-plus-plan/virtual-model), but used in a different way. To use Virtual Try-On, you'll need to use the following parameters: ### `virtualModel.mode` To enable Virtual Try-On, set the parameter `virtualModel.mode` to `ai.auto`. ### `virtualModel.model` The parameter `virtualModel.model` lets you control the likeness of the person wearing the clothing. The image of that person is provided using either the parameter `virtualModel.model.custom.imageFile` or `virtualModel.model.custom.imageUrl`. {% hint style="info" %} The parameter `virtualModel.model.custom.imageFile` is only available when using the [POST endpoint](/image-editing-api-plus-plan/quickstart-guide#post-endpoint). {% endhint %} ### `virtualModel.scene` The parameter `virtualModel.scene` lets you control the environment in which the person will be placed. You can either use a pre-set scene or a custom one. {% hint style="warning" %} To keep the scene generated around the virtual model, please also set the parameters `removeBackground=false` and `referenceBox=originalImage`. {% endhint %} To use a **pre-set scene**, set the parameter `virtualModel.scene.preset.name` to the name of the pre-set scene that you want to use.
List of pre-set scenes
Cover image
random01_random.jpg
street02_street.jpg
bedroom03_bedroom.jpg
sunset04_sunset.jpg
factory05_factory.jpg
studio06_studio.jpg
coloredstudio07_coloredstudio.jpg
concretestudio08_concretestudio.jpg
beach09_beach.jpg
tropical10_tropical.jpg
library11_library.jpg
forest12_forest.jpg
businessdistrict13_businessdistrict.jpg
countryside14_countryside.jpg
flowers15_flowers.jpg
goldenlight16_goldenlight.jpg
mountain17_mountain.jpg
pool18_pool.jpg
latincity19_latincity.jpg
cafe20_cafe.jpg
asiancity21_asiancity.jpg
nightlights22_nightlights.jpg
desert23_desert.jpg
To use a **custom scene**, you will need to provide an image of that scene using either the parameter `virtualModel.scene.custom.imageFile` or `virtualModel.scene.custom.imageUrl`. {% hint style="info" %} The parameter `virtualModel.scene.custom.imageFile` is only available when using the [POST endpoint](/image-editing-api-plus-plan/quickstart-guide#post-endpoint). {% endhint %} By default, this parameter will be set to `virtualModel.scene.preset.name=random`. ### `virtualModel.pose` The parameter `virtualModel.pose` lets you control the pose of the person. You can pick between a list of pre-set poses:
List of pre-set poses
Cover image
random01_random.jpeg
standing02_standing.jpeg
34turn03_34turn.jpeg
powerstance04_powerstance.jpeg
walkingforward05_walkingforward.jpeg
handinpocket06_handinpocket.jpeg
crossedarms07_crossedarms.jpeg
back08_back.jpeg
overtheshoulder09_overtheshoulder.jpeg
seated10_seated.jpeg
adjustingclothing11_adjustingclothing.jpeg
playfulspin12_playfulspin.jpeg
{% hint style="info" %} For a Virtual Try-On, we recommend setting `virtualModel.pose=standing` {% endhint %} By default, this parameter will be set to `virtualModel.pose=random`. ## Which resolutions are supported? By default, Virtual Try-On will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Additional Parameters ### `virtualModel.additionalProductImages[]` 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. To provide these images, use either the parameter `virtualModel.additionalProductImages[].imageFile` or `virtualModel.additionalProductImages[].imageUrl`. {% hint style="info" %} The parameter `virtualModel.additionalProductImages[].imageFile` is only available when using the [POST endpoint](/image-editing-api-plus-plan/quickstart-guide#post-endpoint). {% endhint %} ### `virtualModel.prompt` Optional text prompt to guide the generation style. Example: `street style` ### `virtualModel.size` The output size and aspect ratio of the generated image. Default: `PORTRAIT_HD_3_2` Possible values: `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` # AI Beautifier ## Overview AI Beautifier improves the quality of the main subject by creating a more aesthetically pleasing visual. To beautify an image, set the argument `beautify.mode` to either the value: * `ai.auto` for a result that follows the aesthetic product pack shot imagery * `ai.food` for a result tailored to the specifics of food imagery (e.g. placing the subject on a plate) * `ai.car` for a result tailored to the specifics of car imagery (e.g. removing unwanted reflections) AI Beautifier can also be used in conjunction with other features like [Positioning](/image-editing-api-plus-plan/positioning), [AI Shadows](/image-editing-api-plus-plan/ai-shadows) and [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds). {% hint style="warning" %} AI Beautifier creates a re-imagined visual of the main subject: please note that alterations can be introduced. {% endhint %} | *(original image)* | *(beautified image)* | (*beautified image and* [*AI Shadows*](/image-editing-api-plus-plan/ai-shadows)*)* | (*beautified image and* [*AI Backgrounds*](/image-editing-api-plus-plan/ai-backgrounds)*)* | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FZrl3xPuZjV7Vgs4xmRP2%2Fa2bc94f05b46f9d1d023671c2cdca5289a7441aae43ae0fdff656e827f387b71.jpeg.webp?alt=media\&token=69b807d8-cd7b-4430-87f8-9227177de62c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FjVwNXEMRkcX9Q0r1mKey%2Fa2bc94f05b46f9d1d023671c2cdca5289a7441aae43ae0fdff656e827f387b71.jpeg.png?alt=media\&token=fdc5e1b5-51a5-4ff0-8982-0552a54cc672) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F5lVPZyqByH2OZyeWD8hB%2Fperfume_shadow.png?alt=media\&token=4b3181b8-f8b3-4826-943d-e6519ba05fa0) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FpgWaBvf2PvicN4tSmYAE%2Fperfume_backgound.png?alt=media\&token=dca05250-7dc6-4721-9e75-d779753761cc) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FiQ0bpH7KUaIO3stV9C70%2Fshirt.png?alt=media\&token=46d80010-b008-4633-a19f-fe213c56c7a8) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FeO3ldXQzhpVEe9p8MvBh%2Fshirt_beautifier.png?alt=media\&token=9eb3f2c2-ebf9-4b5d-8987-742871851fb7) |
|
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FF7jyrfnytwpfIlXn1QeP%2FScreenshot%202025-09-26%20at%2014.39.07.png?alt=media\&token=d50f167f-c6ff-4228-a04b-11de5988b28f) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUdUauzCEHpRZhblPth3c%2Fpasta_beautifer.png?alt=media\&token=d8fcdde9-8533-44d3-8072-133c465c7b6c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FyBjjIIW2rntYylNnfGjk%2Fpasta_shadow.png?alt=media\&token=3f38544f-a006-46c1-a789-ce1432e3f4d7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F4lRG3fRDIpKORL1S9Nuv%2Fpasta_background.png?alt=media\&token=38631822-5e65-46cc-a784-c01402ebd312) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FnNlJER2JYzo65ePr2tFE%2FScreenshot%202025-09-26%20at%2014.39.15.png?alt=media\&token=3fbdcc70-65a6-4e86-b9f4-7716330ac4ba) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FoaUgHaJ0gf5z3k0OeOcf%2Fpizza_beautifier.png?alt=media\&token=4304a574-e1e3-442c-80e7-cfd949994a6e) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUDvBc86nP5ZtiOc58Lcn%2Fpizza_shadow.png?alt=media\&token=926ff718-4be5-4257-b23f-cdcdd7dfdfc6) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fa5CvMZUDZxCBYcZIUp2u%2Fpizza_background.png?alt=media\&token=26895cb5-0857-40a0-80a7-f38ef6852566) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FiORYJfVqvN9cOIkOnWpw%2Fphoto-1648311975873-f920306ba958.jpg?alt=media\&token=21bcb837-1c97-4b58-989b-b027ccd9680d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FZy19bxR4IhOmDGLSC2XT%2Fphoto-1648311975873-f920306ba958.png?alt=media\&token=035ef41f-705f-4db1-846e-9d022ac3a85d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FeW9gNt6mZUzzZX3yJ1Qg%2Fphoto-1648311975873-f920306ba958.png?alt=media\&token=f73d2b01-3404-4111-a416-5befce68031a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FsnIOITWJiSDFg0k1UHeJ%2Fphoto-1648311975873-f920306ba958.png?alt=media\&token=4e313b0a-c5dd-4925-9db0-d7b132c92481) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fe9TgGPctZSJv6BLVTpRM%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.jpg?alt=media\&token=de938c37-c9d7-485e-9b9d-8976a979ef7b) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fd0Pa6hZtpsx4HnGTBcJ2%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.png?alt=media\&token=babf55b7-77a0-454d-a3c3-ed04226b4ad7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F3ZHD58NFpABMrOzA4KZc%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.png?alt=media\&token=b06845d8-a35d-42e9-a7cc-430d7bdc9970) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F7zriZ3OPUaMwQKnNX4OI%2FGenerated%20Image%20February%2024%2C%202026%20-%204_54PM.jpg.png?alt=media\&token=7ea3cdbe-3dc1-40e6-ad99-204813bdd074) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FCFLXnIS019iu0pha2xd2%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.jpg?alt=media\&token=b140875c-864b-43cb-8e5a-45b878cb508a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F03HU52cf9Mtb6h2SRHR1%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.png?alt=media\&token=19dab660-f5ac-4952-9dc4-49d44adb8fc7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FxK9XN882JV1aH6LogqrS%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.png?alt=media\&token=cce86b43-dbed-4903-adfd-c0978bf2d898) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FcfJVh5ROMvnFyujn2NZd%2FGenerated%20Image%20February%2024%2C%202026%20-%204_51PM.jpg.png?alt=media\&token=2702de03-e261-4ae8-9cc3-9fb4e011d064) | If you want to give it a try, here's the code to reproduce the examples in the second column above: #### `beautify.mode=ai.auto` ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form beautify.mode=ai.auto \ --output result-ai-beautifier.png ``` Try it now! #### `beautify.mode=ai.food` ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form beautify.mode=ai.food \ --output result-ai-food-beautifier.png ``` Try it now! #### `beautify.mode=ai.car` ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form beautify.mode=ai.car \ --output result-ai-car-beautifier.png ``` Try it now! ## Which resolutions are supported? By default, AI Beautifier will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Additional Parameters ### **`beautify.seed`** If you make several calls to the Image Editing API with the same image, you will notice that it will generate a different beautified subject every time. In order to reduce the randomness, you can set a fixed value for the seed that the API's random generator will use. The value of the argument `beautify.seed` can be any positive integer. If you provide a value for `beautify.seed`, then the API should produce similar-looking beautified subject for the same image. In the examples above, the value used was `beautify.seed=117879368`. # AI Backgrounds ## Overview The Image Editing API allows you to easily create new backgrounds for your images. This feature works by using Generative AI to dynamically create new backgrounds, that perfectly match the subject of the original picture. Here's an example of how you can use AI Backgrounds to personalize product images at scale: {% embed url="" %} {% hint style="info" %} You can see even more examples of AI Backgrounds in our [competitors benchmark](/resources/ai-backgrounds-competitors-benchmark-claid.ai-phot.ai-bria.ai). {% endhint %} ## Model selection There are currently three models for generating background images using AI: * The current default model, v3 (version identifier `3`) * Our new model, Studio (version identifier `background-studio-beta-2025-03-17`) * Our previous model, v2 (version identifier `2`). This model has been deprecated, there is currently no timeline for its removal from the API. {% hint style="info" %} We recommend using the model `background-studio-beta-2025-03-17`, which will deliver the best results. {% endhint %} To use a specific model, add the following HTTP header in your request when calling the Image Editing API: `pr-ai-background-model-version: background-studio-beta-2025-03-17`, where `background-studio-beta-2025-03-17` is the version identifier of the model you want to use. The Studio model is better at generating photorealistic images: object shapes are more defined and textures look better. It is also great at generating props such as cutlery or surrounding objects for your scene. It's a bit slower than our current model. Here's an example of the difference in result between the current model and the new model:
Old model (v2)Current model (v3)New model (Studio)
## Text Prompt To add an AI Background using a text prompt, set the argument `background.prompt` with a description of the new background that you want to generate:
(original image)
background.prompt="the image displays a pair of blue sneakers on a tropical beach on a bright day with a slightly blurred background of the ocean"
background.prompt="the image features a pair of blue sneakers on a boulder with a breathtaking mountain view in the background"
background.prompt="the image depicts a pair of blue sneakers placed within a bustling city street background. The atmosphere is urban and replete with architectural details"
If you want to give it a try, here's the code to reproduce the first example above: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'background.prompt="the image displays a pair of blue sneakers on a tropical beach on a bright day with a slightly blurred background of the ocean"' \ --output result-ai-background.png ``` {% endcode %} Try it now! ### `background.seed` If you make several calls to the Image Editing API with the same image and the same prompt, you will notice that it will generate a different background each time. This is great when you're looking for inspiration, but it might become an issue when you need consistency. In order to reduce the randomness, you can set a fixed value for the seed that the API's random generator will use. The value of the argument `background.seed` can be any positive integer. If you provide a value for `background.seed`, then the API should produce similar-looking backgrounds for the same prompt. The iOS, Android and Web versions of Photoroom always use the same seeds for the first 4 generated background options they present to the user. You can use the same values if you want to have results similar to that of the Photoroom apps: `117879368`, `55994449`, `48672244` and `65080068`. ### `background.expandPrompt.mode` Longer prompts tend to give better results than shorter prompts. This is particularly true when [using our most recent model](#important-model-selection). By default, we **automatically improve prompts** by expanding them into a longer form and integrating a description of the main subject. But if you prefer us not to, it's possible to disable this behavior: set the argument `background.expandPrompt.mode` to `ai.never` so that your prompt doesn't get automatically expanded:

background.prompt="on a beach"

automatically expanded prompt: "A pair of blue sneakers is casually placed on top of a weathered brick walkway leading towards the sandy beach. The sun is setting, casting a warm, golden glow over the scene, creating long shadows that stretch towards the calm ocean waves. Seagulls can be seen gliding in the distance, adding a touch of tranquility to the coastal setting."

background.prompt="on a beach"

and

background.expandPrompt.mode=ai.never

If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'background.prompt="on a beach"' \ --form 'background.expandPrompt.mode="ai.never"' \ --output result-with-expanded-prompt.png ``` Try it now! ### `background.negativePrompt` {% hint style="warning" %} This parameter only has an effect when [using the model](#model-selection) with version identifier `2`. With all other versions of the model, setting `background.negativePrompt` won't have any effect on the result. {% endhint %} `background.negativePrompt` allows you to refine your generated background by specifying elements our AI won’t include in the final image. For example, if you'd like a wedding-themed background without any flowers in view, consider a `background.negativePrompt` such as `"flowers"`:
## Image Prompt
Alternatively to providing a text prompt, you can also use an existing image as the prompt to generate an AI Background. To use this feature, set either the argument `background.guidance.imageFile` or `background.guidance.imageUrl`: | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FlR2xKxVU3FOeO9TsBSOO%2Foriginal.jpeg?alt=media\&token=1fa53df3-8c38-4a3a-a7c9-8a59c3a66f8c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FPvUi6y7FqySznoAUf27M%2Finspiration.jpg?alt=media\&token=1080133a-e69d-4917-95cf-fdb06b364f2d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FN9zt58DQJn7NWo1xWk27%2Fresponse-4.png?alt=media\&token=1b9b3b70-dc40-4c8a-a17d-99d986dae65b) | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | o*riginal image* | *guidance image* | *result* | If you want to give it a try, here's the code to reproduce it: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/original-image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'background.guidance.imageFile=@"/path/to/guidance-image.jpeg"' \ --output result-ai-background-with-guidance.png ``` {% endcode %} ### `background.guidance.scale` Additionally, you can use the parameter `background.guidance.scale` to control how closely the generated background will be matching the guidance image. 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. (Default value is `0.6`)
background.guidance.scale=0.2
background.guidance.scale=0.4
background.guidance.scale=0.6
background.guidance.scale=0.8
background.guidance.scale=1.0
## Using Text and Image Prompts together It's possible to provide both a Text prompt and an Image prompt in the same API call. To use both type of prompts together, set the arguments `background.prompt` and `background.guidance.imageFile` (or `background.guidance.imageUrl`) in your API call. Using the [same Image prompt than above](#image-prompt), here are two examples using different Text prompts:

background.guidance.imageFile=@"/path/to/guidance-image.jpeg"

and

background.prompt="A bottle of perfume 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."

background.guidance.imageFile=@"/path/to/guidance-image.jpeg"

and

background.prompt="the image displays a small bottle with a pink substance on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry."

### Relative weight of the Text and Image Prompts You can control the relative weight of the Text and Image prompts through the argument `background.guidance.scale`. Conceptually, the relative weight follows this formula: *Final prompt* = *Text prompt* + `background.guidance.scale` \* *Image prompt* {% hint style="info" %} In the [two examples above](#using-text-and-image-prompts-together), `background.guidance.scale` had been set to `1.0` {% endhint %} ## How to write a high-quality prompt To use this feature, you will need to set the argument `background.prompt`. The argument `background.prompt` is a textual description of what the new background should look like. It can feel challenging to write a good prompt. However, we have a way to provide you with good examples: 1. Go to the [Photoroom Web App](https://app.photoroom.com/create) and upload an image for which you'd like to generate a new background 2. Open *Backgrounds > AI Backgrounds* on the top panel * The first 2 results are backgrounds that have been generated specifically for your image, and the prompt is visible below the tile! * And if you tap on any of the “scenes”, you'll see the full prompt on top. You can even edit it to see how variations of the prompt would impact the generated background! {% hint style="warning" %} If you want a result that looks similar to the 4 options generated by the apps, make sure that, in addition to the `background.prompt`, you also use the [same `background.seed` than the apps](#background.seed). {% endhint %} # AI Expand ## Overview
The Image Editing API allows you to expand an input image. AI Expand works by seamlessly expanding the background to fill every empty pixel of the result image. To expand an image, set the argument `expand.mode` to the value `ai.auto`: | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fspe7s1H6t3zi9YYktv7o%2Finput.png?alt=media\&token=da2cf808-1949-4874-9ea2-49e625cd76a9) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FNk3rLrl1InSZ69BTS5bI%2Fai-expand.png?alt=media\&token=a9733a75-4ef3-4b08-a165-e9e834463247) | | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *(original image)* | *(expanded image)* | If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'outputSize="1920x1080"' \ --form 'referenceBox="originalImage"' \ --form 'removeBackground="false"' \ --form 'expand.mode="ai.auto"' \ --output result-ai-expand.png ``` Try it now! {% hint style="warning" %} In order to expand an image, you need to either: * set `removeBackground` to `false` * provide a `background.imageUrl` {% endhint %} ## Additional Parameters ### **`expand.seed`** If you make several calls to the Image Editing API with the same image, you will notice that it will generate a different expanded background each time. This is great when you're looking for inspiration, but it might become an issue when you need consistency. In order to reduce the randomness, you can set a fixed value for the seed that the API's random generator will use. The value of the argument `expand.seed` can be any positive integer. If you provide a value for `expand.seed`, then the API should produce similar-looking backgrounds for the same image. # AI Ironing {% embed url="" %} ## Overview The Image Editing API can turn images of wrinkly clothing into freshly pressed clothing. To iron clothing in an image, set `ironing.mode` to `ai.auto`.
(original image)(edited image)
{% hint style="info" %} AI Ironing is meant to be used with images that feature clothing items. Please note that alterations can be introduced. {% endhint %} If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form ironing.mode=ai.auto \ --form removeBackground=false \ --output ironed.png ``` Try it now! ## Additional Examples
(original image)(edited image)
# AI Relight ## Overview The Image Editing API allows you to correct lighting issues, such as over-exposition or under-exposition, by re-lighting the input image. To re-light an image, set the argument `lighting.mode` to one of these three values: * `ai.auto` for the lighting to be automatically adjusted * `ai.preserve-hue-and-saturation` for the lighting to be adjusted while keeping color hues and saturations as close as possible to the original image * this can be useful for product images, where maintaining color accuracy is important * `ai.optimize-portrait` for the lighting to be optimized for human portrait photography. Specifically, this mode acts on the subject by: * enhancing light intensity * removing blemishes * applying subtle teeth whitening * preserving freckles and skin characteristics {% hint style="warning" %} Please note that AI Relight is currently limited to images with a maximum resolution of 3,500x3,500 pixels. Known issue: we don't recommend using AI Relight along with [AI Expand](/image-editing-api-plus-plan/ai-expand) in a same API call. {% endhint %} ## Examples Here are some examples of what re-lighting can achieve by setting `lighting.mode=ai.auto`: | *Original* | *Re-lighted* | | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FNkhQrGGLHn7fbFUuhgox%2Foverexposed-1.jpg?alt=media\&token=7cb6f836-8e3d-4e5a-a1fb-a74833fca0fa) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FTQyVwWcyHTCLJEBqxMaB%2Fresponse.png?alt=media\&token=475a90d4-05cb-4f70-97be-13789a99526c) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FHqLZqGZJDcbqMkZx41XD%2Foverexposed-2.jpg?alt=media\&token=5f8a71fd-0e89-4705-97b9-78d49ef3a16f) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fz9MdDWZ4O5iXMaydjDtU%2Fresponse.png?alt=media\&token=d472b6ad-d693-4178-a3e1-71e6d34b6fbc) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FMkGu8Kmh2eks1Kx0b2oW%2Funderexposed-1.jpg?alt=media\&token=60a1c5f1-08d7-4931-b5bc-93d0b30e45be) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F7a2AfCN0mQm0OgIG0s2Z%2Fresponse.png?alt=media\&token=73bea3ff-ee05-4aed-b85f-1adca2dccffd) | If you want to give it a try, here's the code to reproduce the examples above: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form referenceBox=originalImage \ --form maxWidth=2000 \ --form maxHeight=2000 \ --form removeBackground=false \ --form lighting.mode=ai.auto \ --output with-re-lighting.png ``` {% endcode %} Try it now! And here are examples of the output produced by the different values for `lighting.mode`, for different use-cases: ### Second-hand marketplace | *Original* | `lighting.mode=ai.auto` | `lighting.mode=ai.preserve-hue-and-saturation` | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBXwWQt1XsvEOGvTaQe1M%2Fm43233153640_1.jpg?alt=media\&token=9f48c27c-38af-4fd9-8aff-91291373d0f3) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FgvtEHzukKeAYQefnLIif%2Fold.png?alt=media\&token=0fda2e47-127b-4487-a68c-8c95d1151584) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FCCP27LiwsEj16GadhnMQ%2Fnew.png?alt=media\&token=ca4b3063-018e-464c-a5da-acb0edefdc61) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fwp0p30v9CVVbGpBNSC7Q%2Fm42770846513_1.jpg?alt=media\&token=e589891f-fccc-4fe7-a5aa-3180dbae58d2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FoGH7PKtEqmcQ7Q2c3IOI%2Fm42770846513_1.png?alt=media\&token=3d11ecfb-a50a-4f9e-af35-07b21ec7844a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FkgINLXF3qoE2U3HbkV43%2Fm42770846513_1.png?alt=media\&token=fd49f0aa-fc37-4a9d-bcdb-4a5703ad2758) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FcYyU6flKP8ARTJtuadRH%2Fm63703188619_1%20\(1\).jpg?alt=media\&token=8cc24c3c-3b84-4625-8ea0-4fcf471d02b2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FezLGijQb2hihrjasrwTg%2Fm63703188619_1%20\(1\).png?alt=media\&token=a108a7f7-45d6-4e19-8403-6e2cd9dae415) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fmi94UYhBHPbMzhWHdlSq%2Fm63703188619_1%20\(1\).png?alt=media\&token=cc7f28ec-b265-4a8c-84f2-93dd8a59469c) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FdfM0951WkWmBpTskwoIl%2Fm84390327592_1.jpg?alt=media\&token=8919997a-d67c-4d97-8201-31bb6361f8a3) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F6OFjybEH4X3lJJI8kTub%2Fm84390327592_1.png?alt=media\&token=3e0d35b1-8450-45c1-9b7b-15af38680305) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FgKKrdp2hv0BnD6zZPsxJ%2Fm84390327592_1.png?alt=media\&token=c79d4e11-d925-4970-bc43-3ab44ca487af) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FUzAdpQlqhyWMfI012OPN%2Fm38165968726_1.jpg?alt=media\&token=c0ac1949-3872-46cd-a423-9db98ade14f7) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FncgQDJfvsDRECtXpY6MG%2Fm38165968726_1.png?alt=media\&token=aa437710-07bd-4e39-8b63-2698881e15d5) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FrOiF44wJEgv32PyiXeu4%2Fm38165968726_1.png?alt=media\&token=330d6df5-291d-4105-a71b-dc7e82f58c2d) | ### School portraits | *Original* | `lighting.mode=ai.auto` | `lighting.mode=ai.preserve-hue-and-saturation` | `lighting.mode=ai.optimize-portrait` | | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FASgpNDCI6v0qMaQpnkVb%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-2.png?alt=media\&token=5159dace-6aec-4d7b-8921-775fca8d57f5) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FIcZHrkSYPIp8wb1vPJn1%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-2.png?alt=media\&token=687fd07b-3917-4cf3-acb6-def9f8d37535) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FcN3HIgnv0QdycDOVtswZ%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-2.png?alt=media\&token=353ac79d-ea54-4100-9132-b63e72fd7c4a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FEunvWhrZyj2paP0dnqHz%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-2.png?alt=media\&token=f24c3afb-3dee-4417-b27a-140262f226d5) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FN8wmNszTolDow3Y7JVFL%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-4.png?alt=media\&token=2742df9f-2978-411b-8ac2-4982ef02b01d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FxClZrAxb3yqRUKhHyUy0%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-4.png?alt=media\&token=987e907b-ddfb-4ff3-b19d-44b75780d22f) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F17l6giOCktz2mJIqvVyY%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-4.png?alt=media\&token=00313401-d5b1-4579-9f87-caf2fe4ad6da) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FkRyrAZIS2IzmGyWHUuXu%2FGenerated%20Image%20December%2022%2C%202025%20-%203_19PM-4.png?alt=media\&token=413864f8-70de-44b2-a1e9-aa5acc5ed9b2) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FSVVATSvNBDtKeZ9yeYtm%2FGenerated%20Image%20December%2022%2C%202025%20-%203_20PM.png?alt=media\&token=5841ff1f-3991-4e5b-9b4b-75b3da2dd6bf) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FfflImDU7wHmgIEmhzAil%2FGenerated%20Image%20December%2022%2C%202025%20-%203_20PM.png?alt=media\&token=46314156-b10f-47a3-b8ca-e9c01c4985f2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FiIv5fwgtkJEqBrmnlTHh%2FGenerated%20Image%20December%2022%2C%202025%20-%203_20PM.png?alt=media\&token=3130262c-3eae-4112-8637-894677b76a30) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F5IF7f3F46oisNmPVGY5H%2FGenerated%20Image%20December%2022%2C%202025%20-%203_20PM.png?alt=media\&token=a5fde7f0-293b-44e5-8506-cbedbbf825f1) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FW0GpfCdy8w1YnvXdWqe6%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-3.png?alt=media\&token=a37c9461-ab3a-426d-97a8-b81ed133efa2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FXiJZCrBRLxZovQsTuTTG%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-3.png?alt=media\&token=b5609306-626b-4ba8-9bca-e2b7d90a0410) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fjgt0ODhoheGVGWxgnM3T%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-3.png?alt=media\&token=dd7c6f2d-3533-4087-ae9e-106b1e7cab54) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F9wA78iaysUngziyNZasw%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-3.png?alt=media\&token=4e3d9642-5f8d-4840-a177-1ede7eb2edd6) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FXp1n6EzMo19rYlFfAxHr%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM.png?alt=media\&token=fd0f02df-5288-45f3-8099-256b15f3364d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FLNNElj2rtI7r34veZt2F%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM.png?alt=media\&token=ef5b08ca-ba2b-4426-a139-5babd15b9027) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FSFZbu9thTybUodAIadNL%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM.png?alt=media\&token=e5bc055b-7fa3-4fc8-b3fc-b9d1e0dbf831) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FJcMw7yP6BIj1dBO1sMyQ%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM.png?alt=media\&token=a3bb2a7c-1ae1-4d87-bd34-6c4f60696bed) | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FtxqzOSnEnTSFvHmVEU0m%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-2.png?alt=media\&token=5353eebc-de1e-4ba7-b4ce-5bb4e11977cd) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Frf90BSz0vN53xVHjURvV%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-2.png?alt=media\&token=508250c5-8db2-4eba-9296-1afe7c2b0d21) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F1oF5FEucGt00nxXlYlPF%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-2.png?alt=media\&token=e10e8701-aa62-4094-a7dc-534dfae05826) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQIGJWcG6Zu3rbMHAIFFx%2FGenerated%20Image%20December%2022%2C%202025%20-%203_22PM-2.png?alt=media\&token=62328282-4845-430b-ae41-a0c71af36907) |
### Food industry | *Original* | `lighting.mode=ai.auto` | `lighting.mode=ai.preserve-hue-and-saturation` | | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FxmSM0Omx1jAWCx2YEEh1%2Ffood-raviolis_airelight_preservehueandsat.png?alt=media\&token=578e9814-eb14-42a0-9c76-6ec1c710b71d) | | | | | | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FJBrPwcYGsGHYgPCX5hjT%2Ffood-spaghettis_airelight_preservehueandsat.png?alt=media\&token=7ba96821-f946-4cd5-9fd3-1fdc104dfab4) | ### Car industry | *Original* | `lighting.mode=ai.auto` | `lighting.mode=ai.preserve-hue-and-saturation` | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FDM1KQSbVfRxEwfTkpNEh%2Fcars-blue-car-racing_airelight_auto%20Medium.png?alt=media\&token=df1cbcd4-4b8b-4034-b1f7-ca5576edfcdf) | | | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FHQsC5UjA7d67bo0QG3Ku%2Fcars-grey-car-spring_airelight_preservehueandsat%20Medium.png?alt=media\&token=da2d818c-c136-4e20-aa97-b4c6c24b99bb) | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FxsJX3AlbljVUgOIUy1cj%2Fcars-red-car_airrelight_auto.png?alt=media\&token=ca783bb9-d782-4033-9728-a77763998884) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FmkZ4Mxuf3BUjS0cOR1AP%2Fcars-red-car_airelight_preservehueandsat.png?alt=media\&token=26a07def-84bb-430f-8ae2-e7a3ecaa73bd) | ### Luxury industry | *Original* | `lighting.mode=ai.auto` | `lighting.mode=ai.preserve-hue-and-saturation` | | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FPilVAwhVkd5xHsPns5GH%2Fluxury-earrings_airelight_auto.jpeg?alt=media\&token=51f9463d-06ec-4552-95b6-5090cf140631) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fe8x8uDYaYRcFQ67Y2nFZ%2Fluxury-earrings_airelight_preservehueandsat.jpeg?alt=media\&token=374b9278-2c61-4be7-a2ce-19a6ec6fdd81) | | | | | | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F7Ll1nXN5mh9FYeHqen6z%2Fluxury-bracelet_airelight_auto.jpeg?alt=media\&token=3a58f703-33cb-429e-be98-a9e157e088e5) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FlJz20bNGaubIHICPXKyT%2Fluxury-bracelet_airelight_preservehueandsat.jpeg?alt=media\&token=a9c0ea7a-9ae8-49f0-9850-8ae585f2808c) | # AI Shadows The Image Editing API allows you to add realistic shadows to the main subject of the input image. Here's a demo of how you can use AI Shadows to create studio quality product images at scale: {% embed url="" %} {% hint style="info" %} The tool used in the video is available here: . This tool will consume API image, we recommend using [Sandbox mode](/image-editing-api-plus-plan/sandbox-mode) if you want to test for free. {% endhint %} ## New AI Shadows Model ### Overview We've shipped a new model for AI Shadows that gives you complete control over the softness, intensity and position of the shadow. To use this new model you will need to: 1. add the HTTP header `pr-ai-shadows-model-version: 2026-04-15` to your API call 2. set the parameter `shadow.mode` to `ai.auto-with-overrides` By default, this new model will automatically determine the best values for the softness, intensity and position of the shadow. However, you also have access to 5 parameters that let you override each of these dimensions, to control the appearance of the shadow: * `shadow.softnessOverride`, controls whether the shadow will have hard or soft edges * `shadow.intensityOverride`, controls how dark the shadow will be * `shadow.spreadOverride`, controls how long the shadow will be * `shadow.directionOverride`, controls the direction of the shadow relative to the subject * `shadow.subjectPoseOverride`, controls whether the subject is laying flat or standing upright Under-the-hood, these parameters allow you to precisely control how the light source should be positioned relative to the subject:
### Preview Tool We've built a tool that will help you: 1. easily visualize the impact that each of these override parameters has 2. define the set of parameter values that will produce the result you're looking for
Try it now! {% hint style="info" %} This tool will consume API image, we recommend using [Sandbox mode](/image-editing-api-plus-plan/sandbox-mode) if you want to test for free. {% endhint %} ### Auto Mode When none of the 5 override parameters have been set, the model will fully determine the best shadow appearance for each input image:

shadow.mode=ai.auto-with-overrides

This can be useful because it enables you to immediately start using the feature, without needing to decide on a value for each override parameter If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --output result-with-auto-shadow.png ``` Try it now! If needed, it's also possible to set a value for some of the override parameters, while letting the model determine the value of the others:

shadow.mode=ai.auto-with-overrides
shadow.intensityOverride=0.9
shadow.spreadOverride=short

### Deterministic Mode When all 5 override parameters have been set, the appearance of the shadow becomes fully deterministic. Doing so enables you to achieve a consistent shadow appearance at scale:

shadow.mode=ai.auto-with-overrides
shadow.softnessOverride=0.3
shadow.intensityOverride=0.8
shadow.spreadOverride=medium
shadow.directionOverride=behindLeft
shadow.subjectPoseOverride=upright

shadow.mode=ai.auto-with-overrides
shadow.softnessOverride=0.3
shadow.intensityOverride=0.8
shadow.spreadOverride=medium
shadow.directionOverride=behindRight
shadow.subjectPoseOverride=upright

If you want to give it a try, here's the code to reproduce the first example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.softnessOverride=0.3 \ --form shadow.softnessOverride=0.3 \ --form shadow.intensityOverride=0.8 \ --form shadow.spreadOverride=medium \ --form shadow.directionOverride=behindLeft \ --form shadow.subjectPoseOverride=upright \ --output result-with-deterministic-shadow.png ``` Try it now! ### Override Parameters #### `shadow.softnessOverride` Controls whether the shadow will have hard or soft edges. `0` means a very hard shadow, `1` means a very soft shadow.
(original image)

shadow.mode=ai.auto-with-overrides

shadow.softnessOverride=0.3

shadow.mode=ai.auto-with-overrides

shadow.softnessOverride=0.7

```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.softnessOverride=0.3 \ --output result.png ``` Try it now! #### `shadow.intensityOverride` Controls how dark the shadow will be. `0` means a very faint shadow, `1` means a very dark shadow.
(original image)

shadow.mode=ai.auto-with-overrides

shadow.intensityOverride=0.3

shadow.mode=ai.auto-with-overrides

shadow.intensityOverride=0.7

```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.intensityOverride=0.3 \ --output result.png ``` Try it now! #### `shadow.spreadOverride` Controls how long the shadow will be. 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. {% hint style="warning" %} When using a value in degrees, only set a numeric value, do not add the `°` character. e.g.: `45` is a valid value, `45°` is **not** a valid value {% endhint %}
(original image)

shadow.mode=ai.auto-with-overrides

shadow.spreadOverride=short

shadow.mode=ai.auto-with-overrides

shadow.spreadOverride=medium

```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.spreadOverride=medium \ --output result.png ``` Try it now! #### `shadow.directionOverride` Controls the direction of the shadow relative to the subject. 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 * `270` means the shadow is at the right of the subject. {% hint style="warning" %} When using a value in degrees, only set a numeric value, do not add the `°` character. e.g.: `45` is a valid value, `45°` is **not** a valid value {% endhint %}
(original image)

shadow.mode=ai.auto-with-overrides

shadow.directionOverride=behindLeft

shadow.mode=ai.auto-with-overrides

shadow.directionOverride=frontLeft

shadow.mode=ai.auto-with-overrides

shadow.directionOverride=frontRight

shadow.mode=ai.auto-with-overrides

shadow.directionOverride=behindRight

```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.directionOverride=frontLeft \ --output result.png ``` Try it now! #### `shadow.subjectPoseOverride` Controls whether the subject is laying flat or standing upright. 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. {% hint style="warning" %} When using a value in degrees, only set a numeric value, do not add the `°` character. e.g.: `45` is a valid value, `45°` is **not** a valid value {% endhint %}
(original image)

shadow.mode=ai.auto-with-overrides

shadow.subjectPoseOverride=flatlay

shadow.mode=ai.auto-with-overrides

shadow.subjectPoseOverride=upright

```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-shadows-model-version: 2026-04-15' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1920x1080 \ --form padding=0.15 \ --form shadow.mode=ai.auto-with-overrides \ --form shadow.subjectPoseOverride=flatlay \ --output result.png ``` Try it now! ## Previous AI Shadows Model To add a realistic shadow, set the argument `shadow.mode` with one of the following values:
(original image)shadow.mode=ai.softshadow.mode=ai.hardshadow.mode=ai.floating
{% hint style="warning" %} If you've also added an [AI Background](/image-editing-api-plus-plan/ai-backgrounds) to your image, then it's **not** recommended to also add an AI Shadow as the generated background will already include a shadow for the subject. {% endhint %} If you want to give it a try, here's the code to reproduce the examples above: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form background.color=FFFFFF \ --form outputSize=1000x1000 \ --form padding=0.1 \ --form shadow.mode=ai.soft \ --output with-realistic-shadow.png ``` {% endcode %} Try it now! # AI Text Removal The Image Editing API allows you to automatically remove any unwanted text from your images. To remove text from the input image, set the argument `textRemoval.mode` with one of the following values: * `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, discounts, etc. * `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. * `ai.all`: all text (natural and artificial) will be automatically removed. If we take the example of this image:
Here are the results you will get for each possible value of `textRemoval.mode`:
(original image)
ai.artificial
ai.natural
ai.all
If you want to give it a try, here's the code to reproduce the examples above: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@/path/to/your/image.jpg \ --form removeBackground=false \ --form referenceBox=originalImage \ --form textRemoval.mode=ai.all \ --output result-with-text-removed.png ``` {% endcode %} Try it now! # AI Uncrop ## Overview AI Uncrop reconstructs the missing parts of the main subject using only the visible portion. If the edges of the main subject are clipped, they are seamlessly extended to restore the full form. To uncrop an image, set the argument `uncrop.mode` to the value `ai.auto` and `removeBackground` to `true`: | *(original image)* | *(uncropped image)* | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQ7eExtO3Lrs1OkT53EnL%2Fpasta.webp?alt=media\&token=0c6807d7-58e6-4582-852f-7c40d87ad5f1) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fbi6AaxqPwkC8YGlVo1Xz%2Fimage.webp?alt=media\&token=8dea902a-c8a0-491f-8710-dc3efc433623) | AI Uncrop works automatically: * there’s no need to specify new dimensions or which edges to uncrop * when no edges are cropped, the main subject will not be modified (i.e. AI Uncrop will be a no-op) {% hint style="info" %} AI Uncrop is different from [AI Expand](/image-editing-api-plus-plan/ai-expand): AI Uncrop focuses specifically on the main subject of the image. {% endhint %} If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY_HERE' \ --form imageFile=@/path/to/image.png \ --form uncrop.mode=ai.auto \ --form removeBackground=true \ --output result-ai-uncrop.png ``` Try it now! {% hint style="warning" %} `removeBackground` may **not** be set to false: AI Uncrop always has to be combined with background removal. The API will later start enforcing this. {% endhint %} ## Which resolutions are supported? By default, AI Uncrop will produce outputs at a resolution of 1K (`1024x1024`). Output resolutions of 2K and 4K are available for Enterprise plans:

(original image)

(default 1K output)

(4K output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use 2K or 4K resolution, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo ## Additional Parameters ### **`uncrop.seed`** If you make several calls to the Image Editing API with the same image, you will notice that it will generate a different uncropped subject every time. In order to reduce the randomness, you can set a fixed value for the seed that the API's random generator will use. The value of the argument `uncrop.seed` can be any positive integer. If you provide a value for `uncrop.seed`, then the API should produce similar-looking subject uncroppings for the same image. # \[Preview] AI Upscale
{% hint style="warning" %} 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. {% endhint %} ## Overview The Image Editing API allows you to upscale an input image. AI Upscale increases the resolution of your input image by 4. For example, if you send an input image with resolution 300x400, then AI Upscale will turn it into an image of resolution 1200x1600. {% hint style="info" %} Please note that AI Upscale is currently limited to images with a maximum resolution of: * 1,000x1,000 pixels for the mode `ai.fast` * 512x512 for the mode `ai.slow` {% endhint %} Three upscale modes are available: * Fast mode (classic) * Fast mode (early access to new model using a header flag) * Slow mode In general, slow mode should produce results of a higher quality than fast mode. However, we do recommend that you try all modes: for specific type of images, one might give better results than the other. To upscale an image, set the argument `upscale.mode` to the value `ai.fast` or `ai.slow`. To test the new `ai.fast` model, additionally set the HTTP header `pr-ai-upscale-model-version` to `ai-upscale-2025-07-29`:
(original image)upscale.mode=ai.fastupscale.mode=ai.slowupscale.mode=ai.fast
Early access to new model
If you want to give it a try, here are the code snippets to reproduce the examples above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'removeBackground="false"' \ --form 'upscale.mode="ai.fast"' \ --output result-ai-fast.png ``` Try it now! ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'removeBackground="false"' \ --form 'upscale.mode="ai.slow"' \ --output result-ai-slow.png ``` Try it now! ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --header 'pr-ai-upscale-model-version: ai-upscale-2025-07-29' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'removeBackground="false"' \ --form 'upscale.mode="ai.fast"' \ --output result-ai-fast.png ``` Try it now! ## Additional Examples Below you can find some additional examples of using AI Upscale, with different type of images: {% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} | *(original image)* | `upscale.mode=ai.fast` | `upscale.mode=ai.slow` |

upscale.mode=ai.fast
Early access to new model

| | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FAAojYlPa8APuSGclOmYp%2F1.jpg?alt=media\&token=30c03413-6b01-4e2f-b255-bc721c5edfc5) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FHSjh9EZvGL3Nz7cRRYuu%2F1.png?alt=media\&token=cf2c4830-c7cc-4c74-9916-84f45c0918de) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FZhn0UL3UkFUtFoAUnWK9%2F1.png?alt=media\&token=9393f8f3-fdfd-47e7-ace6-3e3fc77e5a3c) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FbR4LTTvAZKZRFVhyWLMR%2F2.jpeg?alt=media\&token=dc212be2-7eb9-4411-b4ea-ca051f3316df) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FIqC1xNnjPJHAElZBmu86%2F2.png?alt=media\&token=8e581dfb-509e-4c9f-a051-b9d53a67fe2c) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F5mxUD60Y61EREPP9hTD2%2F2.png?alt=media\&token=0b638ca9-08ac-4724-ae01-c487c6befdf0) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FQ7PaKY2q4TFch3i6Jhrr%2F3.jpg?alt=media\&token=ff5c5de3-4e2d-4c78-b644-54f6b15b381a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FDSAEuAensOjaNyzZFaZt%2F3.png?alt=media\&token=ba23aeba-743a-4dff-a746-8676d043de09) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FqusYl95ajnjjqMo4AWEw%2F3.png?alt=media\&token=93f1eafd-c500-49e8-8e2d-78fe637d9571) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F3g5EgFmxQDpCZNZbGIbP%2F4.jpg?alt=media\&token=759fe616-2cd0-403c-8b78-7c4d99388b9a) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FpSWkDudb64HcA7MUovfN%2F4.png?alt=media\&token=0cac064b-3665-4038-933b-b6fae58aa211) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FEqJlrj4nDtqH69fiWVAM%2F4.png?alt=media\&token=d0d6b1bf-0fff-452f-93f7-1d358296858d) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FbLHjWDeXyapxjxq7U1FL%2F5.jpg?alt=media\&token=059b55aa-7bc5-4a59-a472-ffd325c26b54) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FOMMfa3lQarl7FejPE2sg%2F5.png?alt=media\&token=b693db8f-3286-4fbb-b54b-4013c4880be2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F3eTWBv3PcMbrKfUl9cGo%2F5.png?alt=media\&token=fe1b0bc8-c1d8-436e-9c9b-2fcbef452abc) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FBFUlnxtX5EqdqHxZwvrk%2F6.jpg?alt=media\&token=43e11ede-ab89-4173-ba66-05ba199871c2) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fu9Z3He1UmuQL2P8C6xGM%2F6.png?alt=media\&token=a94eb6e5-5d28-4230-bc3d-46ae655ad4ff) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2F5ixaVbE1lOzUaNJ3W6Uj%2F6.png?alt=media\&token=9057d023-06cc-41be-8448-c2117347b231) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2Fo96lQrRSiyJrdIRHTwb1%2F7.jpg?alt=media\&token=9412e32f-e784-4038-8587-c20a6d79044f) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FX0wS1TLckyT1kME8DlLw%2F7.png?alt=media\&token=1282232f-d184-4a15-92ba-d9462b0d32a6) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FKDtV4q90UBnDDJW4uHOS%2F7.png?alt=media\&token=a24b5407-7b5f-400b-be91-9707d6f53a15) |
| | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FjvqUhSJ7KkAflExbH2sJ%2F8.jpeg?alt=media\&token=ee9e2eb0-b45d-49c9-9581-cc15e4c35a2d) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FAGPAu6MAbJP5kLVXFvCP%2F8.png?alt=media\&token=96dcba51-a8c6-4377-ab72-e864e719fc69) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FStcbCzPm006b2oeck8sM%2F8.png?alt=media\&token=f396491b-91f3-4c69-ae8d-695364ea639a) |
| ## Advanced Upscaling Model For the most demanding use cases, an advanced model is available for Enterprise plans:

(original image)

(advanced model output)

(original image)

(advanced model output)

(original image)

(advanced model output)

(original image)

(advanced model output)

(original image)

(advanced model output)

{% hint style="info" %} Make sure to click on the images to see them in full resolution. {% endhint %} If you're interested to use this advanced model, please [contact our team to book a demo](https://www.photoroom.com/contact-sales?utm_source=apidocumentation\&utm_medium=enterprisegated). Book a demo # \[Preview] Text-Guided Segmentation {% hint style="warning" %} 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. {% endhint %} Text-Guided Segmentation allows you to have more control over which parts of the input image should be kept by the segmentation mode and which parts should be removed. Text-Guided segmentation is controlled through 3 parameters: * `segmentation.prompt`: A textual description of what the segmentation should keep. (required, comma separated values are allowed, use singular rather than plural) * `segmentation.negativePrompt`: A textual description of what the segmentation should remove. (optional, comma separated values are allowed, use singular rather than plural) * `segmentation.mode`: When set to `keepSalientObject`, the salient object of the image (i.e. what the default segmentation would have kept) will also be kept by the segmentation. (optional) {% hint style="info" %} For the arguments `segmentation.prompt` and `segmentation.negativePrompt`, please use the singular rather than the plural. (e.g. `laptop` rather than `laptops`) If you want the segmentation to keep a person, we recommend setting `segmentation.mode=keepSalientObject` rather than `segmentation.prompt=person`. (the reason why is that the `prompt` is currently is less performant when dealing with fine details, like hair) {% endhint %} To help better understand how the feature works, here are some examples:
(original image)
(default segmentation)
segmentation.prompt=laptop
segmentation.prompt=memory card

segmentation.prompt=laptop, hand, arm
(original image)
(default segmentation)
segmentation.prompt=tee-shirt
and
segmentation.negativePrompt=hanger
If you want to give it a try, here are some code snippets to reproduce the examples above: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'segmentation.prompt="laptop, hand, arm"' \ --output result-laptop-hand-arm.png ``` Try it now! ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form 'imageFile=@"/path/to/image.jpeg"' \ --form 'referenceBox="originalImage"' \ --form 'segmentation.prompt="tee-shirt"' \ --form 'segmentation.negativePrompt="hanger"' \ --output result-tee-shirt-no-hanger.png ``` Try it now! # \[Preview] Templating mode {% hint style="warning" %} Warning: Templating mode is available as a preview feature. As such, please be aware that there could be breaking changes with a 2-week notice period. {% endhint %} ## Overview Templating Mode enables the scalable generation of personalized and visually consistent images by connecting predefined design templates with dynamic content. By creating a reusable image layout (a template) in the Photoroom editor and assigning unique identifiers to each customizable layer, developers can programmatically inject content—like text, product images, or branding elements—through API calls. This approach is ideal for automating image creation for use cases such as product listings, ads, social media creatives, and more. ### Step 1: Create your template 1. Go to . 2. Start a design from an image or from a Photoroom template. For example, open or upload an image in the Design tab. 3. Turn the design into a template to access the templating features (click on the ellipsis `...` button in the top menu bar, then on the `Turn into template` option). 4. You can now add your image and text layers. 5. On any text (or image) layer you can toggle on the `Replaceable Text` toggle (respectively the `Replaceable Subject` toggle). You can then edit the `Unique ID` field to give each of your layer a clear name. 6. **Make the template public** to enable the API to access it: select `Public link` from the sharing settings. This means the template is public only to the people who know about this specific template ID. It enables the API to have access to your template. 7. Click on the `Preview` tab, and click on the template ID at the bottom of this tab. This copies the template ID in your clipboard. {% hint style="info" %} You now have a template with replaceable layers each identified by a unique ID. The template is publicly shared so that the API can access it. {% endhint %} ### Step 2: Create images through the API The key is to keep track of the `Unique ID`s defined in your template for each layer, as they will be reused in your API calls. Here is an example API call: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form templateId=YOUR_TEMPLATE_ID \ --form 'layers.author.text.content=Tom C.' \ --form 'layers.review.text.content=”Nice product, I love it“' \ --form 'layers.product.image.imageUrl=https://images.unsplash.com/photo-1541643600914-78b084683601?q=80&w=1200&auto=format&fit=crop' \ --output result.png ``` {% endcode %}

Example output

The first attribute needed is `templateId`, which allows you to connect the API to your template. All layer attributes are set using `layers.UNIQUE_ID.image.ATTRIBUTE` or `layers.UNIQUE_ID.text.ATTRIBUTE` (with `UNIQUE_ID` replaced by the actual layer unique id, and `ATTRIBUTE` being replaced by the attribute you want to target). Here is a list of all attributes: * text layer * `content` (string): replaces the text content * `foregroundColor` (hexadecimal color string): replaces the text color * `backgroundColor` (hexadecimal color string): replaces the background color * `font` (string): replaces the font of the text (refer to the Photoroom editor for the full list of available fonts) * image layer * `imageFile` (binary): replaces the image (can only specify one of `imageFile` and `imageUrl`) * `imageUrl` (url string): replaces the image (can only specify one of `imageFile` and `imageUrl`) * `removeBackground` (`auto` or `never`): choose whether to remove the background of this image (defaults to `auto`) * `useForAIBackground` (`auto` or `never`): choose whether the image is taken into account when building the AI background (defaults to `auto`), this is only useful if you have defined an AI background in your template or API call. * `horizontalAlignment` (`left`, `center` or `right`): defines the horizontal alignment of the image within its box (defaults to `auto`) * `verticalAlignment` (`top`, `center` or `bottom`): defines the vertical alignment of the image within its box (defaults to `auto`) * `margin` (percentage string like `10%` or decimal number like `0.1`): defines margins around the object * you can use `marginTop`, `marginRight`, `marginBottom`, `marginLeft` if you want to specify different margins * `padding` (percentage string like `10%` or decimal number like `0.1`): defines padding around the object, the padding will be ignored on each side where the segmented object is cropped * you can use `paddingTop`, `paddingRight`, `paddingBottom`, `paddingLeft` if you want to specify different paddings * `segmentation`: Enables text-guided segmentation for this image. If `removeBackground` is `never`, the result will be "zoomed" to the segmented subject. * `segmentation.prompt`: A textual description of what the segmentation should keep, for example `book,pen,ball` * `segmentation.negativePrompt` (optional): A textual description of what the segmentation should remove * `segmentation.mode`: either `keepSalientObject` or `ignoreSalientObject`, default `ignoreSalientObject`. If it's `keepSalientObject`, the salient object of the image (i.e. what the default segmentation would have kept) will also be kept by the segmentation in addition to the `prompt`. Note: the `removeBackground=never` and `useForAIBackground=never` are great when used with logos, so that only your products have their background removed and does not affect the AI background. Here is an example of a more complex API call: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form templateId=YOUR_TEMPLATE_ID \ --form 'layers.author.text.content=Tom C.' \ --form layers.author.text.foregroundColor=DC143C \ --form layers.author.text.backgroundColor=fe9167 \ --form 'layers.review.text.font=Permanent Marker' \ --form 'layers.rating.text.content=★ ★ ★ ★ ☆' \ --form 'layers.review.text.content=”Nice product, I love it“' \ --form 'layers.cta.text.content=BUY NOW' \ --form 'layers.product.image.imageUrl=https://images.unsplash.com/photo-1541643600914-78b084683601?q=80&w=1200&auto=format&fit=crop' \ --form layers.product.image.removeBackground=auto \ --form layers.product.image.useForAIBackground=auto \ --form layers.product.image.horizontalAlignment=center \ --form layers.product.image.verticalAlignment=center \ --form layers.product.image.margin=0.1 \ --output result.png ``` {% endcode %}

Example output

### Frequently Asked Questions (FAQ) * How many images can I replace (in the same row)? * There is a maximum of 10 replaceable images at the moment. # Quickstart Guide ## Who is this API for? The Remove Background API allows you to isolate the subject of an image by removing the background of the image. Using this API is appropriate if you only need to remove the background of your image, and don't need to perform any additional edits. The quality of the background removal will be the same than that of the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). However, because this API only performs background removal, its response time will be faster. Data on median and p90 response times is [available here](https://photoroomapi.statuspage.io). {% hint style="info" %} For additional information about the important features to look for in image background removal technology, you can [consult this blog article](https://www.photoroom.com/blog/image-background-removal-technology-comparison). {% endhint %} ## How do I make my first API call? To call the Remove Background API and remove the background of an image, you can run the following code in your terminal: ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form image_file=@/path/to/your/image.jpg \ --output photoroom-result.png ``` {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} To go further, you can visit the [API Reference](/getting-started/api-reference-openapi#post-v1-segment) to learn about all the available parameters (`format`, `channels`, `bg_color`, `size`, `crop`). ## Will the API make alterations to my products? No, the Remove Background API will only remove the background and will not make any change to the actual pixels of the original image. Consequently, it cannot make alterations to your products, such as modifying a logo or a brand name. {% hint style="info" %} Please note that the feature [Green Screen Despill](/remove-background-api-basic-plan/green-screen-despill) can, however, alter colors. {% endhint %} # Pricing The Remove Background API is part of our "Basic plan" and each API call is priced at $0.02 Details of the pricing are [available here](https://www.photoroom.com/api/pricing). # File size, resolution and format ## **Which image formats are supported?** For the input image, the Remove Background API supports four formats: PNG, JPEG, WEBP and HEIC. For the result image, the Remove Background API supports three formats: PNG, JPEG and WEBP. By default, the result image will be in PNG format. To configure the format of the result image, set the argument `format` with one of the following values: * `png` for PNG format (bigger file size, transparency is saved) * `jpg` for JPEG format (smaller file size, transparency is not saved) * `webp` for WEBP format (smaller file size, transparency is saved) If you want to give it a try, here's the code to export an image in JPEG format: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form image_file=@/absolute/path/to/image.jpg \ --form format=jpg \ --output photoroom-result.jpg ``` {% endcode %} And here's the code to export an image in WEBP format: ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form image_file=@/absolute/path/to/image.jpg \ --form format=webp \ --output photoroom-result.webp ``` ## **What is the max resolution of the image?** We recommend limiting images to 25 megapixels for optimal performance. * **Maximum File Size**: 50MB * **Maximum Resolution**: 6,000 pixels on the widest side {% hint style="info" %} Please note that large images will result in API calls taking a longer time to complete. If you experience timeouts, we recommend that you try to increase the default timeout of your networking library. {% endhint %} ## Can I use the URL of an image? The Remove Background API requires you to upload the content of your image file when making the API call. However, if your images are already hosted online, it's possible that you don't have the image file itself, but rather a URL that points to the file. If that's the case, there are two solutions for you to process your image through the Photoroom API. ### Option 1: Download the image locally In most situations, you should be able to use the image URL to download the content of the image, store it in a local variable, and then use it when calling the Remove Background API. Here's an example code in JavaScript of how to implement this workflow: ```javascript const axios = require('axios'); const FormData = require('form-data'); const fs = require('fs'); const path = require('path'); async function downloadImageAndCallAPI(imageUrl) { try { // Step 1: Download the image in the local variable `imageBytes` const response = await axios.get(imageUrl, { responseType: 'arraybuffer' }); const imageBytes = response.data; // Step 2: Call to the Remove Background API const form = new FormData(); form.append('image_file', imageBytes, 'image.jpg'); // Step 3: Make an API call with the image bytes in multipart form const uploadResponse = await axios.post("https://sdk.photoroom.com/v1/segment", form, { headers: { "x-api-key": "REPLACE_WITH_YOUR_API_KEY", ...form.getHeaders(), }, responseType: 'arraybuffer' }); // Step 3: Save the result image locally const localPath = path.join(__dirname, 'photoroom-result.png'); fs.writeFileSync(localPath, uploadResponse.data); } catch (error) { console.error('An error occurred:', error.message); } } ``` ### Option 2: Use the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) If downloading the content of the image in a local variable is absolutely not possible for you, then you can use our [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) to process your images. The Image Editing API does offer a [GET endpoint](/image-editing-api-plus-plan/quickstart-guide#get-endpoint), thanks to which you can use the argument `imageUrl` to pass the URL of your image. {% hint style="warning" %} The Image Editing API is part of our Plus plan and calling this API is **more expensive** than calling the Remove Backhround API. Make sure to [review our API pricing](https://www.photoroom.com/api/pricing). {% endhint %} # Download the segmentation mask By default, the Remove Background API will return the subject that's been cutout from the input image:
Input ImageResult of the API call
However, it's also possible for the Remove Background API to return the segmentation mask instead. For this, you'll need to set the argument `channels` with the value `alpha`. Here's the result it will produce:
Input ImageResult of the API call
{% hint style="info" %} Because the mask is only in grayscale, in most cases it will be faster to download than the cutout subject. {% endhint %} However, there's one important caveat to be aware of: * When returning the cutout subject, the Remove Background API will apply some matting to improve the edges of the subject. * When returning the segmentation mask, this matting process will not be applied. So when the mask is applied manually, the edges of the cutout subject will be less precise. Here's an example of what it looks like:
With matting applied by the APIWithout matting applied by the API
If you want to give it a try, here's a code example that's configured to download the mask: {% code overflow="wrap" %} ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form image_file=@/absolute/path/to/image.jpg \ --form channels=alpha \ --output segmentation-mask.png ``` {% endcode %} # Sandbox Mode You can make up to 1,000 free calls by month to the Image Editing API using sandbox mode (100 max per day). Sandbox mode is meant to be used for testing and prototyping, and will produce an image with a watermark. To use sandbox mode, prepend `sandbox_` to your API key. (Example: `sandbox_xxxxxxxxxxxxxxxx`) ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: sandbox_xxxxxxxxxxxxxxxx' \ --form image_file=@/path/to/image.jpg \ --output result-sandbox-mode.png ``` | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FSfNyqw4ZvJfkjQhTrCtu%2Fshoes.jpeg?alt=media\&token=3d01688a-b234-4a5e-badf-5b99d4a3df53) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FaXSY2PsvAQcwKgmpZRQj%2Fresult-sandbox-mode.png?alt=media\&token=feb9a1b2-9fd8-4c17-9e2e-e9be19466333) | ![](https://2855892273-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1SYxn7dWbQYsNtUdJE3f%2Fuploads%2FJa5cSZt8LcCdnF4EPaci%2Fresult-sandbox-mode-sandbox.png?alt=media\&token=067d03d8-6128-4d95-b112-e9d2dcd06f0b) | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | | *(original image)* | *regular API call* | *sandbox mode API call* | # Uncertainty score The API returns a confidence score of the cutout through the HTTP header `x-uncertainty-score`. 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):
High uncertainty score: between 0.6 and 1Low uncertainty score: between 0 and 0.3
{% hint style="warning" %} Please note that the uncertainty score is not guaranteed to be stable over time: the same image might yield a different uncertainty score in the future. {% endhint %} In some cases, we might not be able to able to return an uncertainty score (e.g. if an image contains humans), in that case the value `-1` will be returned. {% hint style="info" %} Learn more about all the important features to look for in AI image background removal technology in [this article](https://www.photoroom.com/blog/image-background-removal-technology-comparison). {% endhint %} # Green screen despill The Remove Background API offers a feature to handle green screen despill. Green screen despill works by automatically removing colored reflections that have been left on the main subject by a green background, learn more about it in [this blog article](https://www.photoroom.com/blog/image-background-removal-technology-comparison#3-important-features). {% hint style="info" %} Please note that the green screen despill feature is currently in beta and is subject to changes. {% endhint %} To enable green screen despill, set the argument `despill` to the value `true`:
(original image)
despill=false
despill=true
{% hint style="warning" %} **Known limitations** * This feature only works for green screen: it will not do anything for pictures that use a blue screen or any color other than green * All green color tones on the main subject will be affected by the feature: this means that for a person wearing green clothing, the color of the clothing will be modified {% endhint %} If you want to give it a try, here's the code to reproduce the example above: ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form 'image_file=@"/path/to/your/image.jpeg"' \ --form 'despill=true' \ --output result-with-green-screen-despill.png ``` # Background Color, Size and Crop The Remove Background API offers additional 3 parameters, that allow you to perform basic editing on the result image. {% hint style="info" %} If you need more control over the editing of the result image, we recommend having a look at our [Image Editing API](broken://pages/sYF796CaXvK7stuRaSNG), which offers many more editing features. {% endhint %} ### `bg_color` The background color of the resulting image. Can be a hex code (`#FF00FF`) or a HTML color (`red`, `green`, etc.) ### `size` 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. Default: `full` ### `crop` If `true`, the image returned is cropped to the cutout border. Transparent pixels are removed from the border Default: `false` # Remove.bg compatibility The Remove Background API offers a built-in compatibility with the API of Remove.bg. This means that any code that calls the API of Remove.bg, like this one: ```bash curl -H 'x-api-key: YOUR_REMOVE_BG_API_KEY' \ -f https://api.remove.bg/v1.0/removebg \ -F 'image_file=@/absolute/path/to/image.jpg' \ -F 'crop=true' \ -F 'bg_color=FFFFFF' \ -F 'format=jpg' \ -F 'size=hd' \ -o result.jpg ``` Can easily be updated to instead call the Remove Background API, just by changing: 1. The URL to `https://sdk.photoroom.com/v1/segment` 2. The API Key to [a Photoroom API Key](/#how-can-i-get-my-api-key) ```bash curl -H 'x-api-key: YOUR_PHOTOROOM_API_KEY' \ -f https://sdk.photoroom.com/v1/segment \ -F 'image_file=@/absolute/path/to/image.jpg' \ -F 'crop=true' \ -F 'bg_color=FFFFFF' \ -F 'format=jpg' \ -F 'size=hd' \ -o result.jpg ``` As you can see, beside these two changes the rest of the code didn't need to be modified, because the name of the arguments and the format of the result both stay the same. # Code Samples # Web Integration ### Tutorials Web Integration In this tutorial, I will show you how you can integrate the Photoroom API into a JavaScript or TypeScript codebase in just a few minutes. ### Step 1: Get Your API Key The first thing you need to do is get your API key. If you don't already have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). ### Step 2: Use Our Sample Code Visit [Photoroom’s GitHub](https://github.com/PhotoRoom/api-code-samples) to find a sample code that's ready to use. Simply copy and paste the code into your project, and update the placeholder with your own API key. ```javascript const url = 'https://sdk.photoroom.com/v1/segment'; // Please replace with your own apiKey const apiKey = "YOUR_API_KEY_HERE"; export async function removeBackground(imageFile: File): Promise { const formData = new FormData(); formData.append('image_file', imageFile); const response = await fetch(url, { method: 'POST', headers: { 'X-Api-Key': apiKey }, body: formData }); if (!response.ok) { console.error(response.json()) throw new Error('Network response was not ok'); } const imageBlob: Blob = await response.blob(); return imageBlob; } ``` Warning: Please be aware that this will make your API key accessible to anyone browsing your website. If your website is public, we recommend calling our API through a proxy that you control (Firebase / Google functions, AWS lambda). ### Step 3: Call the API Now it's time to call the API in your code! Just use the function removeBackground() and pass in the file your user has selected. The function will return a Blob containing a new image with the background removed. ```javascript import { removeBackground } from './remove-background.js'; const fileInput = document.getElementById('fileInput') as HTMLInputElement; const displayImage = document.getElementById('displayImage') as HTMLImageElement; fileInput.addEventListener('change', async () => { const files = fileInput.files; if (files && files.length > 0) { try { const imageBlob = await removeBackground(files[0]); // 👈 API call is here const objectURL = URL.createObjectURL(imageBlob); displayImage.src = objectURL; } catch (error) { console.error('Error:', error); } } }); ``` ### You're done! That's it! With just these three easy steps, you can integrate the Photoroom Background Removal API into your web app and provide your users with high-quality images with clean backgrounds. According to resellers who use the Photoroom app, this feature can increase sales by 20 up to 100%. If you want to learn more about the Photoroom API and get your API key, visit . # Node.js Integration In this tutorial, I will show you how you can integrate the Photoroom API into a Node.js codebase in just a few minutes. ### Step 1: Get Your API Key The first thing you need to do is get your API key. If you don't already have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). ### Step 2: Use Our Sample Code Visit [Photoroom’s GitHub](https://github.com/PhotoRoom/api-code-samples) to find a sample code that's ready to use. Simply copy and paste the code into your project, and update the placeholder with your own API key. ```javascript const https = require('https'); const fs = require('fs'); // Please replace with your own apiKey const apiKey = 'YOUR_API_KEY_HERE'; function removeBackground(imagePath, savePath) { return new Promise((resolve, reject) => { const boundary = '--------------------------' + Date.now().toString(16); const postOptions = { hostname: 'sdk.photoroom.com', path: '/v1/segment', method: 'POST', headers: { 'Content-Type': `multipart/form-data; boundary=${boundary}`, 'X-API-Key': apiKey } }; const req = https.request(postOptions, (res) => { // Check if the response is an image const isImage = ['image/jpeg', 'image/png', 'image/gif'].includes(res.headers['content-type']); if (!isImage) { let errorData = ''; res.on('data', (chunk) => errorData += chunk); res.on('end', () => reject(new Error(`Expected an image response, but received: ${errorData}`))); return; } // Create a write stream to save the image const fileStream = fs.createWriteStream(savePath); res.pipe(fileStream); fileStream.on('finish', () => { resolve(`Image saved to ${savePath}`); }); fileStream.on('error', (error) => { reject(new Error(`Failed to save the image: ${error.message}`)); }); }); req.on('error', (error) => { reject(error); }); // Write form data req.write(`--${boundary}\r\n`); req.write(`Content-Disposition: form-data; name="image_file"; filename="${imagePath.split('/').pop()}"\r\n`); req.write('Content-Type: image/jpeg\r\n\r\n'); // assuming JPEG, adjust if another format is used const uploadStream = fs.createReadStream(imagePath); uploadStream.on('end', () => { req.write('\r\n'); req.write(`--${boundary}--\r\n`); req.end(); }); uploadStream.pipe(req, { end: false }); }); } module.exports = removeBackground; ``` ### Step 3: Call the API Now it's time to call the API in your code! Just use the function removeBackground() and pass as arguments both the path of the original image and the path where the result image should be saved. ```javascript const removeBackground = require('./remove-background'); const imagePath = './path/to/your/image.jpg'; const savePath = './path/where/you/want/to/save/response.jpg'; removeBackground(imagePath, savePath) .then(message => { console.log(message); }) .catch(error => { console.error('Error:', error); }); ``` ### You're done! That's it! With just these three easy steps, you can integrate the Photoroom Background Removal API into your Node.js project and provide your users with high-quality images with clean backgrounds. According to resellers who use the Photoroom app, this feature can increase sales by 20 up to 100%. If you want to learn more about the PhotoRoom API and get your API key, visit . # Python Integration In this tutorial, I will show you how you can integrate the Photoroom API into a Python codebase in just a few minutes. ### Step 1: Get Your API Key The first thing you need to do is get your API key. If you don't already have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). ### Step 2: Use Our Sample Code Visit [Photoroom’s GitHub](https://github.com/PhotoRoom/api-code-samples) to find a sample code that's ready to use. Simply copy and paste the code into your project, and update the placeholder with your own API key. ```python import http.client import mimetypes import os import uuid # Please replace with your own apiKey apiKey = 'YOUR_API_KEY_HERE' def remove_background(input_image_path, output_image_path): # Define multipart boundary boundary = '----------{}'.format(uuid.uuid4().hex) # Get mimetype of image content_type, _ = mimetypes.guess_type(input_image_path) if content_type is None: content_type = 'application/octet-stream' # Default type if guessing fails # Prepare the POST data with open(input_image_path, 'rb') as f: image_data = f.read() filename = os.path.basename(input_image_path) body = ( f"--{boundary}\r\n" f"Content-Disposition: form-data; name=\"image_file\"; filename=\"{filename}\"\r\n" f"Content-Type: {content_type}\r\n\r\n" ).encode('utf-8') + image_data + f"\r\n--{boundary}--\r\n".encode('utf-8') # Set up the HTTP connection and headers conn = http.client.HTTPSConnection('sdk.photoroom.com') headers = { 'Content-Type': f'multipart/form-data; boundary={boundary}', 'x-api-key': apiKey } # Make the POST request conn.request('POST', '/v1/segment', body=body, headers=headers) response = conn.getresponse() # Handle the response if response.status == 200: response_data = response.read() with open(output_image_path, 'wb') as out_f: out_f.write(response_data) print("Image saved to", output_image_path) else: print(f"Error: {response.status} - {response.reason}") print(response.read()) # Close the connection conn.close() ``` ### Step 3: Call the API Now it's time to call the API in your code! Just use the function remove\_background() and pass as arguments both the path of the original image and the path where the result image should be saved. ```python from remove_background import remove_background # Example usage input_path = "test.jpg" output_path = "result.png" remove_background(input_path, output_path) ``` ### You're done! That's it! With just these three easy steps, you can integrate the Photoroom Background Removal API into your Python project and provide your users with high-quality images with clean backgrounds. According to resellers who use the Photoroom app, this feature can increase sales by 20 up to 100%. If you want to learn more about the Photoroom API and get your API key, visit . # iOS / Swift Integration If you work on an e-commerce iOS app, you know how important it is to provide users with high-quality images of the products they want to sell. However, taking pictures with a clean background can be a challenge for many users. This is where the Photoroom API comes in handy! With the Photoroom API, you can easily remove the background of images in your iOS app, improving the overall quality of the pictures your users will upload. In this tutorial, I will show you how you can integrate the Photoroom API into your iOS app in just a few minutes. ### Step 1: Get Your API Key The first thing you need to do is get your API key. If you don't already have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). ### Step 2: Use our Sample Code Visit [Photoroom’s GitHub](https://github.com/PhotoRoom/api-code-samples) to find a sample code that's ready to use. Simply copy and paste the code into your Xcode project, and update the placeholder with your own API key. ![](https://a.storyblok.com/f/191576/2878x2382/5065fd3da2/how-to-easily-remove-the-background-of-images-inside-your-ios-app-002.png) ### Step 3: Call the API Now it's time to call the API in your code! Just use the function removeBackground(of: yourImage) and pass in your original UIImage as an argument. The function will return a new UIImage with the background removed. ```swift // with Swift Concurrency Task { @MainActor in imageView.image = try await removeBackground(of: yourImage) } // without Swift Concurrency removeBackground(of: yourImage) { result in switch result { case let .success(backgroundRemoved): imageView.image = backgroundRemoved case let .failure(error): // handle the `error` } } ``` ### ![](https://a.storyblok.com/f/191576/256x555/fc72482859/how-to-easily-remove-the-background-of-images-inside-your-ios-app-003.gif)You're done! That's it! With just these three easy steps, you can integrate the Photoroom Background Removal API into your iOS app and provide your users with high-quality images with clean backgrounds. According to resellers who use the Photoroom app, this feature can increase sales by 20 up to 100%. If you want to learn more about the Photoroom API and get your API key, visit . # How to process images from a local directory A common use case for the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) or the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) is to process a large amount of images, which are stored in a local directory. In this tutorial, we'll see how it's possible to process these images by integrating the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) or the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) with a Python script. ## Step 1: Calling the API First, we'll write a function that can process a local image through the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) or the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) and save the result image returned by the API to the disk: {% tabs %} {% tab title="Code to integrate with the Image Editing API" %} ```python import requests API_KEY = "REPLACE_WITH_YOUR_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://image-api.photoroom.com/v2/edit" with open(input_image_path, 'rb') as image_file: files = { "imageFile": image_file } headers = { "Accept": "image/png, application/json", "x-api-key": API_KEY } response = requests.post(url, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) ``` {% endtab %} {% tab title="Code to integrate with the Remove Background API" %} ```python import requests API_KEY = "REPLACE_WITH_YOUR_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://sdk.photoroom.com/v1/segment" with open(input_image_path, 'rb') as image_file: files = { "image_file": image_file } headers = { "Accept": "image/png, application/json", "x-api-key": API_KEY } response = requests.post(url, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) ``` {% endtab %} {% endtabs %} This code is pretty straightforward: 1. it opens the image stored at `input_image_path` 2. uses the `requests` library to make the POST HTTP call to the API 3. saves the result image at `output_image_path` Notice that you will need to update the value of the constant `API_KEY` with your own API key. {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Step 2: Iterating over a local directory Now that we have a function to process a single image, the next step is to iterate over all the images stored in a local directory and call `process_image()` for each of them. ```python import concurrent.futures import os def iterate_over_directory(input_directory_path, result_directory_path): with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor: for root, _, files in os.walk(input_directory_path): for file in files: file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '.png' result_path = os.path.join(result_directory_path, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, file_path, result_path) ``` This time the code is a bit more complex, but here are its important steps: 1. we iterate over the files inside the directory at `input_directory_path` 2. then for each `file` we: 1. compose the `result_path` where the result image will be saved 2. check that a file doesn't already exist at `result_path` (so as to not process the same image twice) 3. call the function `process_image()` through an `executor`, which allows us to execute 4 API calls in parallel {% hint style="info" %} If you want, you can increase the value of the argument `max_workers` to run more API calls in parallel. Keep in mind though that the API is [rate limited to 60 calls/minutes](/getting-started/frequently-asked-questions#q-is-there-a-rate-limiting). {% endhint %} ## Step 3: Running the script We're almost there, the last thing we need is to actually run the script. To do this we'll add this final piece of code: ```python if __name__ == "__main__": INPUT_DIRECTORY = "./input/" OUTPUT_DIRECTORY = "./output/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(input_directory_path=INPUT_DIRECTORY, result_directory_path=OUTPUT_DIRECTORY) ``` Here we set the constants `INPUT_DIRECTORY` and `OUTPUT_DIRECTORY` to the paths of respectively: * the directory where the input images are stored * the directory where we want to save the result images. Then all that's left is to actually run the script using the terminal: ```bash $ pip install requests # run once to install the library `requests` $ python script.py ``` ## Conclusion In this tutorial, we saw how to use a Python script to easily process images stored locally with the Photoroom API. ## Download the code sample Here's the entire code sample, if you want to easily save it to a file: ```python import concurrent.futures import os import requests API_KEY = "REPLACE_WITH_YOUR_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://sdk.photoroom.com/v1/segment" with open(input_image_path, 'rb') as image_file: files = { "image_file": image_file } headers = { "Accept": "image/png, application/json", "x-api-key": API_KEY } response = requests.post(url, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def iterate_over_directory(input_directory_path, result_directory_path): with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor: for root, _, files in os.walk(input_directory_path): for file in files: file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '.png' result_path = os.path.join(result_directory_path, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./input/" OUTPUT_DIRECTORY = "./output/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(input_directory_path=INPUT_DIRECTORY, result_directory_path=OUTPUT_DIRECTORY) ``` # How to process images from Google Drive A common use case for the Photoroom API is to process a large amount of images, which are stored inside a Google Drive folder. In this tutorial, we'll see how it's possible to process these images by integrating either the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) or the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) with a Google Apps Script. ## Step 1: Creating a Google Apps Script If you've never used Google Apps Script before, it's a convenient way to run code that can easily interact with Google services, including Google Drive. To create an Apps Script, go to your Google Drive, and click on *New* > *More* > *Google Apps Script*:
This will open a new tab that contains a development environment:
The first thing we'll do is to allow the script to interact with Google Drive. To do that, click on the “+” button next to *Services*:
Then proceed to add both the *Drive API*:
You should now see the *Drive* services available in your development environment:
Now that our environment is set up, it's time to write some code! You can remove all the sample code `function myFunction() { }` and replace it with this code: {% tabs %} {% tab title="Code to integrate with the Image Editing API" %} ```javascript // Customizable variables const INPUT_FOLDER_ID = "REPLACE_WITH_YOUR_INPUT_FOLDER_ID"; const OUTPUT_FOLDER_ID = "REPLACE_WITH_YOUR_OUTPUT_FOLDER_ID"; const API_KEY = "REPLACE_WITH_YOUR_API_KEY"; const SANDBOX_MODE = false; // Params can be expressed as GET params shape const EDIT_PARAMS = "background.color=transparent&background.scaling=fill&outputSize=1000x1000&padding=0.1"; // Or as direct payload // const EDIT_PARAMS = { // "background.color": "transparent", // "background.scaling": "fill", // outputSize: "1000x1000", // padding: 0.1 // } const inputFolder = DriveApp.getFolderById(INPUT_FOLDER_ID); const outputFolder = DriveApp.getFolderById(OUTPUT_FOLDER_ID); const formDataPayload = generatePayloadFromParams(EDIT_PARAMS); // The main function to execute the script function imageEditingAPIMain() { const lock = LockService.getScriptLock(); try { if (!lock.tryLock(0)) { console.error('Exiting, script is already running.'); return; } const imagesToProcess = []; const files = inputFolder.getFiles(); while (files.hasNext()) { const file = files.next(); if (isImageFile(file) && !isFileProcessed(file.getName())) { imagesToProcess.push(file); } } console.log(`Found ${imagesToProcess.length} images to process`); const batchSize = 8; // Adjust this based on your API's rate limits // Process images and send them to the OUTPUT_FOLDER for (let i = 0; i < imagesToProcess.length; i += batchSize) { const batch = imagesToProcess.slice(i, i + batchSize); const requests = batch.map((imageToProcess) => { const originUrl = "https://image-api.photoroom.com"; return { url: `${originUrl}/v2/edit`, method: "post", headers: { "x-api-key": `${SANDBOX_MODE ? "sandbox_" : ""}${API_KEY}`, }, payload: { ...formDataPayload, imageFile: imageToProcess.getBlob(), }, muteHttpExceptions: true, }; }); const responses = UrlFetchApp.fetchAll(requests); for (let j = 0; j < responses.length; j++) { const response = responses[j]; const imageToProcess = batch[j]; if (response.getResponseCode() === 200) { try { const processedImageBlob = response.getBlob(); outputFolder.createFile(processedImageBlob.setName(imageToProcess.getName())); console.log(`Processed '${imageToProcess.getName()}'`); } catch (e) { console.error(`Failed to process ${imageToProcess.getName()}: ${e.message}`); } } else { console.error(`Failed to process ${imageToProcess.getName()}: ${response.getContentText()}`); } } } } catch (error) { console.error('Script failed with error:', error); } finally { // Always release the lock, even if an error occurred lock.releaseLock(); } } function isFileProcessed(fileName) { const files = outputFolder.getFilesByName(fileName); return files.hasNext(); } function isImageFile(file) { const mimeType = file.getMimeType(); return mimeType.indexOf("image/") === 0; } function generatePayloadFromParams(editParams) { if (typeof editParams === "object") { return editParams; } return editParams .split("&") .map((param) => param.split("=")) .reduce((acc, [key, value]) => { acc[key] = decodeURIComponent(value); return acc; }, {}); } ``` There's quite a bit of code. Fortunately, you will only need to configure a few parts: 1. update `const API_KEY` with your Photoroom API key {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). ⚠️ Make sure **not to include** `sandbox_` when copy/pasting your API key ⚠️ {% endhint %} 2. update `const INPUT_FOLDER_ID` and `const OUTPUT_FOLDER_ID` with respectively the id of the Google Drive folder where you want to read the input images and save the result images {% hint style="info" %} To get the id of a Google Drive folder, you just need to look at the folder's URL: [https://drive.google.com/drive/u/0/folders/THIS\_IS\_THE\_FOLDER\_ID](https://drive.google.com/drive/u/0/folders/10s7jyIaTzIyWHClYa4QfxgzYQeXJaRcV) {% endhint %} 3. set the value of `const SANDBOX_MODE` depending on whether or not you want to use [Sandbox mode](/image-editing-api-plus-plan/sandbox-mode) 4. set the value of `const EDIT_PARAMS` with the edits that you want to apply to your images {% hint style="info" %} To define which edits you want to apply, we recommend that you use our [Interactive API Playground](https://www.photoroom.com/api/playground). {% endhint %} That's all the changes you need to make, the rest of the code can be used as-is. {% endtab %} {% tab title="Code to integrate with the Remove Background API" %} ```javascript // Customizable variables const INPUT_FOLDER_ID = "REPLACE_WITH_YOUR_INPUT_FOLDER_ID"; const OUTPUT_FOLDER_ID = "REPLACE_WITH_YOUR_OUTPUT_FOLDER_ID"; const API_KEY = "REPLACE_WITH_YOUR_API_KEY"; const SANDBOX_MODE = false; const BACKGROUND_REMOVAL_PARAMS = { format: "png", channels: "rgba", size: "full", crop: false, despill: false, } const inputFolder = DriveApp.getFolderById(INPUT_FOLDER_ID); const outputFolder = DriveApp.getFolderById(OUTPUT_FOLDER_ID); const formDataPayload = generatePayloadFromParams(BACKGROUND_REMOVAL_PARAMS); // The main function to execute the script function backgroundRemovalAPIMain() { const lock = LockService.getScriptLock(); try { if (!lock.tryLock(0)) { console.error('Exiting, script is already running.'); return; } const imagesToProcess = []; const files = inputFolder.getFiles(); while (files.hasNext()) { const file = files.next(); if (isImageFile(file) && !isFileProcessed(file.getName())) { imagesToProcess.push(file); } } console.log(`Found ${imagesToProcess.length} images to process`); const batchSize = 8; // Adjust this based on your API's rate limits // Process images and send them to the OUTPUT_FOLDER for (let i = 0; i < imagesToProcess.length; i += batchSize) { const batch = imagesToProcess.slice(i, i + batchSize); const requests = batch.map((imageToProcess) => { return { url: "https://sdk.photoroom.com/v1/segment", method: "post", headers: { "x-api-key": `${SANDBOX_MODE ? "sandbox_" : ""}${API_KEY}`, }, payload: { ...formDataPayload, image_file: imageToProcess.getBlob(), }, muteHttpExceptions: true, }; }); const responses = UrlFetchApp.fetchAll(requests); for (let j = 0; j < responses.length; j++) { const response = responses[j]; const imageToProcess = batch[j]; if (response.getResponseCode() === 200) { try { const processedImageBlob = response.getBlob(); outputFolder.createFile(processedImageBlob.setName(imageToProcess.getName())); console.log(`Processed '${imageToProcess.getName()}'`); } catch (e) { console.error(`Failed to process ${imageToProcess.getName()}: ${e.message}`); } } else { console.error(`Failed to process ${imageToProcess.getName()}: ${response.getContentText()}`); } } } } catch (error) { console.error('Script failed with error:', error); } finally { // Always release the lock, even if an error occurred lock.releaseLock(); } } function isFileProcessed(fileName) { const files = outputFolder.getFilesByName(fileName); return files.hasNext(); } function isImageFile(file) { const mimeType = file.getMimeType(); return mimeType.indexOf("image/") === 0; } function generatePayloadFromParams(editParams) { if (typeof editParams === "object") { return editParams; } return editParams .split("&") .map((param) => param.split("=")) .reduce((acc, [key, value]) => { acc[key] = decodeURIComponent(value); return acc; }, {}); } ``` There's quite a bit of code. Fortunately, you will only need to configure a few parts: 1. update `const API_KEY` with your Photoroom API key {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). ⚠️ Make sure **not to include** `sandbox_` when copy/pasting your API key ⚠️ {% endhint %} 2. update `const INPUT_FOLDER_ID` and `const OUTPUT_FOLDER_ID` with respectively the id of the Google Drive folder where you want to read the input images and save the result images {% hint style="info" %} To get the id of a Google Drive folder, you just need to look at the folder's URL: [https://drive.google.com/drive/u/0/folders/THIS\_IS\_THE\_FOLDER\_ID](https://drive.google.com/drive/u/0/folders/10s7jyIaTzIyWHClYa4QfxgzYQeXJaRcV) {% endhint %} 3. set the value of `const BACKGROUND_REMOVAL_PARAMS` to configure the parameters of the API call {% hint style="info" %} The documentation of each of these parameters is [available here](https://www.photoroom.com/api/docs/reference/71f4c26e59e43-remove-background-basic-plan). {% endhint %} That's all the changes you need to make, the rest of the code can be used as-is. {% endtab %} {% endtabs %} ## Step 2: Running the Google Apps Script Then, the next step is to run the script! To execute the script, you just need to click on the button *Run*:
{% hint style="info" %} The first time you run the script, you'll be prompted to give it permission to access your Google Sheets and Google Drive. {% endhint %} While the script is running, you'll see appear the execution log which lets you monitor its progress and will provide useful debug information should an error occur.
The Google Drive folder whose id you used should also contain the result images:
## Step 3: Scheduling Execution of the Google Apps Script In addition to manually executing the Google Apps Script from the development environment, it's also possible to schedule its execution at predefined times. To schedule the execution of the script, click on *Trigger* in the left menu, then on *Add Trigger*:
Then make sure that the function to be executed is indeed the correct one, then select the periodicity at which you want your script to be executed, and finally save the trigger:
## Conclusion In this tutorial, we saw how to use a Google Apps Script to easily process images stored inside Google Drive through the Photoroom API. It's worth noting that a very similar approach can also be used in the situation where you want to process images stored in another service, using a [combination of a Google Apps Script and a Google Sheet](/integrations/how-to-process-images-from-google-sheets). # How to process images from Google Sheets {% embed url="" %} A common use case for the Photoroom API is to process a large amount of images, whose URLs are stored in a spreadsheet. In this tutorial, we'll see how it's possible to process these images by integrating either the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) or the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) with Google Sheets. Let's take the example of this spreadsheet:
To process these images we'll need two things: 1. a place to store the result images 2. a way to run code in the spreadsheet Storing the images is easy: we'll just use a Google Drive folder. And to run code inside the spreadsheet, we're going to use something called a Google Apps Script. ## Step 1: Creating a Google Apps Script If you've never used Google Apps Script before, it's a convenient way to run code that can easily interact with Google services, including Google Sheets and Google Drive. To create an Apps Script, open the *Extensions* menu and click on *Apps Script*:
This will open a new tab that contains a development environment:
The first thing we'll do is to allow the script to interact with both Google Sheets and Google Drive. To do that, click on the “+” button next to *Services*:
Then proceed to add both the *Drive API* and *Google Sheets API*:
You should now see both *Drive* and *Sheets* as services available in your development environment:
Now that our environment is set up, it's time to write some code! You can remove the sample code `function myFunction()` and replace it with this code: {% tabs %} {% tab title="Code to integrate with the Image Editing API" %} ```javascript function processSpreadsheet() { // Config variables const apiKey = "REPLACE_WITH_YOUR_API_KEY"; // Replace with your API Key const folder = DriveApp.getFolderById("REPLACE_WITH_GOOGLE_DRIVE_FOLDER_ID"); // Replace with your Google Drive folder ID const edits = "background.color=FFFFFFFF&outputSize=1000x1000&padding=0.1"; // Replace with the edits you want to apply const IMAGE_URL_COL = 0; const STATUS_COL = 1; var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); var data = sheet.getDataRange().getValues(); var requests = []; var detailsMap = {}; data.forEach(function (row, index) { if (index == 0) return; // Skip header row if (row[STATUS_COL] === 'Processed') return; // Skip if row already marked as processed var imageUrl = row[IMAGE_URL_COL]; var apiEndpoint = "https://image-api.photoroom.com/v2/edit?" + edits + "&apiKey=" + apiKey + "&imageUrl=" + encodeURIComponent(imageUrl); requests.push({url: apiEndpoint, muteHttpExceptions: true}); detailsMap[apiEndpoint] = { rowIndex: index }; // Map API endpoint to row index }); // Process in batches var batchSize = 8; // Number of concurrent calls for (var i = 0; i < requests.length; i += batchSize) { var batchEnd = i + batchSize > requests.length ? requests.length : i + batchSize; var batch = requests.slice(i, batchEnd); var responses = UrlFetchApp.fetchAll(batch); responses.forEach(function (response, index) { var url = batch[index].url; var details = detailsMap[url]; if (response.getResponseCode() == 200) { var blob = response.getBlob(); blob.setName((details.rowIndex + 1) + ".png"); folder.createFile(blob); sheet.getRange(details.rowIndex + 1, STATUS_COL + 1).setValue('Processed'); // Update the status in the second column } else { sheet.getRange(details.rowIndex + 1, STATUS_COL + 1).setValue('Error'); // Update the status in the second column Logger.log("Error processing row " + (details.rowIndex + 1) + ": " + response.getContentText()); } SpreadsheetApp.flush(); }); } } function onOpen() { var ui = SpreadsheetApp.getUi(); // Create a custom menu in the Google Sheets UI. ui.createMenu('Photoroom Actions') .addItem('Process through Photoroom API', 'processSpreadsheet') .addToUi(); } ``` There's quite a bit of code. Fortunately, you will only need to configure a few parts: 1. update `const apiKey` with your Photoroom apiKey {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} 2. update `const folder` with the id of the Google Drive folder where you want to save the result images {% hint style="info" %} To get the id of a Google Drive folder, you just need to look at the folder's URL: [https://drive.google.com/drive/u/0/folders/THIS\_IS\_THE\_FOLDER\_ID](https://drive.google.com/drive/u/0/folders/10s7jyIaTzIyWHClYa4QfxgzYQeXJaRcV) {% endhint %} 3. update `const edits` with the edits you want to apply to your images. In this example, here are the edits that will be applied: * white background * output size of 1000x1000px * padding of 10% {% hint style="info" %} The full list of supported parameters is available in the [API reference](https://www.photoroom.com/api/docs/reference/87e1c15260b1f-beta-edit-image-v2). You can visually define the edits you want to apply using the [API playground](https://www.photoroom.com/api/playground). {% endhint %} That's all the changes you need to make, the rest of the code can be used as-is. {% hint style="info" %} By default, the result images will be named using their respective line number in the spreadsheet. If needed you can modify this behavior by changing this line: ```javascript blob.setName((details.rowIndex + 1) + ".png"); ``` {% endhint %} {% endtab %} {% tab title="Code to integrate with the Remove Background API" %} ```javascript function processSpreadsheet() { // Config variables const apiKey = "REPLACE_WITH_YOUR_API_KEY"; // Replace with your API Key const folder = DriveApp.getFolderById("REPLACE_WITH_GOOGLE_DRIVE_FOLDER_ID"); // Replace with your Google Drive folder ID const IMAGE_URL_COL = 0; const STATUS_COL = 1; var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet(); var data = sheet.getDataRange().getValues(); data.forEach(function (row, index) { if (index == 0 || row[STATUS_COL] === 'Processed') return; // Skip header row and processed rows var imageUrl = row[IMAGE_URL_COL]; // Download image var imageResponse = UrlFetchApp.fetch(imageUrl); var imageBlob = imageResponse.getBlob(); // Prepare multipart form data var formData = { 'image_file': imageBlob }; var options = { 'method' : 'post', 'headers': { 'x-api-key': apiKey }, 'muteHttpExceptions': true, 'payload': formData }; var apiEndpoint = "https://sdk.photoroom.com/v1/segment"; try { var response = UrlFetchApp.fetch(apiEndpoint, options); if (response.getResponseCode() == 200) { var resultBlob = response.getBlob(); resultBlob.setName((index + 1) + ".png"); folder.createFile(resultBlob); sheet.getRange(index + 1, STATUS_COL + 1).setValue('Processed'); } else { sheet.getRange(index + 1, STATUS_COL + 1).setValue('Error'); Logger.log("Error processing row " + (index + 1) + ": " + response.getContentText()); } } catch (e) { sheet.getRange(index + 1, STATUS_COL + 1).setValue('Error'); Logger.log("Error processing row " + (index + 1) + ": " + e.message); } SpreadsheetApp.flush(); }); } function onOpen() { var ui = SpreadsheetApp.getUi(); // Create a custom menu in the Google Sheets UI. ui.createMenu('Photoroom Actions') .addItem('Process through Photoroom API', 'processSpreadsheet') .addToUi(); } ``` There's quite a bit of code. Fortunately, you will only need to configure a few parts: 1. update `const apiKey` with your Photoroom apiKey {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} 2. update `const folder` with the id of the Google Drive folder where you want to save the result images {% hint style="info" %} To get the id of a Google Drive folder, you just need to look at the folder's URL: [https://drive.google.com/drive/u/0/folders/THIS\_IS\_THE\_FOLDER\_ID](https://drive.google.com/drive/u/0/folders/10s7jyIaTzIyWHClYa4QfxgzYQeXJaRcV) {% endhint %} That's all the changes you need to make, the rest of the code can be used as-is. {% hint style="info" %} By default, the result images will be named using their respective line number in the spreadsheet. If needed you can modify this behavior by changing this line: ```javascript blob.setName((details.rowIndex + 1) + ".png"); ``` {% endhint %} {% endtab %} {% endtabs %} ## Step 2: Running a Google Apps Script Finally, the last step is to run the script! The first time you run the script, we recommend you do it inside the development environment, using the button *Run*:
By running this script inside the development environment, you'll have access to its console output, which should help in case there are any errors. {% hint style="info" %} The first time you run the script, you'll be prompted to give it permission to access your Google Sheets and Google Drive. {% endhint %} Once the script has finished running, you can go back to the spreadsheet, where you should see that all the rows are now marked as *Processed*:
The Google Drive folder whose id you used should also contain the result images:
You should also notice that the spreadsheet has gained a new menu called *Photoroom Actions*:
This menu was added thanks to the code inside the `function onOpen()`. It is a shortcut to execute the `function processSpreadsheet()` directly within the spreadsheet. {% hint style="info" %} If the menu *Photoroom Actions* doesn't appear, try refreshing the webpage {% endhint %} This shortcut will be useful if you add more images to the spreadsheet and want to process them rapidly. ## Conclusion In this tutorial, we saw how to use a Google Apps Script to easily integrate Google Sheets and Google Drive with the Photoroom API. It's worth noting that a very similar approach can also be used in the situation where your images are already stored in Google Drive, using a [standalone Google Apps Script](/integrations/how-to-process-images-from-google-drive). # How to process images from an Excel spreadsheet A common use case for the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) is to process a large amount of images, whose URLs are stored inside an Excel spreadsheet. In this tutorial, we'll see how it's possible to process these images through a Python script that will: 1. parse the Excel spreadsheet 2. make the calls to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) 3. save the result images to the disk. Let's take the example of this spreadsheet:
## Step 1: Calling the Image Editing API First, we'll write a function that can process a single image through the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) and save the result image returned by the API to the disk: ```python import os import requests API_KEY = "REPLACE_WITH_YOUR_API_KEY" def process_image(input_image_url, output_image_path): try: url = "https://image-api.photoroom.com/v2/edit" query_string = { "background.color": "FFFFFFFF", "outputSize": "1000x1000", "padding": "0.1", "imageUrl": input_image_url } headers = { "Accept": "image/png, application/json", "x-api-key": API_KEY } response = requests.get(url, headers=headers, params=query_string) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) ``` This code is pretty straightforward: 1. it configures the parameters of the call to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide): 1. white background 2. output size of 1000x1000px 3. padding of 10% 2. uses the `requests` library to make the GET HTTP call to the API 3. saves the result image at `output_image_path` {% hint style="info" %} The full list of supported parameters is available in the [API reference](https://www.photoroom.com/api/docs/reference/87e1c15260b1f-beta-edit-image-v2). You can visually define the edits you want to apply using the [API playground](https://www.photoroom.com/api/playground). {% endhint %} Notice that you will need to update the value of the constant `API_KEY` with your own API key. {% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} ## Step 2: Parsing the Excel spreadsheet Now that we have a function to process a single image, the next step is to parse the content of the Excel spreadsheet, iterate over all the image URLs it contains and call `process_image()` for each of them. ```python import openpyxl import concurrent.futures def iterate_over_spreadsheet(spreadsheet_path, column_name, result_directory_path): # Load the spreadsheet wb = openpyxl.load_workbook(spreadsheet_path) image_urls = [] # Loop over all sheets in the workbook for sheet_name in wb.sheetnames: sheet = wb[sheet_name] for col_num, col_cells in enumerate(sheet.iter_cols(values_only=True)): if col_cells[0] == column_name: break else: print(f"Column {column_name} not found in sheet {sheet_name}.") continue for cell in sheet.iter_rows(min_row=2, min_col=col_num + 1, max_col=col_num + 1): if cell[0].value: image_urls.append(cell[0].value) ``` The code above contains the first half of the function `iterate_over_spreadsheet()`, here are its important steps: 1. we open the spreadsheet located at `spreadsheet_path` using the library `openpyxl` 2. we iterate over all the sheets contained in the document 3. we look for the column whose first cell contains the value `column_name` (in the case of the spreadsheet we use as an example, that value would be `"Image URL"`) 4. we iterate over all the rows in that column, and collect their `value` in the array `image_urls` Now that we have collected all the `image_urls`, we can write the second part of the function `iterate_over_spreadsheet()`: ```python with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor: for image_url in image_urls: # Extracting the filename from the URL, stripping query parameters if any base_name = os.path.basename(image_url.split('?')[0]) # Getting the filename without its original extension and appending '.png' result_file_name = os.path.splitext(base_name)[0] + '.png' result_path = os.path.join(result_directory_path, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, image_url, result_path) ``` In this second part of the function we: 1. iterate over the `image_urls` 2. compose the `result_path` where the result image will be saved 3. check that a file doesn't already exist at `result_path` (so as to not process the same image twice) 4. call the function `process_image()` through an `executor`, which allows us to execute 4 API calls in parallel {% hint style="info" %} If you want, you can increase the value of the argument `max_workers` to run more API calls in parallel. Keep in mind though that the API is [rate limited to 60 calls/minutes](/getting-started/frequently-asked-questions#q-is-there-a-rate-limiting). {% endhint %} ## Step 3: Running the script We're almost there, the last thing we need is to actually run the script. To do this, we'll add this final piece of code: ```python if __name__ == "__main__": SPREADSHEET_PATH = "./path_to_spreadsheet.xlsx" COLUMN_NAME = "Image URL" OUTPUT_DIRECTORY = "./output/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_spreadsheet(spreadsheet_path=SPREADSHEET_PATH, column_name=COLUMN_NAME, result_directory_path=OUTPUT_DIRECTORY) ``` Then, all that's left is to actually run the script using the terminal: ```bash $ pip install requests openpyxl # run once to install the third-party libraries $ python script.py ``` ## Conclusion In this tutorial, we saw how to use a Python script to easily process images whose URLs are store inside an Excel spreadsheet with the Photoroom API. ## Download the code sample Here's the entire code sample, if you want to easily save it to a file: ```python import concurrent.futures import openpyxl import os import requests API_KEY = "REPLACE_WITH_YOUR_API_KEY" def process_image(input_image_url, output_image_path): try: url = "https://image-api.photoroom.com/v2/edit" query_string = { "background.color": "FFFFFFFF", "outputSize": "1000x1000", "padding": "0.1", "imageUrl": input_image_url } headers = { "Accept": "image/png", "x-api-key": API_KEY } response = requests.get(url, headers=headers, params=query_string) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def iterate_over_spreadsheet(spreadsheet_path, column_name, result_directory_path): # Load the spreadsheet wb = openpyxl.load_workbook(spreadsheet_path) image_urls = [] # Loop over all sheets in the workbook for sheet_name in wb.sheetnames: sheet = wb[sheet_name] for col_num, col_cells in enumerate(sheet.iter_cols(values_only=True)): if col_cells[0] == column_name: break else: print(f"Column {column_name} not found in sheet {sheet_name}.") continue for cell in sheet.iter_rows(min_row=2, min_col=col_num + 1, max_col=col_num + 1): if cell[0].value: image_urls.append(cell[0].value) with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor: for image_url in image_urls: # Extracting the filename from the URL, stripping query parameters if any base_name = os.path.basename(image_url.split('?')[0]) # Getting the filename without its original extension and appending '.png' result_file_name = os.path.splitext(base_name)[0] + '.png' result_path = os.path.join(result_directory_path, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, image_url, result_path) if __name__ == "__main__": SPREADSHEET_PATH = "./path_to_spreadsheet.xlsx" COLUMN_NAME = "Image URL" OUTPUT_DIRECTORY = "./output/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_spreadsheet(spreadsheet_path=SPREADSHEET_PATH, column_name=COLUMN_NAME, result_directory_path=OUTPUT_DIRECTORY) ``` # How to process images from Google Drive using Zapier [Zapier](https://zapier.com) is a popular no-code tool that allows you to easily integrate and automate multiple tools. In this tutorial, you'll learn how to use Zapier to create an integration that: 1. Watches a Google Drive folder to detect new images 2. Sends the new images to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) 3. Saves the result of the API call to another Google Drive folder ## Step 1: Watching a Google Drive folder In Zapier, first create a new Zap, click to configure its *Trigger* and then select *Google Drive*:
Then, select the event *New File in Folder*:
Next, configure the connection to your Google Drive account and select the *Folder* where you will deposit the images that you want to process:
## Step 2: Processing Images through the Image Editing API Now that you've configured the event that will trigger your Zap, it's time to configure the action that your Zap will execute. To do this, click on *Action*, search for "Photoroom" and pick *Photoroom (latest)*:
Next, you'll set the *Event* to choose which API you want to call. In this tutorial, we want to call the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide):
{% hint style="info" %} As you can notice, our Zapier integration also allows you to call our [Remove Background API](/remove-background-api-basic-plan/quickstart-guide). {% endhint %} Then, you'll need to input your API key so that Zapier can call the Photoroom API on your behalf:
{% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} Finally, you need to configure the parameters of the API call. First, you'll set the value of the `imageFile` argument to be the data of the file that has been added to the Google Drive folder:
Then, you can also add additional fields for the edits that you want to apply to the image. Here we're setting an `outputSize` of `1000x1000` and a `padding` of `10%`:
## Step 3: Uploading the Result to Google Drive You're almost finished, now you just need to upload the image returned by the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) back to Google Drive. To do this, you'll add a new Google Drive *Step*:
Then, to configure this *Action*, you'll first set the *Event* to *Upload File*:
And then you'll set: * the *Drive* and *Folder* where we want to save the result * the content of the *File* to the data returned by the API call * the *File Name* to that of the original file
## Step 4: Testing the Integration That's it, you've finished implementing your Zap! You can click to *Publish* it:
And now that your Zap has been published, it's time to test it! To do this, you'll simply add some images to the Google Drive folder that your Zap has been configured to watch:
And then you can move to the folder that's been configured to receive the results and after a few moments you'll see the processed images appear:
## Conclusion In this tutorial, we saw how to use Zapier to easily integrate Google Drive with the Photoroom API. We took the example of watching a Google Drive folder and automatically processing images through the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide), but it's of course possible to modify the workflow to: * replace Google Drive with another storing service * call another Photoroom API, like the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) * add additional steps to run some logic specific to your use case # How to process images from Google Drive using Make.com [Make.com](https://www.make.com/) is a popular no-code tool that allows you to easily design and run powerful workflows. In this tutorial, you'll learn how to use Make.com to create a workflow that: 1. Watches a Google Drive folder to detect new images 2. Sends the new images to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) 3. Saves the result of the API call to another Google Drive folder ## Step 1: Watching a Google Drive folder In Make.com, first create a new scenario:
Then, create a new *Google Drive* module, with the action *Watch Files in a Folder*:
Then, configure the module to select the Google Drive folder that you want to watch:
Here, I'm watching a folder called *Images to process* that's stored at the root of my Google Drive. ## Step 2: Downloading files from Google Drive The next step will be to download the image file from Google Drive, so that Make.com can send it to the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). To do that, connect to the first module another *Google Drive* module called *Download a File*:
Then, configure this new module to download a file using the *File ID* fetched by the previous module.
## Step 3: Calling the Image Editing API Now that we have downloaded the input image file, we're ready to call the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). To implement the API call, we're going to add another module called *HTTP* with the action *Make a request*:
Next, we need to configure this module. First, we set the URL of the endpoint we're calling:
Then, we set the *Method* of the request to *POST*:
Next, we add a header that sets the API key:
{% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} Then, we set the *Body type* to *Multipart/form-data*:
Next, we add a first *Field* to the request, to upload the file that was downloaded by the previous module:
And finally, we add additional fields for the edits that we want to apply to the image. Here I'm setting an `outputSize` of `1000x1000` and a `padding` of `10%`:
## Step 4: Uploading the result to Google Drive Now that we've implemented the API call, we're down to the last step: uploading the result to a Google Drive folder. First, we add an *Image* module with the action *Convert a format*:
We'll configure this module so that it uses the data returned by the API call to create an image file, with the same name than that of the original image:
Then, we can add a final *Google Drive* module with the action *Upload a File*:
And finally, we configure this module to upload the result of the previous one to the desired Google Drive folder:
## Step 5: Running the workflow Now that everything has been configured, running the workflow will be pretty easy. You can use the controls at the bottom left of the screen to either: * Run the workflow one time * Schedule it so that it's run every N minutes
The best practice we recommend is to first use *Run once* to test the worflow with a small number of images, and then enable the *Scheduling* to watch the Google Drive folder and process new images automatically. ## Conclusion In this tutorial, we saw how to use Make.com to easily integrate Google Drive with the Photoroom API. We took the example of watching a Google Drive folder and automatically processing images through the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide), but it's of course possible to modify the workflow to: * replace Google Drive with another storing service * call another Photoroom API, like the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) * add additional steps to run some logic specific to your use case # How to process images using an iOS or macOS Shortcut Apple Shortcuts is an app that comes built-in with recent versions of iOS and macOS, and that provides users with a no-code editor to create and execute workflows. Because Shortcurts support making HTTP calls, you can implement a Shortcut that integrates with the Photoroom API. And with such a Shortcut, it becomes possible to easily process a batch of images through the Photoroom API directly from inside the Finder, Files or Photos app:

Calling the Shortcut on macOS

Calling the Shortcut on iOS

## Download the Shortcut We actually took care of implementing such a Shortcut, you can [download it here](https://www.icloud.com/shortcuts/9400603f6f6f4a8abdb8da46dd6d5744). {% hint style="warning" %} The Shortcut needs to be configured with an API Key in order to be functionnal. The instructions on how to do it are [available just below on this page](#step-3-calling-the-photoroom-api). {% endhint %} If you open the Shortcut, you will see that this is the workflow that it contains:
This workflow can be broken down into 4 main steps that we're going to explore in more details. ## How the Shortcut works ### Step 1: Invoking the Shortcut with the images to process
The Shortcut has been configured so that it's very easy to invoke. It can be invoked from two places: * through the *Quick Actions* menu, as demonstrated in the demo at the beginning of the page. This is the recommended way to invoke the Shortcut in macOS. * from the *Share Sheet*, which is usually accessible by tapping this button . This is the recommended way to invoke the Shortcut in iOS. ### Step 2: Converting the images to JPEG The next step takes care of automatically converting the images to JPEG, to make sure that they are in a format that is compatible with the Photoroom API.
{% hint style="info" %} This step is important, because pictures taken with an iOS device are by default saved using the `.heic` format, which is not supported by the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). {% endhint %} ### Step 3: Calling the Photoroom API After that, the following step is to actually call the Photoroom API:
{% hint style="info" %} In this example the Shortcut is calling the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide), but it would of course possible to call the [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) instead. {% endhint %} Here, make sure that you replace the placeholder *REPLACE\_WITH\_YOUR\_API\_KEY* with your actual API Key:
{% hint style="info" %} If you don't have an API key, here are the [steps to create yours](/#how-can-i-get-my-api-key). {% endhint %} The image and the set of edits that will be applied to it are passed inside of the *Request Body*:
In this example, the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) will: * remove the background to isolate the main subject of the image * center it inside a square of 1000x1000 pixels, with 5% of padding and a transparent background * add a realistic shadow that simulates a soft lighting You can of course modify the parameters of the call to update the edits that will be applied to the image in order to match your own requirements and brand guidelines. More details about the list of available edits are available in the documentation of the [Image Editing API](/image-editing-api-plus-plan/quickstart-guide). ### Step 4: Saving the processed images Finally, the last step is to save the processed images that have been returned by the Photoroom API. For this, we simply ask the user to select the directory where the result images should be saved:
## Conclusion In this tutorial, we've covered how it's possible in iOS and macOS to easily process a batch of th Photoroom API in iOS or macOS by using an Apple Shortcut. If you want to give it a try, don't forget that the Shortcut we've covered can be [downloaded here](https://www.icloud.com/shortcuts/9400603f6f6f4a8abdb8da46dd6d5744). # How to correct the perspective of trading cards in an iOS app Photos of flat items such as trading cards, book covers, documents or packaging are rarely taken perfectly straight on. The result is a skewed rectangle on a cluttered background, which looks poor in a listing and is hard to compare with other items. This tutorial walks through **Card Straight**, an open-source demo iPhone app that photographs a trading card, uses the Remove Background API to find the card's edges, straightens it on-device, and optionally produces a blurred, relit background with the Image Editing API. The full source code is available on GitHub: [Photoroom/api-demo-apps → iOS Perspective Correction App](https://github.com/Photoroom/api-demo-apps/tree/main/iOS%20Perspective%20Correction%20App) (MIT license). ### What the app produces From a single photo, the app creates two kinds of results: * **Transparent**: a tight, perspective-corrected cutout of the card, exported as a PNG with transparency. * **Background blur + relight**: the card straightened in place, with the original background kept but blurred and the lighting harmonized, exported as a JPEG. | *(original photo)* | *Transparent finish* | *Background blur + relight finish* | | :-------------------------------------------------------------------------------------------------------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------: | | ![](https://raw.githubusercontent.com/Photoroom/api-demo-apps/main/iOS%20Perspective%20Correction%20App/docs/examples/charizard-original.jpg) | ![](https://raw.githubusercontent.com/Photoroom/api-demo-apps/main/iOS%20Perspective%20Correction%20App/docs/examples/charizard-transparent.png) | ![](https://raw.githubusercontent.com/Photoroom/api-demo-apps/main/iOS%20Perspective%20Correction%20App/docs/examples/charizard-blurred.jpg) | | ![](https://raw.githubusercontent.com/Photoroom/api-demo-apps/main/iOS%20Perspective%20Correction%20App/docs/examples/mew-original.jpg) | ![](https://raw.githubusercontent.com/Photoroom/api-demo-apps/main/iOS%20Perspective%20Correction%20App/docs/examples/mew-transparent.png) | ![](https://raw.githubusercontent.com/Photoroom/api-demo-apps/main/iOS%20Perspective%20Correction%20App/docs/examples/mew-blurred.jpg) | {% hint style="info" %} The interesting part of this app is the division of labour: **Photoroom does the hard perception work** (where is the card in the image) while **the phone does the geometry it is uniquely placed to do**: warping the pixels to a rectangle, and using its own camera calibration to work out the card's true proportions. The API is called once per photo for the transparent finish, and once more only if the user asks for the blurred finish. {% endhint %} ### Running the app You need Xcode, an iPhone running iOS 17 or later (the Simulator works for everything except the camera), and a Photoroom API key. If you don't have one yet, here are [the steps to create yours](/#how-can-i-get-my-api-key). 1. Clone the repository and open `iOS Perspective Correction App/ios-perspective-correction.xcodeproj` in Xcode. 2. Select the `ios-perspective-correction` scheme and an iPhone destination. On a physical device, pick your development team under *Signing & Capabilities*. 3. Build and run. Tap the gear icon and paste your API key: it is stored in the device Keychain and never bundled in the app or logged. 4. Tap **Take a photo** and point the camera at a single, fully visible card on a contrasting background. Automatic capture fires once the card is stable and sharp; you can also use the shutter, **Choose from library**, or **Try a sample card** (nine bundled photos that work in the Simulator). 5. Review the result, adjust **Proportions** or **Rotate** if needed, pick the finish in **Settings → Finish**, then save or share. {% hint style="info" %} Use Sandbox mode while you explore: prepend `sandbox_` to your API key and calls are free (results are watermarked). {% endhint %} ### How it works The pipeline has four stages. Two of them call the Photoroom API; the other two run entirely on the device. #### Step 1: Capture and normalize the photo `CameraCapture.swift` does more than take a picture: it configures the session so that each frame comes with a trustworthy **camera intrinsic matrix** (focal length and optical centre, in pixels). It picks the rear physical wide-angle camera, prefers the 4K preset and falls back to 1080p, locks the zoom factor to 1, turns off video stabilization (which crops and shifts the frame), enables geometric distortion correction where supported, and turns on `isCameraIntrinsicMatrixDeliveryEnabled` on the connection. The captured still is the exact video sample buffer that passed the auto-capture checks, read together with its `kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix` attachment, rather than a separate full-resolution photo whose intrinsics could differ. ```swift session.sessionPreset = session.canSetSessionPreset(.hd4K3840x2160) ? .hd4K3840x2160 : .hd1920x1080 device.videoZoomFactor = 1 if connection.isVideoStabilizationSupported { connection.preferredVideoStabilizationMode = .off } if connection.isCameraIntrinsicMatrixDeliverySupported { connection.isCameraIntrinsicMatrixDeliveryEnabled = true } // Later, for the captured frame: let intrinsics = CMGetAttachment(sampleBuffer, key: kCMSampleBufferAttachmentKey_CameraIntrinsicMatrix, attachmentModeOut: nil) as? Data ``` Orientation is handled with `AVCaptureDevice.RotationCoordinator`: sensor pixels are left unrotated, the closest cardinal EXIF orientation is attached to the JPEG, and the same orientation is stored alongside the calibration. This matters in Step 3, where the app has to undo orientation and resizing before it can project detected corners into calibrated camera coordinates; otherwise it would pair a portrait, cropped image with a landscape, full-frame matrix. Before anything is sent to Photoroom, `CardProcessor.swift` applies the EXIF orientation and downsizes the photo to at most 3,000 pixels on its longest edge: ```swift let original = CGImageSourceCreateThumbnailAtIndex(source, 0, [ kCGImageSourceCreateThumbnailFromImageAlways: true, kCGImageSourceCreateThumbnailWithTransform: true, // bake in EXIF rotation kCGImageSourceThumbnailMaxPixelSize: 3000 ] as CFDictionary) ``` Both steps matter for API integrations in general: the Remove Background API doesn't carry EXIF metadata into its result, so an un-rotated upload comes back rotated (see Troubleshooting), and a smaller upload means a faster round trip with no visible loss for this use case. The shutter can also fire on its own. An on-device Vision rectangle detector checks preview frames at about 5 Hz; once a whole card is visible, the app waits 0.6 s for aiming, gives autofocus up to 1.2 s to settle, then requires two sufficiently sharp frames (Laplacian variance on a 256×256 patch of the card's interior, threshold 80) 0.15–0.5 s apart before capturing. None of these preview frames are sent to Photoroom, only the single captured frame is, so automatic capture costs nothing in API calls. Manual capture, library import and the bundled samples remain available; the [README](https://github.com/Photoroom/api-demo-apps/blob/main/iOS%20Perspective%20Correction%20App/README.md#automatic-proportions-and-capture) documents the heuristics in full. #### Step 2: Get a segmentation mask from Photoroom Rather than asking for the cutout, the app asks the Remove Background API for the **segmentation mask** by setting `channels=alpha` (see Download the segmentation mask). The equivalent curl call is: ```bash curl --request POST \ --url https://sdk.photoroom.com/v1/segment \ --header 'x-api-key: YOUR_API_KEY' \ --form image_file=@/path/to/card.jpg \ --form channels=alpha \ --output mask.png ``` In Swift, `Processing/PhotoroomClient.swift` builds the same multipart request by hand with `URLSession`, with no third-party dependency: ```swift var request = URLRequest(url: URL(string: "https://sdk.photoroom.com/v1/segment")!) request.httpMethod = "POST" request.timeoutInterval = 90 request.setValue(apiKey, forHTTPHeaderField: "x-api-key") request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type") request.setValue("image/png", forHTTPHeaderField: "Accept") var body = Data() body.append("--\(boundary)\r\nContent-Disposition: form-data; name=\"image_file\"; filename=\"card.jpg\"\r\nContent-Type: image/jpeg\r\n\r\n") body.append(imageData) body.append("\r\n--\(boundary)\r\nContent-Disposition: form-data; name=\"channels\"\r\n\r\nalpha\r\n") body.append("--\(boundary)--\r\n") request.httpBody = body ``` Why the mask rather than the cutout? The app needs the mask twice: once as a binary image to *find the card's corners*, and once at full resolution to *make the background transparent*. Requesting the grayscale mask gives it both from a single, smaller response. The mask is then used in two ways in `CardProcessor.finish`: * It is downscaled to at most 1,600 pixels and thresholded into a binary image for the geometry step below. * It is composited onto the original photo as its alpha channel (`CIBlendWithAlphaMask`), which removes the background, including around the card's rounded corners, *before* the perspective warp. #### Step 3: Find the corners and straighten the card on-device `Processing/CardGeometry.swift` turns the binary mask into four corners without any machine learning, using only classic image geometry: 1. Flood-fill the background from the image border, so that enclosed holes inside the card don't affect its outline. 2. Keep the largest connected foreground component (the card, or a graded slab if that is what was segmented). 3. Compute its convex hull and simplify it to four significant vertices. 4. Assign the boundary pixels to the four sides and fit a line to each with two passes of robust least squares, which trims rounded corners and stray pixels. 5. Intersect the four lines to get the corners, order them, and reject detections whose confidence or fill ratio is too low. With the corners known, Core Image's `CIPerspectiveCorrection` filter warps the transparent cutout into a rectangle. **Recovering the card's true proportions from the camera** A perspective warp needs to know the target rectangle's width-to-height ratio, and the photo alone cannot tell you: a square seen at an angle and a tall rectangle seen straight on can produce the same four corners. This is where the camera intrinsics from Step 1 come in. `Processing/CameraCalibration.swift` first maps the four corners found on the (rotated, resized) mask back to the unrotated sensor frame, then applies the inverse intrinsic matrix to turn each corner into a viewing ray. For a flat rectangle, the first two columns of the homography from the unit square to those rays are the two physical side vectors, up to a common scale, so the ratio of their lengths is the card's real width/height ratio. The estimate is discarded when the calibration is invalid, when the recovered sides are not close to perpendicular (orthogonality above 0.12), when the ratio falls outside 0.2–5, or when perturbing the corners by a few pixels changes the ratio by more than 6%, which indicates the corners are too imprecise to trust. ```swift guard let base = solve(corners), (0.2...5).contains(base.ratio), base.orthogonality < 0.12 else { return nil } // ... re-solve with slightly perturbed corners ... guard uncertainty < 0.06 else { return nil } return AspectRatioEstimate(widthOverHeight: base.ratio, relativeUncertainty: uncertainty) ``` This is why the **Proportions** control behaves differently depending on where the photo came from. Photos taken in the app have intrinsics, so proportions default to **Automatic**. Photos imported from the library have none, so the app shows apparent proportions as a preview and waits for the user to pick the **Standard card** preset (2.5 : 3.5) or enter **Custom** dimensions before exporting. In both cases the estimate concerns proportions only, not physical size in millimeters. Changing proportions or rotating the result re-renders locally from the retained cutout and mask and **never triggers another API call**. Finally, an on-device text-recognition pass (Vision) compares the four possible orientations and rotates the card upright when printed text clearly favors one of them. #### Step 4 (optional): Blur and relight the background with two Image Editing API calls If the user selects the **Background blur** finish, the app warps the *whole photo* (not just the cutout) so that the card becomes a rectangle while its surroundings are kept, then sends this image to the Image Editing API twice. The first call uses AI Expand to fill the transparent borders that the warp leaves around the photo: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@perspective-corrected-card.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form expand.mode=ai.auto \ --output expanded.png ``` The second call takes the expanded image and applies Background Blur and AI Relight, exporting a JPEG: ```bash curl --request POST \ --url https://image-api.photoroom.com/v2/edit \ --header 'x-api-key: YOUR_API_KEY' \ --form imageFile=@expanded.png \ --form removeBackground=false \ --form referenceBox=originalImage \ --form background.blur.mode=gaussian \ --form background.blur.radius=0.012 \ --form lighting.mode=ai.preserve-hue-and-saturation \ --form export.format=jpeg \ --output result.jpg ``` A few details worth noting in these two calls: * `removeBackground=false` keeps the original background so it can be expanded, then blurred. Photoroom still detects the subject internally, which is how the blur is applied to the background only. * `referenceBox=originalImage` tells the API to treat the whole canvas, not the cropped subject, as the frame of reference, so the framing of the input image is preserved exactly. * `lighting.mode=ai.preserve-hue-and-saturation` improves the lighting while keeping the card's colours faithful, which matters for collectibles. Turning **Relight** off in the app simply omits this field. In `PhotoroomClient.swift`, the two calls are chained, with a cancellation check between them so that switching finish mid-way doesn't waste a request: ```swift func blurredFinish(image: Data, apiKey: String, relight: Bool = true) async throws -> Data { let expanded = try await send(Self.finishRequest(image: image, apiKey: apiKey, step: .expand)) try Task.checkCancellation() return try await send(Self.finishRequest(image: expanded, apiKey: apiKey, step: .blur, relight: relight)) } ``` After the JPEG comes back, the app crops it to the card's rectified bounds with 5% padding, so the final image is framed the same way as the "Original" it is compared against. ### Handling errors The client maps HTTP status codes to user-facing messages, which is a good pattern to reuse in any mobile integration: ```swift static func responseError(status: Int) -> PhotoroomError { switch status { case 401, 403: .invalidKey // missing or rejected API key case 402: .credits // no API credits left case 429: .rateLimited // default limit is 60 images per minute default: .server(status) } } ``` Each case produces a recoverable error in the UI (a *Retry* button, or a prompt to check the key in Settings), and an in-flight request is cancelled if the user starts a new capture. Timeouts are set generously (90 s for segmentation, 180 s for the AI edits), because AI features on large images can take several seconds. ### Adapting the app to your use case Although the demo is built around trading cards, nothing in the API calls is specific to them. The same pipeline works for any flat rectangular item: comics, vinyl sleeves, book covers, boxed products, ID cards or documents. Here's how to adapt it: * **Different proportions**: the aspect-ratio acceptance range in `CardGeometry.swift` is 1:1 to 5:1, and the *Standard card* preset (2.5 : 3.5) is just a default. Add presets for your item's dimensions. * **A different finish**: the second Image Editing API call is where the look is decided. Replace the blur with a solid `background.color`, an AI Background generated from a `background.prompt`, or add an AI Shadow with `shadow.mode`. Use the *Try it now!* button on each feature page to find the parameters, then paste them into `finishRequest`. * **Server-side processing**: if you'd rather not ship API keys in a mobile app, move `PhotoroomClient` behind your own backend and keep the on-device geometry as is. The API calls are plain multipart HTTP requests and translate directly to any language; see Code Samples. * **Batch processing**: the `Scripts/GenerateReadmeExamples.swift` script in the repository runs the exact same processing code on macOS from the command line, which is a convenient starting point for processing a folder of photos. {% hint style="info" %} Cost per photo: the transparent finish uses **1** Remove Background API call; the blurred finish adds **2** Image Editing API calls. Local adjustments (proportions, rotation, orientation) are free. {% endhint %} ### Going further * Browse the source: [Photoroom/api-demo-apps](https://github.com/Photoroom/api-demo-apps/tree/main/iOS%20Perspective%20Correction%20App) * The repository also contains a [Web demo app](https://github.com/Photoroom/api-demo-apps/tree/main/Web%20Demo%20App) and a general [iOS demo app](https://github.com/Photoroom/api-demo-apps/tree/main/iOS%20Demo%20App). * Related tutorials: How to improve images for second-hand item marketplaces, How to create sticker images. # AI Backgrounds Competitors Benchmark (Claid.ai, Phot.ai, Bria.ai) On this page you will find a comparison of our [AI Backgrounds](/image-editing-api-plus-plan/ai-backgrounds) (using our v3 model) against some of our competitors. ## Feature Comparison
Photoroom APIClaid.ai APIPhot.ai APIBria.ai API
Pricing€0.10 per imagefrom $0.20 per imagefrom $0.18 per imagefrom $0.08 per image
Response time~5 seconds~15 seconds~35 seconds~20 seconds
# of API calls required1 call2 calls1 call1 call
Supports a different aspect ratio than that of the input imageYesYesNoNo
Supports sending an image fileYesYesNoYes
Supports sending an image URLYesYesYesYes
Supports setting the RNG seedYesNoNoYes
## Result Comparison ### Food Images {% tabs %} {% tab title="Image #01" %}
Original Image
Promptthe image displays a plate of vegetables with succulents in the background. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #02" %}
Original Image
Prompta chocolate cupcake with blue frosting on a white marbled tray, with a pastel coloured table in the background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)		This image failed to process
{% endtab %} {% tab title="Image #03" %}
Original Image
Prompta plate of chicken wings and dipping sauces on a black scampered wooden table.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #04" %}
Original Image
Promptthe image displays a piece of bread with avocado and greens on top bathed in a golden light. It has been captured professionally, emphasizing the warm tones and gleaming highlights.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #05" %}
Original Image
Promptthe image displays a bowl with bread and vegetables foregrounded against a breathtaking mountain sunset. The object is set against a picturesque scene of a mountain during sunset.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% endtabs %} ### Cosmetic Images {% tabs %} {% tab title="Image #01" %}
Original Image
Promptthe image displays a bottle with a pink substance surrounded by cherry blossom. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #02" %}
Original Image
Promptthe image displays a tube of false lashes in a bathroom. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #03" %}
Original Image
Promptthe image displays an orange plastic bottle with a pump top on a tropical beach on a bright day with a slightly blurred background of the ocean
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #04" %}
Original Image
Promptthe image displays a tube of lotion on a cream marble countertop. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #05" %}
Original Image
Promptthe image displays a spray bottle sitting on top on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% endtabs %} ### Apparel Images {% tabs %} {% tab title="Image #01" %}
Original Image
Promptthe image displays a jacket hanging on a wall standing against a baby blue background. The background is plain, textureless, doesn't have any discernible objects or patterns, and its color is baby blue
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #02" %}
Original Image
Prompta baseball cap on a baseball field, with a bright sun in the background
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #03" %}
Original Image
Prompta crocheted poncho on a fluffy blanket, with a soft green grass field in the background
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #04" %}
Original Image
Promptthe image displays a group of three people standing set against an autumn-themed backdrop, captivating the essence of fall season.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #05" %}
Original Image
Promptthe image illustrates a person walking set against a breathtaking mountain view. It exudes a professionalism in composition and performance.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% endtabs %} ### Jewelry Images {% tabs %} {% tab title="Image #01" %}
Original Image
Promptthe image displays a ring with a pink stone on a cream marble countertop. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #02" %}
Original Image
Prompta long necklace on a black velvet cushion, with a cream stone wall in the background
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #03" %}
Original Image
Promptthe image displays a pair of earrings on a green marble countertop. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #04" %}
Original Image
Promptthe image displays a pair of wedding rings sitting next to each other on a concrete countertop. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #05" %}
Original Image
Promptthe image displays a necklace in a cozy home. The image features a minimalistic and professional looking background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% endtabs %} ### People Images {% tabs %} {% tab title="Image #01" %}
Original Image
Prompta person standing with their eyes closed on an old, twisted brick wall, with a grey field in the background
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #02" %}
Original Image
Promptthe image features a person walking on a boulder with a breathtaking mountain view in the background.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #03" %}
Original Image
Promptthe image displays a person wearing glasses and a green shirt with New York in the background. The overall scenery in the background is typical and instantly transports you to New York
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #04" %}
Original Image
Promptthe image displays a person riding a skateboard set against an autumn-themed backdrop, captivating the essence of fall season.
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% tab title="Image #05" %}
Original Image
Promptthe image displays a person holding a suit case on a tropical beach on a bright day with a slightly blurred background of the ocean
Photoroom API
(response time: ~5 seconds)
Claid.ai API
(response time: ~15 seconds)
Phot.ai API
(response time: ~35 seconds, doesn't support changing the aspect ratio)
Bria.ai API
(response time: ~20 seconds, doesn't support changing the aspect ratio)
{% endtab %} {% endtabs %} ## Reproducing the results If you want to reproduce the results of this benchmark, here are the Python scripts that were used to generate the images. {% tabs %} {% tab title="Photoroom API" %} ```python import os import requests import concurrent.futures API_KEY = "YOUR_PHOTOROOM_API_KEY" SEEDS = [117879368, 55994449, 48672244, 65080068] def process_image(image_url, prompt, variant_index, output_image_path): try: url = "https://image-api.photoroom.com/v2/edit" params = { "imageUrl": image_url, "referenceBox": "originalImage", "outputSize": "1024x1024", "background.prompt": prompt, "background.negativePrompt": "oversaturated, ugly, 3d, render, cartoon, grain, low-res, kitsch, text, lens, camera", "background.seed": SEEDS[variant_index] } headers = { "x-api-key": API_KEY, "pr-ai-background-model-version": "3" } response = requests.get(url, params=params, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def iterate_over(image_urls, prompts, file_names, result_directory): with concurrent.futures.ThreadPoolExecutor(max_workers=8) as executor: root = os.getcwd() for image_url, prompt, file_name in zip(image_urls, prompts, file_names): file_path = os.path.join(root, file_name) for variant in range(0, 5): result_file_name = f"photoroom-{file_name}-variant_{variant+1}.png" result_path = os.path.join(result_directory, result_file_name) executor.submit(process_image, image_url, prompt, variant, result_path) if __name__ == "__main__": # FOOD FOOD_IMAGES_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F1.jpg?alt=media&token=850ab5be-a503-40f1-a270-c7cdcc62bdeb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F2.png?alt=media&token=9c6e5512-efb8-47bc-b45d-01cb5b00b698", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F3.jpg?alt=media&token=04851dba-83bc-4d24-9549-ad029a838c33", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F4.jpeg?alt=media&token=191746c4-c528-4e2f-9e04-e1cac0b8d4b9", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F5.jpeg?alt=media&token=97421dcf-14b0-4353-913e-03428341e274", ] FOOD_PROMPTS = [ "the image displays a plate of vegetables with succulents in the background. The image features a minimalistic and professional looking background.", "a chocolate cupcake with blue frosting on a white marbled tray, with a pastel coloured table in the background", "a plate of chicken wings and dipping sauces on a black scampered wooden table.", "the image displays a piece of bread with avocado and greens on top bathed in a golden light. It has been captured professionally, emphasizing the warm tones and gleaming highlights.", "the image displays a bowl with bread and vegetables foregrounded against a breathtaking mountain sunset. The object is set against a picturesque scene of a mountain during sunset.", ] FOOD_OUTPUT_DIRECTORY = "./output-photoroom/food/" if not os.path.exists(FOOD_OUTPUT_DIRECTORY): os.makedirs(FOOD_OUTPUT_DIRECTORY) iterate_over(image_urls=FOOD_IMAGES_URLS, prompts=FOOD_PROMPTS, file_names=list(map(str, range(1, len(FOOD_IMAGES_URLS) + 1))), result_directory=FOOD_OUTPUT_DIRECTORY) # COSMETIC COSMETIC_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F1.jpeg?alt=media&token=837a3a2c-4621-44bc-84d7-ca1bafd7dad7", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F2.jpeg?alt=media&token=9327b3b6-68a6-4106-88cc-978afa5c048e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F3.png?alt=media&token=6c25d2aa-4a11-4b00-bac6-b98f59289b5c", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F4.jpg?alt=media&token=be6075e1-b754-4f98-8937-cba8d234942d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F5.jpg?alt=media&token=982083a1-b8df-40f7-88cc-c9185670f162", ] COSMETIC_PROMPTS = [ "the image displays a bottle with a pink substance surrounded by cherry blossom. The image features a minimalistic and professional looking background.", "the image displays a tube of false lashes in a bathroom. The image features a minimalistic and professional looking background.", "the image displays an orange plastic bottle with a pump top on a tropical beach on a bright day with a slightly blurred background of the ocean", "the image displays a tube of lotion on a cream marble countertop. The image features a minimalistic and professional looking background.", "the image displays a spray bottle sitting on top on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry", ] COSMETIC_OUTPUT_DIRECTORY = "./output-photoroom/cosmetic/" if not os.path.exists(COSMETIC_OUTPUT_DIRECTORY): os.makedirs(COSMETIC_OUTPUT_DIRECTORY) iterate_over(image_urls=COSMETIC_IMAGE_URLS, prompts=COSMETIC_PROMPTS, file_names=list(map(str, range(1, len(COSMETIC_IMAGE_URLS) + 1))), result_directory=COSMETIC_OUTPUT_DIRECTORY) # APPAREL APPAREL_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F1.jpeg?alt=media&token=462bd079-f084-4a97-bdf5-51e1ea6454a3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F2.jpg?alt=media&token=7666a271-93c8-4fa5-bf46-e550f2832189", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F3.jpg?alt=media&token=3551ca21-e31a-4076-b810-1bc0aacbaceb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F4.jpg?alt=media&token=4a2d0c5d-b44a-479f-bc35-64fcc3d3d366", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F5.jpeg?alt=media&token=4624dafe-959b-4bfc-b230-7785780abcf7", ] APPAREL_PROMPTS = [ "the image displays a jacket hanging on a wall standing against a baby blue background. The background is plain, textureless, doesn't have any discernible objects or patterns, and its color is baby blue", "a baseball cap on a baseball field, with a bright sun in the background", "a crocheted poncho on a fluffy blanket, with a soft green grass field in the background", "the image displays a group of three people standing set against an autumn-themed backdrop, captivating the essence of fall season.", "the image illustrates a person walking set against a breathtaking mountain view. It exudes a professionalism in composition and performance.", ] APPAREL_OUTPUT_DIRECTORY = "./output-photoroom/apparel/" if not os.path.exists(APPAREL_OUTPUT_DIRECTORY): os.makedirs(APPAREL_OUTPUT_DIRECTORY) iterate_over(image_urls=APPAREL_IMAGE_URLS, prompts=APPAREL_PROMPTS, file_names=list(map(str, range(1, len(APPAREL_IMAGE_URLS) + 1))), result_directory=APPAREL_OUTPUT_DIRECTORY) # JEWELRY JEWELRY_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F1.jpg?alt=media&token=0afec946-38cf-4773-a96a-d0c158358557", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F2.jpg?alt=media&token=9b93ee57-9343-4611-8156-76c512149002", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F3.jpg?alt=media&token=925a455c-1b58-469d-95c7-7db4ff5ac61e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F4.jpg?alt=media&token=c694560d-951d-4fe5-8390-a4c5df846f51", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F5.jpg?alt=media&token=38205d4d-ce4f-4168-9a91-94d872aed3fe", ] JEWELRY_PROMPTS = [ "the image displays a ring with a pink stone on a cream marble countertop. The image features a minimalistic and professional looking background.", "a long necklace on a black velvet cushion, with a cream stone wall in the background", "the image displays a pair of earrings on a green marble countertop. The image features a minimalistic and professional looking background.", "the image displays a pair of wedding rings sitting next to each other on a concrete countertop. The image features a minimalistic and professional looking background.", "the image displays a necklace in a cozy home. The image features a minimalistic and professional looking background.", ] JEWELRY_OUTPUT_DIRECTORY = "./output-photoroom/jewelry/" if not os.path.exists(JEWELRY_OUTPUT_DIRECTORY): os.makedirs(JEWELRY_OUTPUT_DIRECTORY) iterate_over(image_urls=JEWELRY_IMAGE_URLS, prompts=JEWELRY_PROMPTS, file_names=list(map(str, range(1, len(JEWELRY_IMAGE_URLS) + 1))), result_directory=JEWELRY_OUTPUT_DIRECTORY) # PEOPLE PEOPLE_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F1.jpg?alt=media&token=5b57a70d-e94d-4056-8e48-2b8a2c296028", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F2.jpg?alt=media&token=f0e8a0bb-9fd7-4cc3-bd90-b5655321d46d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F3.jpg?alt=media&token=37ade83a-611e-4346-b4fe-5ee484f69ea3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F4.jpg?alt=media&token=3569a732-9be2-4b2d-b685-c55a1093fca8", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F5.jpg?alt=media&token=38875d9b-8f48-4bec-a30a-ca10be2b86d5", ] PEOPLE_PROMPTS = [ "a person standing with their eyes closed on an old, twisted brick wall, with a grey field in the background", "the image features a person walking on a boulder with a breathtaking mountain view in the background.", "the image displays a person wearing glasses and a green shirt with New York in the background. The overall scenery in the background is typical and instantly transports you to New York", "the image displays a person riding a skateboard set against an autumn-themed backdrop, captivating the essence of fall season.", "the image displays a person holding a suit case on a tropical beach on a bright day with a slightly blurred background of the ocean", ] PEOPLE_OUTPUT_DIRECTORY = "./output-photoroom/people/" if not os.path.exists(PEOPLE_OUTPUT_DIRECTORY): os.makedirs(PEOPLE_OUTPUT_DIRECTORY) iterate_over(image_urls=PEOPLE_IMAGE_URLS, prompts=PEOPLE_PROMPTS, file_names=list(map(str, range(1, len(PEOPLE_IMAGE_URLS) + 1))), result_directory=PEOPLE_OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Claid.ai API" %} {% hint style="info" %} Please note that: * Claid.ai requires to make a first API call to remove the original background, then make a second call to generate the new background * Claid.ai doesn't support [providing the seed of the random number generator](https://docs.photoroom.com/resources/pages/HApfqZOrLZgScroTLTtk#background.seed), so you will **not** get exactly the same results than the ones shown above {% endhint %} ```python import os import requests API_KEY = "YOUR_CLAID_AI_API_KEY" def remove_background(input_image_url): try: url = "https://api.claid.ai/v1-beta1/image/edit" payload = { "input": input_image_url, "operations": { "background": { "remove": True }, "resizing": { "width": 1024, "height": 1024, "fit": "bounds" } }, "output": { "format": "png" } } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) response.raise_for_status() data = response.json() tmp_url = data['data']['output']['tmp_url'] print(f"Background Removed: {tmp_url}") return tmp_url except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def generate_background(input_image_url, prompt, input_file_name, output_directory): try: url = "https://api.claid.ai/v1-ea/scene/create" payload = { "object": { "image_url": input_image_url, "placement_type": "original" }, "scene": { "prompt": prompt, "negative_prompt": "oversaturated, ugly, 3d, render, cartoon, grain, low-res, kitsch, text, lens, camera" } } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) response.raise_for_status() data = response.json() for index, variant in zip(range(1, 5), data['data']['output']): variant_url = variant['tmp_url'] response = requests.get(variant_url) response.raise_for_status() # To ensure the request was successful variant_file_name = os.path.join(output_directory, f"claid-ai-{input_file_name}-variant_{index}.png") with open(variant_file_name, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {variant_file_name}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def process_image(input_image_url, prompt, input_file_name, output_directory): background_removed_url = remove_background(input_image_url) generate_background(background_removed_url, prompt, input_file_name, output_directory) def iterate_over(image_urls, prompts, file_names, result_directory): for image_url, prompt, file_name in zip(image_urls, prompts, file_names): process_image(image_url, prompt, file_name, result_directory) if __name__ == "__main__": # FOOD FOOD_IMAGES_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F1.jpg?alt=media&token=850ab5be-a503-40f1-a270-c7cdcc62bdeb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F2.png?alt=media&token=9c6e5512-efb8-47bc-b45d-01cb5b00b698", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F3.jpg?alt=media&token=04851dba-83bc-4d24-9549-ad029a838c33", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F4.jpeg?alt=media&token=191746c4-c528-4e2f-9e04-e1cac0b8d4b9", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F5.jpeg?alt=media&token=97421dcf-14b0-4353-913e-03428341e274", ] FOOD_PROMPTS = [ "the image displays a plate of vegetables with succulents in the background. The image features a minimalistic and professional looking background.", "a chocolate cupcake with blue frosting on a white marbled tray, with a pastel coloured table in the background", "a plate of chicken wings and dipping sauces on a black scampered wooden table.", "the image displays a piece of bread with avocado and greens on top bathed in a golden light. It has been captured professionally, emphasizing the warm tones and gleaming highlights.", "the image displays a bowl with bread and vegetables foregrounded against a breathtaking mountain sunset. The object is set against a picturesque scene of a mountain during sunset.", ] FOOD_OUTPUT_DIRECTORY = "./output-claid-ai/food/" if not os.path.exists(FOOD_OUTPUT_DIRECTORY): os.makedirs(FOOD_OUTPUT_DIRECTORY) iterate_over(image_urls=FOOD_IMAGES_URLS, prompts=FOOD_PROMPTS, file_names=list(map(str, range(1, len(FOOD_IMAGES_URLS) + 1))), result_directory=FOOD_OUTPUT_DIRECTORY) # COSMETIC COSMETIC_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F1.jpeg?alt=media&token=837a3a2c-4621-44bc-84d7-ca1bafd7dad7", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F2.jpeg?alt=media&token=9327b3b6-68a6-4106-88cc-978afa5c048e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F3.png?alt=media&token=6c25d2aa-4a11-4b00-bac6-b98f59289b5c", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F4.jpg?alt=media&token=be6075e1-b754-4f98-8937-cba8d234942d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F5.jpg?alt=media&token=982083a1-b8df-40f7-88cc-c9185670f162", ] COSMETIC_PROMPTS = [ "the image displays a bottle with a pink substance surrounded by cherry blossom. The image features a minimalistic and professional looking background.", "the image displays a tube of false lashes in a bathroom. The image features a minimalistic and professional looking background.", "the image displays an orange plastic bottle with a pump top on a tropical beach on a bright day with a slightly blurred background of the ocean", "the image displays a tube of lotion on a cream marble countertop. The image features a minimalistic and professional looking background.", "the image displays a spray bottle sitting on top on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry", ] COSMETIC_OUTPUT_DIRECTORY = "./output-claid-ai/cosmetic/" if not os.path.exists(COSMETIC_OUTPUT_DIRECTORY): os.makedirs(COSMETIC_OUTPUT_DIRECTORY) iterate_over(image_urls=COSMETIC_IMAGE_URLS, prompts=COSMETIC_PROMPTS, file_names=list(map(str, range(1, len(COSMETIC_IMAGE_URLS) + 1))), result_directory=COSMETIC_OUTPUT_DIRECTORY) # APPAREL APPAREL_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F1.jpeg?alt=media&token=462bd079-f084-4a97-bdf5-51e1ea6454a3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F2.jpg?alt=media&token=7666a271-93c8-4fa5-bf46-e550f2832189", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F3.jpg?alt=media&token=3551ca21-e31a-4076-b810-1bc0aacbaceb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F4.jpg?alt=media&token=4a2d0c5d-b44a-479f-bc35-64fcc3d3d366", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F5.jpeg?alt=media&token=4624dafe-959b-4bfc-b230-7785780abcf7", ] APPAREL_PROMPTS = [ "the image displays a jacket hanging on a wall standing against a baby blue background. The background is plain, textureless, doesn't have any discernible objects or patterns, and its color is baby blue", "a baseball cap on a baseball field, with a bright sun in the background", "a crocheted poncho on a fluffy blanket, with a soft green grass field in the background", "the image displays a group of three people standing set against an autumn-themed backdrop, captivating the essence of fall season.", "the image illustrates a person walking set against a breathtaking mountain view. It exudes a professionalism in composition and performance.", ] APPAREL_OUTPUT_DIRECTORY = "./output-claid-ai/apparel/" if not os.path.exists(APPAREL_OUTPUT_DIRECTORY): os.makedirs(APPAREL_OUTPUT_DIRECTORY) iterate_over(image_urls=APPAREL_IMAGE_URLS, prompts=APPAREL_PROMPTS, file_names=list(map(str, range(1, len(APPAREL_IMAGE_URLS) + 1))), result_directory=APPAREL_OUTPUT_DIRECTORY) # JEWELRY JEWELRY_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F1.jpg?alt=media&token=0afec946-38cf-4773-a96a-d0c158358557", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F2.jpg?alt=media&token=9b93ee57-9343-4611-8156-76c512149002", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F3.jpg?alt=media&token=925a455c-1b58-469d-95c7-7db4ff5ac61e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F4.jpg?alt=media&token=c694560d-951d-4fe5-8390-a4c5df846f51", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F5.jpg?alt=media&token=38205d4d-ce4f-4168-9a91-94d872aed3fe", ] JEWELRY_PROMPTS = [ "the image displays a ring with a pink stone on a cream marble countertop. The image features a minimalistic and professional looking background.", "a long necklace on a black velvet cushion, with a cream stone wall in the background", "the image displays a pair of earrings on a green marble countertop. The image features a minimalistic and professional looking background.", "the image displays a pair of wedding rings sitting next to each other on a concrete countertop. The image features a minimalistic and professional looking background.", "the image displays a necklace in a cozy home. The image features a minimalistic and professional looking background.", ] JEWELRY_OUTPUT_DIRECTORY = "./output-claid-ai/jewelry/" if not os.path.exists(JEWELRY_OUTPUT_DIRECTORY): os.makedirs(JEWELRY_OUTPUT_DIRECTORY) iterate_over(image_urls=JEWELRY_IMAGE_URLS, prompts=JEWELRY_PROMPTS, file_names=list(map(str, range(1, len(JEWELRY_IMAGE_URLS) + 1))), result_directory=JEWELRY_OUTPUT_DIRECTORY) # PEOPLE PEOPLE_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F1.jpg?alt=media&token=5b57a70d-e94d-4056-8e48-2b8a2c296028", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F2.jpg?alt=media&token=f0e8a0bb-9fd7-4cc3-bd90-b5655321d46d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F3.jpg?alt=media&token=37ade83a-611e-4346-b4fe-5ee484f69ea3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F4.jpg?alt=media&token=3569a732-9be2-4b2d-b685-c55a1093fca8", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F5.jpg?alt=media&token=38875d9b-8f48-4bec-a30a-ca10be2b86d5", ] PEOPLE_PROMPTS = [ "a person standing with their eyes closed on an old, twisted brick wall, with a grey field in the background", "the image features a person walking on a boulder with a breathtaking mountain view in the background.", "the image displays a person wearing glasses and a green shirt with New York in the background. The overall scenery in the background is typical and instantly transports you to New York", "the image displays a person riding a skateboard set against an autumn-themed backdrop, captivating the essence of fall season.", "the image displays a person holding a suit case on a tropical beach on a bright day with a slightly blurred background of the ocean", ] PEOPLE_OUTPUT_DIRECTORY = "./output-claid-ai/people/" if not os.path.exists(PEOPLE_OUTPUT_DIRECTORY): os.makedirs(PEOPLE_OUTPUT_DIRECTORY) iterate_over(image_urls=PEOPLE_IMAGE_URLS, prompts=PEOPLE_PROMPTS, file_names=list(map(str, range(1, len(PEOPLE_IMAGE_URLS) + 1))), result_directory=PEOPLE_OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Phot.ai API" %} {% hint style="info" %} Please note that: * Phot.ai requires to make a first API call to start the processing, then make a second call to fetch the result. This code sets a delay of 300 seconds before fetching the result to maximize the chances of the result being ready. * Phot.ai doesn't support [providing the seed of the random number generator](https://docs.photoroom.com/resources/pages/HApfqZOrLZgScroTLTtk#background.seed), so you will **not** get exactly the same results than the ones shown above {% endhint %} ```python import os import requests import time import concurrent.futures API_KEY = "YOUR_PHOT_AI_API_KEY" def generate_background(input_image_url, prompt): try: url = "https://prodapi.phot.ai/external/api/v2/user_activity/background-generator" payload = { "file_name": "my-image.jpg", "input_image_link": input_image_url, "prompt": prompt } headers = { "x-api-key": API_KEY, "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) response.raise_for_status() data = response.json() return data['order_id'] except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def download_results(order_id, input_file_name, output_directory): try: url = f"https://prodapi.phot.ai/external/api/v1/user_activity/order-status?order_id={order_id}" headers = { "x-api-key": API_KEY, } response = requests.get(url, headers=headers) response.raise_for_status() data = response.json() for index, output_url in zip(range(1, 5), data['output_urls']): response = requests.get(output_url) response.raise_for_status() # To ensure the request was successful variant_file_name = os.path.join(output_directory, f"phot-ai-{input_file_name}-variant_{index}.webp") with open(variant_file_name, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {variant_file_name}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def process_image(input_image_url, prompt, input_file_name, output_directory): order_id = generate_background(input_image_url, prompt) print(f"order_id: {order_id}") time.sleep(300) # sleep while the results are generated download_results(order_id, input_file_name, output_directory) def iterate_over(image_urls, prompts, file_names, result_directory): with concurrent.futures.ThreadPoolExecutor(max_workers=5) as executor: for image_url, prompt, file_name in zip(image_urls, prompts, file_names): executor.submit(process_image, image_url, prompt, file_name, result_directory) if __name__ == "__main__": # FOOD FOOD_IMAGES_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F1.jpg?alt=media&token=850ab5be-a503-40f1-a270-c7cdcc62bdeb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F2.png?alt=media&token=9c6e5512-efb8-47bc-b45d-01cb5b00b698", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F3.jpg?alt=media&token=04851dba-83bc-4d24-9549-ad029a838c33", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F4.jpeg?alt=media&token=191746c4-c528-4e2f-9e04-e1cac0b8d4b9", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F5.jpeg?alt=media&token=97421dcf-14b0-4353-913e-03428341e274", ] FOOD_PROMPTS = [ "the image displays a plate of vegetables with succulents in the background. The image features a minimalistic and professional looking background.", "a chocolate cupcake with blue frosting on a white marbled tray, with a pastel coloured table in the background", "a plate of chicken wings and dipping sauces on a black scampered wooden table.", "the image displays a piece of bread with avocado and greens on top bathed in a golden light. It has been captured professionally, emphasizing the warm tones and gleaming highlights.", "the image displays a bowl with bread and vegetables foregrounded against a breathtaking mountain sunset. The object is set against a picturesque scene of a mountain during sunset.", ] FOOD_OUTPUT_DIRECTORY = "./output-phot-ai/food/" if not os.path.exists(FOOD_OUTPUT_DIRECTORY): os.makedirs(FOOD_OUTPUT_DIRECTORY) iterate_over(image_urls=FOOD_IMAGES_URLS, prompts=FOOD_PROMPTS, file_names=list(map(str, range(1, len(FOOD_IMAGES_URLS) + 1))), result_directory=FOOD_OUTPUT_DIRECTORY) # COSMETIC COSMETIC_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F1.jpeg?alt=media&token=837a3a2c-4621-44bc-84d7-ca1bafd7dad7", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F2.jpeg?alt=media&token=9327b3b6-68a6-4106-88cc-978afa5c048e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F3.png?alt=media&token=6c25d2aa-4a11-4b00-bac6-b98f59289b5c", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F4.jpg?alt=media&token=be6075e1-b754-4f98-8937-cba8d234942d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F5.jpg?alt=media&token=982083a1-b8df-40f7-88cc-c9185670f162", ] COSMETIC_PROMPTS = [ "the image displays a bottle with a pink substance surrounded by cherry blossom. The image features a minimalistic and professional looking background.", "the image displays a tube of false lashes in a bathroom. The image features a minimalistic and professional looking background.", "the image displays an orange plastic bottle with a pump top on a tropical beach on a bright day with a slightly blurred background of the ocean", "the image displays a tube of lotion on a cream marble countertop. The image features a minimalistic and professional looking background.", "the image displays a spray bottle sitting on top on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry", ] COSMETIC_OUTPUT_DIRECTORY = "./output-phot-ai/cosmetic/" if not os.path.exists(COSMETIC_OUTPUT_DIRECTORY): os.makedirs(COSMETIC_OUTPUT_DIRECTORY) iterate_over(image_urls=COSMETIC_IMAGE_URLS, prompts=COSMETIC_PROMPTS, file_names=list(map(str, range(1, len(COSMETIC_IMAGE_URLS) + 1))), result_directory=COSMETIC_OUTPUT_DIRECTORY) # APPAREL APPAREL_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F1.jpeg?alt=media&token=462bd079-f084-4a97-bdf5-51e1ea6454a3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F2.jpg?alt=media&token=7666a271-93c8-4fa5-bf46-e550f2832189", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F3.jpg?alt=media&token=3551ca21-e31a-4076-b810-1bc0aacbaceb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F4.jpg?alt=media&token=4a2d0c5d-b44a-479f-bc35-64fcc3d3d366", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F5.jpeg?alt=media&token=4624dafe-959b-4bfc-b230-7785780abcf7", ] APPAREL_PROMPTS = [ "the image displays a jacket hanging on a wall standing against a baby blue background. The background is plain, textureless, doesn't have any discernible objects or patterns, and its color is baby blue", "a baseball cap on a baseball field, with a bright sun in the background", "a crocheted poncho on a fluffy blanket, with a soft green grass field in the background", "the image displays a group of three people standing set against an autumn-themed backdrop, captivating the essence of fall season.", "the image illustrates a person walking set against a breathtaking mountain view. It exudes a professionalism in composition and performance.", ] APPAREL_OUTPUT_DIRECTORY = "./output-phot-ai/apparel/" if not os.path.exists(APPAREL_OUTPUT_DIRECTORY): os.makedirs(APPAREL_OUTPUT_DIRECTORY) iterate_over(image_urls=APPAREL_IMAGE_URLS, prompts=APPAREL_PROMPTS, file_names=list(map(str, range(1, len(APPAREL_IMAGE_URLS) + 1))), result_directory=APPAREL_OUTPUT_DIRECTORY) # JEWELRY JEWELRY_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F1.jpg?alt=media&token=0afec946-38cf-4773-a96a-d0c158358557", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F2.jpg?alt=media&token=9b93ee57-9343-4611-8156-76c512149002", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F3.jpg?alt=media&token=925a455c-1b58-469d-95c7-7db4ff5ac61e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F4.jpg?alt=media&token=c694560d-951d-4fe5-8390-a4c5df846f51", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F5.jpg?alt=media&token=38205d4d-ce4f-4168-9a91-94d872aed3fe", ] JEWELRY_PROMPTS = [ "the image displays a ring with a pink stone on a cream marble countertop. The image features a minimalistic and professional looking background.", "a long necklace on a black velvet cushion, with a cream stone wall in the background", "the image displays a pair of earrings on a green marble countertop. The image features a minimalistic and professional looking background.", "the image displays a pair of wedding rings sitting next to each other on a concrete countertop. The image features a minimalistic and professional looking background.", "the image displays a necklace in a cozy home. The image features a minimalistic and professional looking background.", ] JEWELRY_OUTPUT_DIRECTORY = "./output-phot-ai/jewelry/" if not os.path.exists(JEWELRY_OUTPUT_DIRECTORY): os.makedirs(JEWELRY_OUTPUT_DIRECTORY) iterate_over(image_urls=JEWELRY_IMAGE_URLS, prompts=JEWELRY_PROMPTS, file_names=list(map(str, range(1, len(JEWELRY_IMAGE_URLS) + 1))), result_directory=JEWELRY_OUTPUT_DIRECTORY) # PEOPLE PEOPLE_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F1.jpg?alt=media&token=5b57a70d-e94d-4056-8e48-2b8a2c296028", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F2.jpg?alt=media&token=f0e8a0bb-9fd7-4cc3-bd90-b5655321d46d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F3.jpg?alt=media&token=37ade83a-611e-4346-b4fe-5ee484f69ea3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F4.jpg?alt=media&token=3569a732-9be2-4b2d-b685-c55a1093fca8", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F5.jpg?alt=media&token=38875d9b-8f48-4bec-a30a-ca10be2b86d5", ] PEOPLE_PROMPTS = [ "a person standing with their eyes closed on an old, twisted brick wall, with a grey field in the background", "the image features a person walking on a boulder with a breathtaking mountain view in the background.", "the image displays a person wearing glasses and a green shirt with New York in the background. The overall scenery in the background is typical and instantly transports you to New York", "the image displays a person riding a skateboard set against an autumn-themed backdrop, captivating the essence of fall season.", "the image displays a person holding a suit case on a tropical beach on a bright day with a slightly blurred background of the ocean", ] PEOPLE_OUTPUT_DIRECTORY = "./output-phot-ai/people/" if not os.path.exists(PEOPLE_OUTPUT_DIRECTORY): os.makedirs(PEOPLE_OUTPUT_DIRECTORY) iterate_over(image_urls=PEOPLE_IMAGE_URLS, prompts=PEOPLE_PROMPTS, file_names=list(map(str, range(1, len(PEOPLE_IMAGE_URLS) + 1))), result_directory=PEOPLE_OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Bria.ai" %} ```python import os import requests API_KEY = "YOUR_BRIA_API_KEY" SEED = 117879368 def process_image(input_image_url, prompt, input_file_name, output_directory): try: url = "https://engine.prod.bria-api.com/v1/background/replace" payload = { "image_url": input_image_url, "sync": True, "bg_prompt": prompt, "negative_prompt": "oversaturated, ugly, 3d, render, cartoon, grain, low-res, kitsch, text, lens, camera", "refine_prompt": True, "num_results": 4, "seed": SEED } headers = { "api_token": API_KEY, "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers, timeout=300) response.raise_for_status() data = response.json() for index, result in zip(range(1, 5), data['result']): response = requests.get(result[0]) response.raise_for_status() # To ensure the request was successful variant_file_name = os.path.join(output_directory, f"bria-ai-{input_file_name}-variant_{index}.png") with open(variant_file_name, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {variant_file_name}") except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def iterate_over(image_urls, prompts, file_names, result_directory): for image_url, prompt, file_name in zip(image_urls, prompts, file_names): process_image(image_url, prompt, file_name, result_directory) if __name__ == "__main__": # FOOD FOOD_IMAGES_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F1.jpg?alt=media&token=850ab5be-a503-40f1-a270-c7cdcc62bdeb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F2.png?alt=media&token=9c6e5512-efb8-47bc-b45d-01cb5b00b698", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F3.jpg?alt=media&token=04851dba-83bc-4d24-9549-ad029a838c33", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F4.jpeg?alt=media&token=191746c4-c528-4e2f-9e04-e1cac0b8d4b9", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Ffood%2F5.jpeg?alt=media&token=97421dcf-14b0-4353-913e-03428341e274", ] FOOD_PROMPTS = [ "the image displays a plate of vegetables with succulents in the background. The image features a minimalistic and professional looking background.", "a chocolate cupcake with blue frosting on a white marbled tray, with a pastel coloured table in the background", "a plate of chicken wings and dipping sauces on a black scampered wooden table.", "the image displays a piece of bread with avocado and greens on top bathed in a golden light. It has been captured professionally, emphasizing the warm tones and gleaming highlights.", "the image displays a bowl with bread and vegetables foregrounded against a breathtaking mountain sunset. The object is set against a picturesque scene of a mountain during sunset.", ] FOOD_OUTPUT_DIRECTORY = "./output-bria-ai/food/" if not os.path.exists(FOOD_OUTPUT_DIRECTORY): os.makedirs(FOOD_OUTPUT_DIRECTORY) iterate_over(image_urls=FOOD_IMAGES_URLS, prompts=FOOD_PROMPTS, file_names=list(map(str, range(1, len(FOOD_IMAGES_URLS) + 1))), result_directory=FOOD_OUTPUT_DIRECTORY) # COSMETIC COSMETIC_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F1.jpeg?alt=media&token=837a3a2c-4621-44bc-84d7-ca1bafd7dad7", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F2.jpeg?alt=media&token=9327b3b6-68a6-4106-88cc-978afa5c048e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F3.png?alt=media&token=6c25d2aa-4a11-4b00-bac6-b98f59289b5c", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F4.jpg?alt=media&token=be6075e1-b754-4f98-8937-cba8d234942d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fcosmetic%2F5.jpg?alt=media&token=982083a1-b8df-40f7-88cc-c9185670f162", ] COSMETIC_PROMPTS = [ "the image displays a bottle with a pink substance surrounded by cherry blossom. The image features a minimalistic and professional looking background.", "the image displays a tube of false lashes in a bathroom. The image features a minimalistic and professional looking background.", "the image displays an orange plastic bottle with a pump top on a tropical beach on a bright day with a slightly blurred background of the ocean", "the image displays a tube of lotion on a cream marble countertop. The image features a minimalistic and professional looking background.", "the image displays a spray bottle sitting on top on a table with a beautiful orange yellow sunset where the clouds are brightly lit from the sunset and a field is in the background slightly blurry", ] COSMETIC_OUTPUT_DIRECTORY = "./output-bria-ai/cosmetic/" if not os.path.exists(COSMETIC_OUTPUT_DIRECTORY): os.makedirs(COSMETIC_OUTPUT_DIRECTORY) iterate_over(image_urls=COSMETIC_IMAGE_URLS, prompts=COSMETIC_PROMPTS, file_names=list(map(str, range(1, len(COSMETIC_IMAGE_URLS) + 1))), result_directory=COSMETIC_OUTPUT_DIRECTORY) # APPAREL APPAREL_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F1.jpeg?alt=media&token=462bd079-f084-4a97-bdf5-51e1ea6454a3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F2.jpg?alt=media&token=7666a271-93c8-4fa5-bf46-e550f2832189", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F3.jpg?alt=media&token=3551ca21-e31a-4076-b810-1bc0aacbaceb", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F4.jpg?alt=media&token=4a2d0c5d-b44a-479f-bc35-64fcc3d3d366", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fapparel%2F5.jpeg?alt=media&token=4624dafe-959b-4bfc-b230-7785780abcf7", ] APPAREL_PROMPTS = [ "the image displays a jacket hanging on a wall standing against a baby blue background. The background is plain, textureless, doesn't have any discernible objects or patterns, and its color is baby blue", "a baseball cap on a baseball field, with a bright sun in the background", "a crocheted poncho on a fluffy blanket, with a soft green grass field in the background", "the image displays a group of three people standing set against an autumn-themed backdrop, captivating the essence of fall season.", "the image illustrates a person walking set against a breathtaking mountain view. It exudes a professionalism in composition and performance.", ] APPAREL_OUTPUT_DIRECTORY = "./output-bria-ai/apparel/" if not os.path.exists(APPAREL_OUTPUT_DIRECTORY): os.makedirs(APPAREL_OUTPUT_DIRECTORY) iterate_over(image_urls=APPAREL_IMAGE_URLS, prompts=APPAREL_PROMPTS, file_names=list(map(str, range(1, len(APPAREL_IMAGE_URLS) + 1))), result_directory=APPAREL_OUTPUT_DIRECTORY) # JEWELRY JEWELRY_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F1.jpg?alt=media&token=0afec946-38cf-4773-a96a-d0c158358557", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F2.jpg?alt=media&token=9b93ee57-9343-4611-8156-76c512149002", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F3.jpg?alt=media&token=925a455c-1b58-469d-95c7-7db4ff5ac61e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F4.jpg?alt=media&token=c694560d-951d-4fe5-8390-a4c5df846f51", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fjewelry%2F5.jpg?alt=media&token=38205d4d-ce4f-4168-9a91-94d872aed3fe", ] JEWELRY_PROMPTS = [ "the image displays a ring with a pink stone on a cream marble countertop. The image features a minimalistic and professional looking background.", "a long necklace on a black velvet cushion, with a cream stone wall in the background", "the image displays a pair of earrings on a green marble countertop. The image features a minimalistic and professional looking background.", "the image displays a pair of wedding rings sitting next to each other on a concrete countertop. The image features a minimalistic and professional looking background.", "the image displays a necklace in a cozy home. The image features a minimalistic and professional looking background.", ] JEWELRY_OUTPUT_DIRECTORY = "./output-bria-ai/jewelry/" if not os.path.exists(JEWELRY_OUTPUT_DIRECTORY): os.makedirs(JEWELRY_OUTPUT_DIRECTORY) iterate_over(image_urls=JEWELRY_IMAGE_URLS, prompts=JEWELRY_PROMPTS, file_names=list(map(str, range(1, len(JEWELRY_IMAGE_URLS) + 1))), result_directory=JEWELRY_OUTPUT_DIRECTORY) # PEOPLE PEOPLE_IMAGE_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F1.jpg?alt=media&token=5b57a70d-e94d-4056-8e48-2b8a2c296028", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F2.jpg?alt=media&token=f0e8a0bb-9fd7-4cc3-bd90-b5655321d46d", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F3.jpg?alt=media&token=37ade83a-611e-4346-b4fe-5ee484f69ea3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F4.jpg?alt=media&token=3569a732-9be2-4b2d-b685-c55a1093fca8", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fai-backgrounds%2Fpeople%2F5.jpg?alt=media&token=38875d9b-8f48-4bec-a30a-ca10be2b86d5", ] PEOPLE_PROMPTS = [ "a person standing with their eyes closed on an old, twisted brick wall, with a grey field in the background", "the image features a person walking on a boulder with a breathtaking mountain view in the background.", "the image displays a person wearing glasses and a green shirt with New York in the background. The overall scenery in the background is typical and instantly transports you to New York", "the image displays a person riding a skateboard set against an autumn-themed backdrop, captivating the essence of fall season.", "the image displays a person holding a suit case on a tropical beach on a bright day with a slightly blurred background of the ocean", ] PEOPLE_OUTPUT_DIRECTORY = "./output-bria-ai/people/" if not os.path.exists(PEOPLE_OUTPUT_DIRECTORY): os.makedirs(PEOPLE_OUTPUT_DIRECTORY) iterate_over(image_urls=PEOPLE_IMAGE_URLS, prompts=PEOPLE_PROMPTS, file_names=list(map(str, range(1, len(PEOPLE_IMAGE_URLS) + 1))), result_directory=PEOPLE_OUTPUT_DIRECTORY) ``` {% endtab %} {% endtabs %} # Remove Background Competitors Benchmark (Remove.bg, Clipdrop, SAM, Azure) On this page you will find a comparison of our [Remove Background API](/remove-background-api-basic-plan/quickstart-guide) against some of our competitors. For additional information about the important features to look for in image background removal technology, you can also [consult this blog article](https://www.photoroom.com/blog/image-background-removal-technology-comparison). ## Result Comparison {% hint style="info" %} If you want to compare two results in details, we recommend using this website: {% endhint %} ### Home Decoration Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #04" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #05" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #06" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #07" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #08" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #09" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #10" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### Furniture Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #04" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #05" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### Apparel Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)		This image failed to process
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #04" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #05" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### Food Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### Cosmetic Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #04" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)		This image failed to process
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #05" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### Jewelry Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### People Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #04" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #05" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ### Industry Images {% tabs %} {% tab title="Image #01" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #02" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #03" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% tab title="Image #04" %}
Original Image
Photoroom API
(response time: ~450 milliseconds)
Remove.bg API
(response time: ~600 milliseconds)
Clipdrop API
(response time: ~2 seconds, doesn't support cropping to the bounds of the subject)
Segment Anything Model (SAM)
(response time: depends on the machine running the model)
Azure Background Removal API
(response time: ~2 seconds)
{% endtab %} {% endtabs %} ## Reproducing the results If you want to reproduce the results of this benchmark, here are the Python scripts that were used to generate the images. {% tabs %} {% tab title="Photoroom API" %} {% hint style="info" %} Before running this code, please download the original images that you want to re-process, and place them in a directory called `original-images.` {% endhint %} ```python import os import requests import concurrent.futures API_KEY = "YOUR_PHOTOROOM_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://sdk.photoroom.com/v1/segment" with open(input_image_path, 'rb') as image_file: files = { "image_file": image_file } headers = { "Accept": "image/png, application/json", "pr-background-removal-model-version": "2024-09-26", "x-api-key": API_KEY } response = requests.post(url, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)} ({input_image_path})") return str(e) def iterate_over_directory(directory_path, result_directory): with concurrent.futures.ThreadPoolExecutor(max_workers=16) as executor: for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '.png' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-photoroom/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Remove.bg API" %} {% hint style="info" %} Before running this code, please download the original images that you want to re-process, and place them in a directory called `original-images`. {% endhint %} ```python import os import requests API_KEY = "YOUR_REMOVE_BG_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://api.remove.bg/v1.0/removebg" with open(input_image_path, 'rb') as image_file: files = { "image_file": image_file } payload = { "size": "auto" } headers = { "Accept": "image/png, application/json", "x-api-key": API_KEY } response = requests.post(url, data=payload, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)} ({input_image_path})") return str(e) def iterate_over_directory(directory_path, result_directory): for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '.png' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images process_image(file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-remove-bg/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Clipdrop API" %} {% hint style="info" %} Before running this code, please download the original images that you want to re-process, and place them in a directory called `original-images`. {% endhint %} ```python import os import requests API_KEY = "YOUR_CLIPDROP_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://clipdrop-api.co/remove-background/v1" with open(input_image_path, 'rb') as image_file: files = { "image_file": image_file } payload = { "transparency_handling": "discard_alpha_layer" } headers = { "Accept": "image/png", "x-api-key": API_KEY } response = requests.post(url, data=payload, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)} ({input_image_path})") return str(e) def iterate_over_directory(directory_path, result_directory): for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '.png' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images process_image(file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-clipdrop/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="SAM" %} {% hint style="info" %} Before running this code please: * download the original images that you want to re-process, and place them in a directory called `original-images` * run the command: `pip install pillow rembg` {% endhint %} ```python from PIL import Image from rembg import new_session, remove import os MODEL_NAME = "sam" SESSION = new_session(MODEL_NAME) def process_image(input_image_path, output_image_path): input = Image.open(input_image_path) output = remove(input) output.save(output_image_path) print(f"Image saved to {output_image_path}") def iterate_over_directory(directory_path, result_directory): for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '-sam.png' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images process_image(file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-sam/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Azure Background Removal API" %} {% hint style="info" %} Before running this code, please download the original images that you want to re-process, and place them in a directory called `original-images.` {% endhint %} ```python import os import requests API_ENDPOINT = "YOUR_AZURE_ENDPOINT" API_KEY = "YOUR_AZURE_API_KEY" def process_image(input_image_path, output_image_path): try: url = API_ENDPOINT + "computervision/imageanalysis:segment?api-version=2023-02-01-preview&mode=backgroundRemoval" with open(input_image_path, 'rb') as image_file: headers = { "Content-Type": "application/octet-stream", "Ocp-Apim-Subscription-Key": API_KEY } response = requests.post(url, data=image_file, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)} ({input_image_path})") return str(e) def iterate_over_directory(directory_path, result_directory): for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '-azure.png' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images process_image(file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-azure/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% endtabs %} # Grocery Delivery Image API Benchmark (Claid.ai, Picsart) On this page you will find a comparison of our [Image Editing API](/image-editing-api-plus-plan/quickstart-guide) against some of our competitors, on the specific use case of Grocery Delivery images. ## Use Case description Grocery delivery services need to display an image for each product on their catalog: * it makes it much easier for the user to navigate that catalog * it helps the user build trust that they are buying the correct product Additionally, it's important that all these images follow the same brand guidelines, such as: * 16:9 aspect ratio * white background * centered product, with 10% padding However, it's not trivial to come up with such images. You might have to deal with vendor images that all have different backgrounds and aspect ratios:
Or you might also have to handle images that were taken directly inside the store:
## Results ### UGC Images {% tabs %} {% tab title="Original Images" %}
{% endtab %} {% tab title="Photoroom API" %}
{% endtab %} {% tab title="Claid.ai API" %}
{% hint style="info" %} Claid.ai API doesn't support [positioning the subject](/image-editing-api-plus-plan/positioning) to occupy all the space available, minus some padding. {% endhint %} {% endtab %} {% tab title="Picsart API" %}
{% hint style="info" %} Picsart API doesn't support [positioning the subject](/image-editing-api-plus-plan/positioning) to occupy all the space available, minus some padding. {% endhint %} {% endtab %} {% endtabs %} ### Vendor Images {% tabs %} {% tab title="Original Images" %}
{% endtab %} {% tab title="Photoroom API" %}
{% endtab %} {% tab title="Claid.ai API" %}
{% hint style="info" %} Claid.ai API doesn't support [positioning the subject](/image-editing-api-plus-plan/positioning) to occupy all the space available, minus some padding. {% endhint %} {% endtab %} {% tab title="Picsart API" %}
{% hint style="info" %} Please note that: * Picsart API doesn't support [positioning the subject](/image-editing-api-plus-plan/positioning) to occupy all the space available, minus some padding * Image #08 being fully white is what was returned by Picsart API {% endhint %} {% endtab %} {% endtabs %} ## Reproducing the results If you want to reproduce the results of this benchmark, here are the Python scripts that were used to generate the images. {% tabs %} {% tab title="Photoroom API" %} {% hint style="info" %} Before running this code, please download the original images that you want to re-process and place them in a directory called `original-images`. {% endhint %} ```python import os import requests import concurrent.futures API_KEY = "YOUR_PHOTOROOM_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://image-api.photoroom.com/v2/edit" with open(input_image_path, 'rb') as image_file: files = { "imageFile": image_file } headers = { "x-api-key": API_KEY } payload = { "outputSize": "1920x1080", "export.format": "jpg", "background.color": "white", "padding": "0.1", "ignorePaddingAndSnapOnCroppedSides": "false", "lighting.mode": "ai.auto", } response = requests.post(url, data=payload, files=files, headers=headers) response.raise_for_status() with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)} ({input_image_path})") return str(e) def iterate_over_directory(directory_path, result_directory): with concurrent.futures.ThreadPoolExecutor(max_workers=16) as executor: for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '-photoroom.jpg' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-photoroom/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Claid.ai API" %} ```python import os import requests API_KEY = "YOUR_CLAID_AI_API_KEY" def process_image(input_image_url, file_name, output_directory): try: url = "https://api.claid.ai/v1-beta1/image/edit" payload = { "input": input_image_url, "operations": { "background": { "remove": True, "color": "#ffffff", }, "resizing": { "width": 1920, "height": 1080, "fit": "canvas" }, "padding": "10%", }, "output": { "format": "png" } } headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) response.raise_for_status() data = response.json() tmp_url = data['data']['output']['tmp_url'] response = requests.get(tmp_url) response.raise_for_status() # To ensure the request was successful output_image_path = os.path.join(output_directory, f"claid-ai-{file_name}.png") with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") return tmp_url except requests.RequestException as e: print(f"Error: {str(e)}") return str(e) def iterate_over(image_urls, file_names, result_directory): for image_url, file_name in zip(image_urls, file_names): process_image(image_url, file_name, result_directory) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" # UGC UGC_OUTPUT_DIRECTORY = "./result-claid-ai/UGC" if not os.path.exists(UGC_OUTPUT_DIRECTORY): os.makedirs(UGC_OUTPUT_DIRECTORY) UGC_IMAGES_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00001.png?alt=media&token=7be569f4-bfca-4bee-85b4-c41456d8d51a", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00002.jpg?alt=media&token=1897e16e-0976-4678-afef-4c84cae8944e", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00003.jpg?alt=media&token=89da64fe-1e99-43c0-b973-b7bf8d0fa087", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00004.jpg?alt=media&token=ccfd60a4-5e72-4dc6-9593-1172260b2f9a", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00005.jpg?alt=media&token=d3ce2f60-cb09-4021-9ce6-8ac6abf389c9", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00006.jpg?alt=media&token=4c6e7292-8ec0-4077-88a4-d87446d67c57", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00008.jpg?alt=media&token=c6ae512f-e8dd-45bc-91ba-16a5ce7481b1", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00009.png?alt=media&token=96e9716c-7b7a-4a62-921b-a1dbf6ef1c73", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00010.png?alt=media&token=c56f5a7d-ec06-4264-b86e-d678ced54730", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00011.png?alt=media&token=f0db0074-a90c-4ef1-85a5-3d48c1e53748", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FUGC%2FUGC00012.jpg?alt=media&token=2c76fee2-77f3-4f7f-8cfb-d189a9735139", ] # Vendor VENDOR_OUTPUT_DIRECTORY = "./result-claid-ai/Vendor" if not os.path.exists(VENDOR_OUTPUT_DIRECTORY): os.makedirs(VENDOR_OUTPUT_DIRECTORY) VENDOR_IMAGES_URLS = [ "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00001.jpg?alt=media&token=a5ee4335-4891-498e-a41c-80851aece10c", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00002.jpg?alt=media&token=a9118cc1-af0e-4556-b9d8-61fed070fcc7", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00003.jpeg?alt=media&token=adf4edda-cf10-43ae-a4e8-7deaf7ca303a", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00004.jpg?alt=media&token=7e4dc31e-5156-47af-b818-4ab09a82dd57", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00005.jpeg?alt=media&token=1d47bbfd-9f7d-48cc-b49e-ac4eaf1888a3", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00006.png?alt=media&token=18255a50-f3bb-4f70-a356-c924eefbeb88", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00007.jpg?alt=media&token=dc66699e-680a-4414-92f6-6a5f5e218e79", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00008.png?alt=media&token=1223e09e-e789-4a5c-8c9d-b7a5adc95fbe", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00009.png?alt=media&token=4c0e5ccb-4199-4f07-bf24-2e62e54a0955", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00010.png?alt=media&token=9f5144a7-9ed0-41d4-8039-ebb6c4282207", "https://firebasestorage.googleapis.com/v0/b/photoroom-demos.appspot.com/o/api-benchmark%2Fgrocery-images%2FVendor%2FVendor00011.jpeg?alt=media&token=e792985a-6392-47a9-9ea3-fc06b78d4aad", ] iterate_over(image_urls=UGC_IMAGES_URLS,file_names=list(map(str, range(1, len(UGC_IMAGES_URLS) + 1))), result_directory=UGC_OUTPUT_DIRECTORY) iterate_over(image_urls=VENDOR_IMAGES_URLS,file_names=list(map(str, range(1, len(VENDOR_IMAGES_URLS) + 1))), result_directory=VENDOR_OUTPUT_DIRECTORY) ``` {% endtab %} {% tab title="Picsart API" %} {% hint style="info" %} Before running this code, please download the original images that you want to re-process and place them in a directory called `original-images`. {% endhint %} ```python import os import requests import concurrent.futures API_KEY = "YOUR_PICSART_API_KEY" def process_image(input_image_path, output_image_path): try: url = "https://api.picsart.io/tools/1.0/removebg" with open(input_image_path, 'rb') as image_file: files = { "image": image_file } headers = { "X-Picsart-API-Key": API_KEY } payload = { "export": "jpg", "bg_width": "1920", "bg_height": "1080", "bg_color": "#ffffff", "auto_center": "true", "scale": "fit", } response = requests.post(url, data=payload, files=files, headers=headers) response.raise_for_status() data = response.json() tmp_url = data['data']['url'] response = requests.get(tmp_url) response.raise_for_status() # To ensure the request was successful with open(output_image_path, 'wb') as f: f.write(response.content) print(f"Image downloaded and saved to {output_image_path}") except requests.RequestException as e: print(f"Error: {str(e)} ({input_image_path})") return str(e) def iterate_over_directory(directory_path, result_directory): with concurrent.futures.ThreadPoolExecutor(max_workers=16) as executor: for root, _, files in os.walk(directory_path): for file in files: if file.lower().endswith(('.png', '.jpg', '.jpeg', '.webp', '.heic')): file_path = os.path.join(root, file) result_file_name = os.path.splitext(os.path.basename(file_path))[0] + '-picsart.jpg' result_file_directory = os.path.join(result_directory, os.path.basename(root)) if not os.path.exists(result_file_directory): os.makedirs(result_file_directory) result_path = os.path.join(result_file_directory, result_file_name) if not os.path.exists(result_path): # don't re-process images executor.submit(process_image, file_path, result_path) if __name__ == "__main__": INPUT_DIRECTORY = "./original-images/" OUTPUT_DIRECTORY = "./result-picsart/" if not os.path.exists(OUTPUT_DIRECTORY): os.makedirs(OUTPUT_DIRECTORY) iterate_over_directory(directory_path=INPUT_DIRECTORY, result_directory=OUTPUT_DIRECTORY) ``` {% endtab %} {% endtabs %}