HEheygen
Background Removal

Create Background Removal

Changed on

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.

post/v3/background-removals

Request

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

Request body

layersstring[]

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.

titlestring nullable

Optional human-readable title for the job.

request_idstring 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

Successful response

Changes