Eleven Music v2.5 API

POST Base URL: https://api.hiapi.ai /v1/tasks

Copy Page

Image, video, and audio models are called through theUnified Async API POST /v1/tasks endpoint; only the input fields differ (see input parameters below).

Model summary

Model name	elevenlabs/music-v2.5
Type	Audio generation (text-to-music)
Endpoint	POST /v1/tasks
Pricing	See HiAPI Pricing

ElevenLabs Eleven Music v2.5 text-to-music: generate 3 seconds to 10 minutes of songs or instrumentals from a music description, or write a chunk-by-chunk composition plan that controls lyrics, duration, styles, and reference audio per section.

Production guidance

Production guidance

• For production, pass callback.url at the top level of the request body so HiAPI can notify your service when the task reaches a terminal state.
• GET /v1/tasks/:id is better for local debugging, low-volume jobs, or fallback reconciliation if a callback is missed.
• Use callback.when=final. Both success and fail are terminal states, so your service should deduplicate by taskId.

Best suited for

Fast drafts

A single music description yields a complete song or instrumental, for ad beds, short-video background music, and quick idea checks.

promptmusic_length_msforce_instrumental

Exact structure

Plan intro, verse, and chorus chunk by chunk with their own lyrics, duration, and styles when the arrangement must follow a script.

composition_planseed

Reference style

Attach reference audio to a chunk so the whole song or one section follows a sound you already have.

composition_plan.chunks[].audio_reference

Request parameters

</> Generate example code

model string required

Fixed value elevenlabs/music-v2.5.

example elevenlabs/music-v2.5

input object required

Business parameters. Put Eleven Music v2.5-specific configuration here.

prompt string optional

Music description of up to 4,100 characters covering genre, mood, instruments, vocals, structure, or lyrics. Exactly one of prompt or composition_plan must be supplied.

music_length_ms integer optional

Length of the generated audio in milliseconds, an integer from 3,000 to 600,000. Only applies with prompt.

default 60000

force_instrumental boolean optional

Set to true to guarantee a result without vocals. Only applies with prompt.

default false

composition_plan object optional

Chunk-by-chunk composition plan: split the track into 1–30 chunks, each with its own text, duration, and styles, for work that needs an exact structure. Exactly one of prompt or composition_plan must be supplied.

chunks object[] required

Chunks in playback order, 1 to 30 items, totalling 3,000 to 600,000 ms.

text string required

Text for this chunk. Start with an optional section name in square brackets such as [Verse 1], then one lyric line per row; put performance directions in curly braces such as {whisper}. Up to 30 lines of 200 characters. An instrumental chunk can contain only the section name.

duration_ms integer required

Duration of this chunk in milliseconds, an integer from 3,000 to 120,000. The durations of all chunks must add up to between 3,000 and 600,000 ms.

positive_styles string[] required

Styles and musical directions this chunk should contain; English works best. The first chunk sets the overall tone and genre; later chunks can add nuance, progression, or a change of direction.

negative_styles string[] optional

Styles and directions to keep out of this chunk. Leaving it empty is a good default; set it only to exclude a specific style, for example vocals.

context_adherence enum optional

How closely this chunk follows its surrounding chunks: low allows more deviation and creativity, high keeps it consistent with the context.

enum: lowmediumhigh

audio_reference object optional

Reference audio whose style guides this chunk.

audio_url string required

Publicly reachable audio file whose style conditions this chunk. A reference on the first chunk shapes the whole song.

strength enum optional

How closely to follow the reference: low leaves room to deviate, xhigh stays closest to the reference.

enum: lowmediumhighxhigh

start_ms integer optional

Offset into the clip where the referenced window starts, in milliseconds; at least 0.

default 0

end_ms integer optional

End of the referenced window in milliseconds; must be greater than start_ms. Omit to use 30,000 ms after start_ms or the end of the clip. The window is at most 30,000 ms.

seed integer optional

Random seed, an integer from 0 to 2147483647. The same seed with the same parameters gives more consistent results, but exact reproduction is not guaranteed. Only applies with composition_plan.

output_format enum optional

Codec, sample rate, and bitrate of the output audio, written as codec_samplerate_bitrate. MP3 returns an MP3 file, Opus returns an Ogg file, and PCM returns 16-bit WAV audio (the download link may not end in .wav).

default mp3_48000_192 enum: mp3_22050_32mp3_24000_48mp3_44100_32mp3_44100_64mp3_44100_96mp3_44100_128mp3_44100_192mp3_48000_128mp3_48000_192mp3_48000_240mp3_48000_320pcm_8000pcm_16000pcm_22050pcm_24000pcm_32000pcm_44100pcm_48000ulaw_8000alaw_8000opus_48000_32opus_48000_64opus_48000_96opus_48000_128opus_48000_192

callback object optional

Optional callback configuration. When set, HiAPI notifies your service when the task reaches a terminal state.

url string required

Required when callback is set; HTTPS URL that receives terminal task notifications.

example https://your-domain.com/hiapi/callback

when enum optional

Callback trigger timing. Use final.

default final enum: final

Chunk text format

Common ways to write composition_plan.chunks[].text; the section name is optional and a chunk does not need every element.

Syntax	Meaning	Example
[Section]	Section name in square brackets at the start of the text, 1–100 characters.	[Intro], [Verse 1], [Chorus], [Bridge], [Outro]
Lyric line	One lyric line per row after the section name, up to 30 lines of 200 characters.	Neon rain on empty streets
{direction}	Performance direction in curly braces.	{whisper}, {scratching}
Section name only	For an instrumental chunk, write only the section name and add vocals to negative_styles.	[Intro]

Example requests

Late-night lo-fi instrumental

Generate 30 seconds of vocal-free lo-fi hip hop from a music description.

Request body⧉

{
  "model": "elevenlabs/music-v2.5",
  "input": {
    "prompt": "Warm lo-fi hip hop instrumental with dusty drums, soft Rhodes piano chords, vinyl crackle, and a mellow late-night mood.",
    "music_length_ms": 30000,
    "force_instrumental": true
  }
}

Two-chunk synthwave

Use a composition plan for a 10-second instrumental intro followed by a 20-second verse with lyrics, with a fixed seed.

Request body⧉

{
  "model": "elevenlabs/music-v2.5",
  "input": {
    "composition_plan": {
      "chunks": [
        {
          "text": "[Intro]",
          "duration_ms": 10000,
          "positive_styles": [
            "synthwave",
            "analog drum machine",
            "great production quality"
          ],
          "negative_styles": [
            "vocals"
          ]
        },
        {
          "text": "[Verse 1]\nNeon rain on empty streets\nI keep walking to the beat",
          "duration_ms": 20000,
          "positive_styles": [
            "synthwave",
            "driving bass",
            "confident vocals"
          ],
          "context_adherence": "high"
        }
      ]
    },
    "seed": 42
  }
}

Getting the result

1. The response returns a taskId immediately without waiting for generation to finish.
2. In production, prefer waiting for callback.url to receive the terminal notification. For local debugging, poll GET /v1/tasks/:id.
3. When status=success, find the type=audio item in output and download the generated audio from its url.
4. When status=fail, fix the request based on the returned error instead of retrying the same invalid payload.

FAQ

What is the difference between a music description and a composition plan?

A music description hands the model one text brief and is the fastest way to get a track. A composition plan splits the song into 1–30 chunks, each with its own lyric text, duration, and styles to include or avoid, for work that needs an exact structure. Use one or the other, never both in one request.

Can it generate instrumentals?

Yes. With a music description, set force_instrumental to true to guarantee no vocals. With a composition plan, add vocals to a chunk's negative_styles and describe the instrumentation in positive_styles.

How do I control the length?

With a music description, set music_length_ms between 3,000 and 600,000 milliseconds; when omitted, the track is generated at 60,000 milliseconds (one minute). With a composition plan, the total length is the sum of every chunk's duration_ms and must also fall between 3,000 and 600,000 milliseconds.

How do I guide the style with reference audio?

Add audio_reference to a chunk in the composition plan with a publicly reachable audio URL. Use start_ms and end_ms to select a window of at most 30 seconds and strength to control how closely the model follows it. The reference on the first chunk shapes the whole song.

Which output formats are supported?

The default is mp3_48000_192. MP3 formats return an MP3 file, Opus formats return an Ogg file, and PCM formats return 16-bit WAV audio whose download link may not end in .wav, so save it as WAV. μ-law and A-law are 8 kHz telephony encodings. Format names follow codec_samplerate_bitrate; the full list is under the output_format parameter.

How is it billed?

Per minute of generated audio, rounded up to the next whole minute; the audio length comes from music_length_ms or the sum of the chunk duration_ms values. See the pricing page for the live rate. View pricing

Next steps

• Get an API key
• View Eleven Music v2.5 pricing
• Compare AI audio APIs
• Playground