HEheygen
Audio

Create Music

Changed on

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.

post/v3/audio/music

Request

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

Headers

Idempotency-Keystring required

Required client-supplied key for safely retrying a request that charges. A retry within 24 hours that shares this key returns the original response instead of running again. The body must be the same: a different body under the same key returns 409 conflict. A retry that arrives while the original is still in flight gets a 409 request_in_progress. When the original could not be confirmed, repeating it with the same key settles that attempt instead of starting another. Scope is the space plus the request path, so the same key on another video is independent, and a key sent by another member of the space replays that member's response. A missing or blank value is rejected with 400. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default.

Request body

model'lyria-3-pro' required

Music model. Each model accepts its own options.

promptstring required

What the track should sound like: genre, mood, instruments, use.

duration_secondsinteger 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.

bpminteger nullable

Target tempo in beats per minute.

intensityinteger nullable

Energy from 1 (ambient) to 5 (peak).

instrumentalboolean

No vocals. Cannot be combined with lyrics.

lyricsstring nullable

Lyrics to sing verbatim. Untagged text is split into verses on blank lines. Written by the model when omitted.

Response

The finished track with its download URL.

Changes