---
title: "Create Background Removal"
method: POST
path: "/v3/background-removals"
tags: ["Background Removal"]
---

# Create Background Removal

`POST /v3/background-removals`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/background-removals`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Submits a video for background removal and returns a job; poll Get Background Removal with its id. A completed job has download URLs for the requested layers: `foreground`, `mask` and `background`. For idempotency, send `request_id` in the body. Available on all plans with sufficient credits. API requests cost \$0.15 per input-video minute (9 API quota units, 18 on the enterprise base card, or 3 plan/generative credits per minute), rounded up to whole wallet units. Failed jobs are refunded. An insufficient-credit response allows retrying the same `request_id` after topping up; a concurrent replay may return a pending job that is removed if payment is refused. After a job is claimed, other submission failures retain a failed job; use a new `request_id` to try again. The `request_id` inside an error body identifies the HTTP request for support; it is not this idempotency key. Web/editor background removal remains free.

## Request body

- CreateBackgroundRemovalRequest
  - `video` union, required: Input video to remove the background from (url, asset_id, or base64).
    - AssetUrl: Asset input via publicly accessible HTTPS URL.
      - `type` 'url', required: Input type discriminator
      - `url` string, required: Publicly accessible HTTPS URL for the asset
    - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
      - `type` 'asset_id', required: Input type discriminator
      - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
    - AssetBase64: Asset input via base64-encoded content.
      - `type` 'base64', required: Input type discriminator
      - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
      - `data` string, required: Base64-encoded file content
  - `layers` string[]: Output layers to return. Any of: 'foreground' (subject on a transparent background), 'mask' (grayscale alpha matte), 'background' (the scene with the subject removed). Defaults to all three.
  - `title` string, nullable: Optional human-readable title for the job.
  - `request_id` string, nullable: Client-provided idempotency key — *the* idempotency mechanism for this endpoint. Re-sending the same `request_id` returns the *original* job (same `id`, same `status`, same charge) instead of creating a new one — the dedup is over (`space_id`, `request_id`), not over the response body, so a duplicate `request_id` with different content still collides on the original job. The HTTP `Idempotency-Key` header is *not* honored here; pick a per-content `request_id` if you need per-content dedup.

## Response `200`

Successful response

- object
  - `data` BackgroundRemovalJob
    - `id` string, required: Background removal job id. Use it to poll GET /v3/background-removals/{id}.
    - `status` string, required: Job status: 'pending' | 'processing' | 'completed' | 'failed' | 'deleted'.
    - `layers` object: Map of produced layer name to a presigned download URL. Populated once status is 'completed'.
    - `duration` number, nullable: Processed video duration in seconds.
    - `created_at` integer, nullable: Unix timestamp (seconds) when the job was created.
    - `completed_at` integer, nullable: Unix timestamp (seconds) when the job completed. Present once completed.
    - `error` string, nullable: Failure reason. Present only when status is 'failed'.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `429`: Rate limit exceeded

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/background-removals/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)