---
title: "Create Music"
method: POST
path: "/v3/audio/music"
tags: ["Audio"]
---

# Create Music

`POST /v3/audio/music`

## Request

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

Generate a music track with `lyria-3-pro`. The request waits for the track and answers 200 with a time-limited `audio_url` to the mp3. `duration_seconds` is a target: a longer render is cut to it with a fade-out, and a shorter one is kept, so read the returned `duration_seconds` for the real length. Send an `Idempotency-Key` header with every request: it is required. Repeating a request with the same key and body returns the original track instead of generating again, and a duplicate sent while the original is still running gets 409 `request_in_progress`. Each track is priced at the vendor's flat per-song cost. 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 track is made, and a failed generation is not charged. If the balance no longer covers the charge when the track is ready, the request answers 402 `insufficient_credit` without it.

## Headers

- `Idempotency-Key` string, required

## Request body

- MusicCreateRequest
  - `model` 'lyria-3-pro', required: Music model. Each model accepts its own options.
  - `prompt` string, required: What the track should sound like: genre, mood, instruments, use.
  - `duration_seconds` integer, required: Target length: 30, 60, 120 or 180. A longer render is cut to this length with a fade-out; a shorter one is kept as is.
  - `bpm` integer, nullable: Target tempo in beats per minute.
  - `intensity` integer, nullable: Energy from 1 (ambient) to 5 (peak).
  - `instrumental` boolean: No vocals. Cannot be combined with `lyrics`.
  - `lyrics` string, nullable: Lyrics to sing verbatim. Untagged text is split into verses on blank lines. Written by the model when omitted.

## Response `200`

The finished track with its download URL.

- object
  - `data` MusicResponse
    - `id` string, required: The music job id; read it again with GET /v3/audio/music/{id}.
    - `status` 'pending' | 'completed' | 'failed', required
    - `model` 'lyria-3-pro', required: The music model that generated the track.
    - `created_at` integer, nullable: Unix seconds.
    - `requested_duration_seconds` integer, required: The target length the request asked for.
    - `duration_seconds` number, nullable: The measured length of the file; present once completed.
    - `audio_url` string, nullable: Time-limited download URL of the mp3; present once completed. Read the job again for a fresh URL.
    - `format` 'mp3', nullable: Audio format; present once completed.
    - `failure_code` 'invalid_input' | 'content_policy_violation' | '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/music/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)