---
title: "Remove background from a product image"
method: POST
path: "/v1/images/remove-background"
tags: ["Images"]
---

# Remove background from a product image

`POST /v1/images/remove-background`

## Request

- Base URL: `https://api.shopfront.app`
- URL: `https://api.shopfront.app/v1/images/remove-background`
- Auth: HTTP bearer

Standalone background removal via PhotoRoom. This is a separate operation
from image enhancement; the service replaces the background without the
enhancement step.

**How it works:**
1. Submit product image (URL or base64)
2. PhotoRoom segments and replaces the background
3. Returns the result as a base64 data URL (default) or S3 URL

**Return formats:**
- **Base64** (default): Return a base64 data URL
- **URL**: Upload to S3 and return the output URL (set `returnFormat: "url"`)

**Output options:**
- `outputFormat`: `jpg` (default, marketplace-safe), `png` (transparency-capable), `webp`
- `bgColor`: 6-digit hex (default `#FFFFFF`). Ignored if a transparent PNG is preferred.
- `size`: `preview` (0.25MP), `medium` (1.5MP), `hd` (4MP), `full` (up to 36MP, default)
- `crop`: trim transparent borders to the cutout bounding box

**When to choose this vs `/v1/images/enhance`:**
- Use this endpoint when you only need a clean white/coloured background.
- Use `/v1/images/enhance` for studio-style lighting and full enhancement.

## Request body

- ImageRemoveBackgroundRequest: Request payload for `/v1/images/remove-background`. **URL-input notes:** - Only `https://` URLs are accepted. - HTTP redirects (301/302/etc.) are **not** followed — each hop would weaken the SSRF guard, so callers are expected to resolve redirects client-side before submitting. URLs that return a redirect status will fail with `invalid_image`. - Response `Content-Type` must be one of `image/jpeg`, `image/png`, `image/webp`, `image/heic`, or `image/heif`. Other content types (e.g. `text/html` login walls) are rejected.
  - `image` union, required: Image to process (URL or base64)
    - UrlImage
      - `type` 'url', required
      - `url` string, uri, required
    - BackgroundRemovalBase64Image: Base64 image for `/v1/images/remove-background`, which also accepts HEIC and HEIF.
      - `type` 'base64', required
      - `data` string, required
      - `filename` string
  - `options` object
    - `returnFormat` 'url' | 'base64': Format for processed image return (base64 default, url for S3 storage)
    - `outputFormat` 'png' | 'jpg' | 'webp': Output image format. JPG is the default for marketplace compatibility (SHO-897 — eBay rejects WebP). Use PNG for transparency-capable output.
    - `bgColor` string: Background colour as a 6-digit hex code. Ignored when outputFormat=png and transparency is desired.
    - `size` 'preview' | 'medium' | 'hd' | 'full': Output resolution. preview=0.25MP, medium=1.5MP, hd=4MP, full=up to 36MP.
    - `crop` boolean: Crop output to the cutout's bounding box (removes transparent borders).

## Response `200`

Background removed successfully

- ImageRemoveBackgroundResponse: Successful background removal response (200). Error responses use a separate `{ error, message }` shape.
  - `success` boolean, required: Always `true` for this response (200 success path).
  - `originalUrl` string, required: Original image URL when the input is `type: url`. For `type: base64` inputs, the literal string `"base64-input"` — the original data is not echoed back to keep responses small.
  - `outputUrl` string, required: Processed image (base64 data URL by default, or S3 URL if returnFormat=url)
  - `s3Location` object: S3 storage location. Present only when `returnFormat=url`; otherwise the field is absent from the response.
    - `bucket` string
    - `key` string
  - `processingTime` integer, required: Processing time in milliseconds

## Other responses

- `400`: Invalid request
- `401`: Unauthorized - missing or invalid token
- `429`: Rate limit exceeded
- `500`: Background removal failed

---

[API](https://skmtc.dev/shopfront/apis/shopfront-public-api.md) - [All operations](https://skmtc.dev/shopfront/apis/shopfront-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/shopfront/apis/shopfront-public-api/revisions/4dbfb90550d4?raw)