---
title: "Separate Audio Stems"
method: POST
path: "/v3/audio/stems"
tags: ["Audio"]
---

# Separate Audio Stems

`POST /v3/audio/stems`

## Request

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

Separate a recording of at most 3600 seconds into six stems with ElevenLabs `six_stems_v1`: `vocals`, `drums`, `bass`, `guitar`, `piano` and `other`. Upload the audio through the asset upload API (at most 200 MB) and pass its asset_id. The request waits for the stems and answers 200 with a time-limited mp3 `url` for each, every stem the full length of the audio. Each request is priced per second of the audio. A request the workspace's API credits cannot cover is refused with 402 `insufficient_credit` before the model runs. The credits are charged once the stems are made, and a failed separation is not charged. If the balance no longer covers the charge when the stems are ready, the request answers 402 `insufficient_credit` without them. Send an `Idempotency-Key` header with every request: it is required. Repeating a request with the same key and body returns the original stems with fresh URLs without charging again, a duplicate sent while the original is still running gets 409 `request_in_progress`, and the same key with a different body gets 409 `conflict`. Failed requests replay their stored error; use a new key for a new attempt.

## Headers

- `Idempotency-Key` string, required

## Request body

- StemsCreateRequest: POST /v3/audio/stems request body.
  - `version` 1, required: Contract version. Only 1 exists.
  - `audio` AssetId, required: 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

## Response `200`

The stems with their download URLs.

- object
  - `data` StemsResponse
    - `id` string, required: The stems job id; read it again with GET /v3/audio/stems/{id}.
    - `status` 'pending' | 'completed' | 'failed', required
    - `created_at` integer, nullable: Unix seconds.
    - `duration_seconds` number, required: The length of the audio separated, which is what the job is charged for.
    - `stems` StemFile[], nullable: One file per stem, each the full length of the audio; present once completed.
      - `name` string, required: `vocals`, `drums`, `bass`, `guitar`, `piano` or `other`.
      - `url` string, required: Time-limited download URL of the stem's mp3. Read the job again for a fresh URL.
    - `failure_code` 'invalid_input' | 'vendor_unavailable' | 'vendor_timeout' | 'ai_vendor_access_restricted' | 'insufficient_credit' | 'api_key_required' | 'internal_error'
    - `failure_message` string, nullable: A customer-safe explanation; present once failed.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `402`: Insufficient credit
- `403`: Forbidden
- `409`: Conflict — `error.code` is one of: `request_in_progress`, `conflict`.
- `429`: Rate limit exceeded
- `502`: Upstream dependency failed — the request did not complete and is safe to retry.
- `504`: Upstream dependency timed out — the request did not complete and is safe to retry.

## Changes

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

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/audio/stems/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)