> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mynth.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Remove Image Background

> Remove the background from an existing image with POST /image/remove-background or the SDK.

Use `POST /image/remove-background` or `mynth.image.removeBackground()` to get a transparent version of a single existing image. Mynth picks the model, so the request has no `model` field. The API creates an async task and returns a `taskId`. The SDK waits for completion by default; use `removeBackgroundAsync()` when you want to poll yourself.

## Pricing

`/image/remove-background` costs **\$0.02 per image**. You are charged only when the task completes successfully.

The cost is reserved up front. If the task fails, the reserve is released. If your balance cannot cover the reserve, the request returns `422 INSUFFICIENT_BALANCE`.

## Remove a background with the SDK

```ts theme={"theme":"kanagawa-dragon"}
import Mynth from "@mynthio/sdk";

const mynth = new Mynth();

const result = await mynth.image.removeBackground({
  url: "https://example.com/product.jpg",
});

console.log(result.image.url); // transparent image
console.log(result.image.format); // "png" | "webp"
console.log(result.image.size); // "1024x768"
console.log(result.cost);
```

### Local files

Pass `file` instead of `url` when the image is local. The SDK uploads first, then calls `/image/remove-background` with the resulting URL. See [Upload input images](/guides/upload-input-images).

```ts theme={"theme":"kanagawa-dragon"}
const result = await mynth.image.removeBackground({
  file, // File or Blob
});
```

## Output format

The result keeps the format the provider returned. Set `output.format` to always get `png` or `webp`. `jpg` is not accepted because it cannot store transparency.

```ts theme={"theme":"kanagawa-dragon"}
const result = await mynth.image.removeBackground({
  url: "https://example.com/product.jpg",
  output: { format: "webp" },
});
```

## Metadata, webhooks, and destinations

The request accepts the same `metadata`, `webhook`, and `destination` fields as [image generation](/reference/image-generation-request):

```ts theme={"theme":"kanagawa-dragon"}
const result = await mynth.image.removeBackground({
  url: "https://example.com/product.jpg",
  metadata: { productId: "sku_1" },
  webhook: { custom: [{ url: "https://example.com/webhooks/mynth" }] },
  destination: "bunny-prod",
});

console.log(result.metadata.productId); // "sku_1"
```

With a destination, `image.url` is the destination URL. If the upload fails, `image.url` is `null` and `image.mynth_url` still points at the Mynth CDN. See [Use Destinations](/guides/use-destinations) and [Use webhooks](/guides/use-webhooks).

## Remove a background with REST

```bash theme={"theme":"kanagawa-dragon"}
curl https://api.mynth.io/image/remove-background \
  -X POST \
  -H "Authorization: Bearer $MYNTH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product.jpg"
  }'
```

Response (`201`):

```json theme={"theme":"kanagawa-dragon"}
{
  "data": {
    "taskId": "tsk_01KE7XWWEQ4MCGWKBQKJ1G47RP",
    "estimatedCost": "0.02",
    "access": {
      "publicAccessToken": "pat_eyJhbGciOi..."
    }
  }
}
```

Poll `/tasks/:id` for the completed result. Full fields live in [Image Remove Background Request](/reference/image-remove-background-request).

## Start now, wait later

Use `removeBackgroundAsync()` when you want to create the task now and wait later. The task carries a Public Access Token, so browser code can poll it without your API key:

```ts theme={"theme":"kanagawa-dragon"}
const task = await mynth.image.removeBackgroundAsync({
  url: "https://example.com/product.jpg",
});

return { id: task.id, access: task.access };
```

Poll `/tasks/:id/status` and `/tasks/:id`, or listen for `task.image.remove_background.completed` / `task.image.remove_background.failed` webhooks.

See [Async and polling](/guides/async-and-polling) and [Browser Polling](/tutorials/browser-polling).

## Task failures

If the background cannot be removed, the task status is `failed`. The SDK's `wait()` throws `TaskAsyncTaskFailedError`.

| Code             | Meaning                                    |
| ---------------- | ------------------------------------------ |
| `INVALID_INPUT`  | The image could not be processed.          |
| `PROVIDER_ERROR` | The provider failed to process the image.  |
| `PROVIDERS_BUSY` | No provider had capacity. Retry shortly.   |
| `TIMEOUT`        | The provider did not respond in time.      |
| `UNKNOWN_ERROR`  | An unexpected error. Retry if it persists. |

## Constraints

| Constraint       | Limit         |
| ---------------- | ------------- |
| URLs per request | 1             |
| Output formats   | `png`, `webp` |
| Metadata size    | 2 KB          |