Image Remove Background Request - Mynth - Documentation

Endpoint:

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

{
  "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.
`webhook`	`object`	—	Same shape as on image generation.
`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

{
  "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:

{
  "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.

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 for the full error reference.

​Request body

​Fields

​Response body

​201 — task created

​Limits

​Pricing

​Error responses