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

# Image Remove Background Request

> Reference for the request body and response shape of POST /image/remove-background.

Endpoint:

```text theme={"theme":"kanagawa-dragon"}
POST https://api.mynth.io/image/remove-background
```

Authentication: API key or OAuth access token required. Public Access Tokens are not accepted.

The endpoint is **async only**. It creates an `image.remove_background` task and returns `201` with a `taskId`. Poll task endpoints or use webhooks to get the result.

## Request body

```json theme={"theme":"kanagawa-dragon"}
{
  "url": "https://example.com/product.jpg",
  "output": {
    "format": "webp"
  },
  "destination": "bunny-prod",
  "webhook": {
    "custom": [{ "url": "https://example.com/webhooks/mynth" }]
  },
  "metadata": {
    "productId": "sku_1"
  },
  "access": {
    "pat": { "enabled": true }
  }
}
```

## Fields

| Field         | Type     | Default    | Notes                                                                                             |
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------------------- |
| `url`         | `string` | *required* | Image URL to remove the background from. Must be http(s).                                         |
| `output`      | `object` | —          | `format`: `png` or `webp`. When omitted, the result keeps the provider's format.                  |
| `destination` | `string` | —          | Slug of a configured destination. See [Use Destinations](/guides/use-destinations).               |
| `webhook`     | `object` | —          | Same shape as on [image generation](/reference/image-generation-request).                         |
| `metadata`    | `object` | —          | Arbitrary JSON, up to 2 KB. Returned on the task and in webhook payloads.                         |
| `access`      | `object` | —          | `pat.enabled` (boolean, default `true`). Controls whether a task-scoped access token is returned. |

## Response body

### `201` — task created

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

| Field                           | Type     | Notes                                                                |
| ------------------------------- | -------- | -------------------------------------------------------------------- |
| `data.taskId`                   | `string` | Task ID. Poll `/tasks/:id` or use webhooks for the result.           |
| `data.estimatedCost`            | `string` | Estimated cost in USD reserved for this task. Failed tasks are free. |
| `data.access.publicAccessToken` | `string` | Returned when `access.pat.enabled` is true.                          |

When the task completes, `GET /tasks/:id` (or the webhook payload) includes:

```json theme={"theme":"kanagawa-dragon"}
{
  "result": {
    "image": {
      "id": "img_01KE7XWWEQ4MCGWKBQKJ1G47RP",
      "url": "https://cdn.mynth.io/images/img_01KE7XWWEQ4MCGWKBQKJ1G47RP.png",
      "mynth_url": "https://cdn.mynth.io/images/img_01KE7XWWEQ4MCGWKBQKJ1G47RP.png",
      "size": "1024x768",
      "format": "png"
    }
  }
}
```

| Field             | Type             | Notes                                                                                     |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------- |
| `image.id`        | `string`         | Image ID.                                                                                 |
| `image.url`       | `string \| null` | Destination URL, or the Mynth CDN URL without a destination. `null` when delivery failed. |
| `image.mynth_url` | `string`         | Mynth CDN URL.                                                                            |
| `image.size`      | `string`         | `{width}x{height}` of the result.                                                         |
| `image.format`    | `string`         | `png` or `webp`.                                                                          |

If background removal fails, the task status is `failed` with `errors: [{ code, message? }]`. Common codes: `INVALID_INPUT`, `PROVIDER_ERROR`, `PROVIDERS_BUSY`, `TIMEOUT`, `UNKNOWN_ERROR`. See [Task error codes](/reference/errors-and-limits#task-error-codes).

## Limits

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

## Pricing

Each request is priced at **\$0.02**. That amount is reserved from your account balance before processing begins. You are charged only when the task completes successfully — failed tasks release the reserve. If your balance is insufficient, the request returns `422 INSUFFICIENT_BALANCE`.

## Error responses

| Status | Body                                | Cause                                                        |
| ------ | ----------------------------------- | ------------------------------------------------------------ |
| `400`  | `{ success: false, errors: [...] }` | Request body fails schema validation.                        |
| `400`  | `{ code: "VALIDATION_ERROR", ... }` | Metadata is larger than 2 KB, or the destination is unknown. |
| `401`  | `{ code: "UNAUTHORIZED", ... }`     | Missing or invalid API key or OAuth access token.            |
| `422`  | `{ code: "INSUFFICIENT_BALANCE" }`  | Account balance is too low to reserve the cost.              |

See [Errors and Limits](/reference/errors-and-limits) for the full error reference.