Elevenlabs Music V2.5 API Documentation

Elevenlabs Music V2.5 API Documentation

Playground

ElevenLabs Music v2.5 Text-to-Music generates songs with vocals or instrumental music from text prompts, with configurable duration and MP3 output for songwriting demos, background music, social content, ads, and creative audio production workflows. Ready-to-use REST inference API, best performance, no coldstarts, affordable pricing.

Features

ElevenLabs Music v2.5 generates songs with vocals or instrumental tracks from a text description. Describe the genre, mood, instrumentation, vocal style, and optional original lyrics, then set the requested duration and output format to generate a complete music track.

Music v2.5 improves audio quality and prompt adherence over Music v2.

Why Choose This?

• Prompt-to-music generation
  Generate music directly from a text description.

• Vocal or instrumental output
  Create songs with vocals based on the prompt, or enable force_instrumental for instrumental-only music.

• Improved prompt adherence
  Follow music direction more closely for genre, mood, arrangement, instrumentation, and vocal style.

• Duration control
  Set the requested music length from 3 seconds to 10 minutes.

• Multilingual vocal support
  Generate songs with vocals in different languages when specified in the prompt.

• MP3 output format control
  Choose the MP3 codec, sample rate, and bitrate through output_format.

Parameters

How to Use

1. Write your prompt — Describe the genre, mood, instruments, tempo, vocal style, language, and optional original lyrics.
2. Set duration — Choose music_length_ms from 3000 to 600000.
3. Choose instrumental mode optional — Enable force_instrumental when you want music without vocals.
4. Choose output format optional — Use the default mp3_48000_192 or select another supported MP3 output format.
5. Submit — Generate the music track and retrieve the output.

Output

One generated MP3 audio URL is returned in data.outputs[0].

Submit the job and poll the WaveSpeed prediction result endpoint until the task completes.

Pricing

Pricing is based on the requested music_length_ms.

Billing is calculated per started minute. Requested duration is rounded up to the next whole minute, with a minimum billed duration of 1 minute.

Example Costs

Best Use Cases

• Song generation — Create complete songs from a descriptive prompt and optional original lyrics.
• Instrumental music — Generate backing tracks, music beds, loops, or soundtrack-style audio.
• Multilingual vocal tracks — Create vocal music in different languages by specifying the language in the prompt.
• Content creation — Generate music for videos, podcasts, ads, games, and social media.
• Creative prototyping — Test different genres, moods, arrangements, and vocal directions quickly.
• Custom soundtrack workflows — Create tracks tailored to a specific scene, product, brand, or story.

Pro Tips

• Include genre, mood, instruments, tempo, vocal style, and production cues in the prompt.
• Add original lyrics directly in the prompt when you want more control over the song content.
• Use force_instrumental=true when you need background music without vocals.
• Set the duration close to what you actually need, since billing uses the requested duration.
• Use concise, specific music direction instead of mixing too many unrelated genres.
• Keep vocals, language, and lyrical direction clear when generating songs with singing.
• Use instrumental prompts when you need clean background music for video or media workflows.

Notes

• prompt and music_length_ms are required.
• music_length_ms supports 3000–600000 milliseconds.
• The minimum billed duration is 1 started minute.
• Billing is based on requested duration, not measured output length.
• Automatic duration, composition plans, reference audio, and seed are not exposed in this version.
• Do not submit unsupported fields.

Related Models

• ElevenLabs Music — Generate music from text prompts with the earlier ElevenLabs Music workflow.
• ElevenLabs Music v2 — Generate vocal or instrumental music with prompt-based duration control.
• ElevenLabs Music v2.5 — Generate upgraded vocal or instrumental music from prompt-based instructions.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "prompt": "A cinematic ocean wave at sunrise, highly detailed",
  "music_length_ms": 30000,
  "force_instrumental": false,
  "output_format": "mp3_48000_192"
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/elevenlabs/music-v2.5" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters