---
title: "Remove image background (async)"
method: POST
path: "/v1/images/remove-background"
tags: ["Images"]
---

# Remove image background (async)

`POST /v1/images/remove-background`

## Request

- Base URL: `https://contentmaschine.ai/api`
- URL: `https://contentmaschine.ai/api/v1/images/remove-background`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://contentmaschine.ai/api/oauth/authorize`, token URL `https://contentmaschine.ai/api/oauth/token`)

Queue a background removal for an image: a library `file_uuid` or the image inline
as base64 in `image_data`; exactly one of the two. JPEG, PNG or WebP.
Uses AI triangulation matting (two Gemini passes + per-pixel alpha computation).
Returns immediately with a `job_id` - poll `GET /v1/jobs/{id}` until `status` is
`completed`; the result carries `file_uuid` and `download_url` of the PNG.
This route answered synchronously before 2026-10-09 - see `x-breaking-changes`.

Cost: 0.20 credits per call, reserved when the job is queued.

## Request body

- object
  - `file_uuid` string, uuid: UUID of an image file in your library (JPEG, PNG, or WebP). Use this or `image_data`.
  - `image_data` string: The image inline, as base64 or a data URL (JPEG, PNG, or WebP). Use this or `file_uuid`.
  - `subject_hint` string: Optional hint to identify the subject, e.g. "the person" or "the car".

## Response `202`

Job queued

- JobQueued
  - `success` boolean
  - `data` object
    - `job_id` integer
    - `generation_id` integer
    - `generation_uuid` string, uuid
    - `status` string
    - `estimated_credits` number, float
  - `timestamp` string, date-time

## Other responses

- `400`: No image or both forms of it, an unsupported image type, or a subject_hint over the limit
- `401`: Missing or invalid API key
- `402`: Insufficient credits
- `403`: Unauthorized access to file
- `404`: File not found
- `default`: Any other error. Every failure this API emits uses the same envelope; branch on `error.type`, never on `error.message`, and quote `error.correlation_id` to support.

---

[API](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api.md) · [All operations](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/contentmaschine/apis/contentmaschine-ai-api/revisions/28c74f46051c?raw)