ElevenLabs Music Text to Audio API

elevenlabs/music

ElevenLabs Music Text to Audio turns text descriptions into songs or instrumentals, with custom lyrics and section-based composition. Set global and local styles to guide the sound, then shape the arrangement with individual section durations.

Input

Text0 / 4100

Describe the genre, mood, instruments, and vocals in up to 4,100 characters. Entering text selects prompt-based creation.

Composition Plan

Add sections to arrange your track and set its global styles. Editing the plan selects section-based creation.

Positive Global Styles

Add one direction per item, such as acoustic guitar, soft drums, or warm vocals. The list may be empty.

Negative Global Styles

Add one style to avoid per item, such as heavy distortion or dense drums. The list may be empty.

Sections

Section Name

Name this section in 1–100 characters, for example Intro, Verse, or Chorus.

Positive Local Styles

Add one direction per item, such as acoustic guitar, soft drums, or warm vocals. The list may be empty.

Negative Local Styles

Add one style to avoid per item, such as heavy distortion or dense drums. The list may be empty.

Duration

Set this section to 3–120 seconds. Decimal values are accepted.

Lines

Enter one lyric line per item, up to 200 characters each. For an instrumental section, leave the list empty and specify instrumental in its styles.

Section Name

Name this section in 1–100 characters, for example Intro, Verse, or Chorus.

Positive Local Styles

Add one direction per item, such as acoustic guitar, soft drums, or warm vocals. The list may be empty.

Negative Local Styles

Add one style to avoid per item, such as heavy distortion or dense drums. The list may be empty.

Duration

Set this section to 3–120 seconds. Decimal values are accepted.

Lines

Enter one lyric line per item, up to 200 characters each. For an instrumental section, leave the list empty and specify instrumental in its styles.

Section Name

Name this section in 1–100 characters, for example Intro, Verse, or Chorus.

Positive Local Styles

Add one direction per item, such as acoustic guitar, soft drums, or warm vocals. The list may be empty.

Negative Local Styles

Add one style to avoid per item, such as heavy distortion or dense drums. The list may be empty.

Duration

Set this section to 3–120 seconds. Decimal values are accepted.

Lines

Enter one lyric line per item, up to 200 characters each. For an instrumental section, leave the list empty and specify instrumental in its styles.

Section Name

Name this section in 1–100 characters, for example Intro, Verse, or Chorus.

Positive Local Styles

Add one direction per item, such as acoustic guitar, soft drums, or warm vocals. The list may be empty.

Negative Local Styles

Add one style to avoid per item, such as heavy distortion or dense drums. The list may be empty.

Duration

Set this section to 3–120 seconds. Decimal values are accepted.

Lines

Enter one lyric line per item, up to 200 characters each. For an instrumental section, leave the list empty and specify instrumental in its styles.

Respect Sections Durations

Turn on to follow each section’s requested duration. Turn off to allow more flexible section timing.

Output Format

Choose the audio codec, sample rate, and bitrate. The default is mp3_44100_128.

Output

Create a voice track next

ElevenLabs V3 Text to Speech ElevenLabs Turbo v2.5 Text to Speech

Examples

The Clockmaker's Clues

Create a 30-second instrumental jazz cue for a puzzle scene in a clockmaker's workshop. 104 BPM, lightly swinging 4/4, playful curiosity with a hint of mystery. Use plucked upright bass, brushed drums, muted trumpet and vibraphone, each clearly separated in a warm intimate acoustic mix. Begin with a distinctive four-note vibraphone motif over bass; let muted trumpet answer and develop that motif in the middle, while brush accents subtly increase the momentum. Resolve with a short, clean ensemble cadence and allow the last note to decay naturally. No vocals, choir, spoken words, ticking sound effects or abrupt cutoff.

Light Through the Kelp Forest

Compose a 40-second instrumental score for a nature documentary gliding through a sunlit underwater kelp forest. 72 BPM, gently flowing 4/4. Felt piano, delicate harp harmonics, soft sustained strings and a subtle low ambient texture; luminous, patient, full of quiet wonder. Start sparsely with isolated felt-piano notes and wide space. Gradually introduce harp and strings into an expansive rising harmony through the middle third, suggesting shafts of light moving through long fronds. Gently thin the arrangement and finish on a peaceful resolved chord with natural reverb decay. Detailed soft dynamics, wide stereo depth, no heavy percussion, no vocals or choir, no narration, no water sound effects, no abrupt cutoff.

Music generation interface

Start a music generation request

Submit a music description or composition plan, receive a task identifier, then check its status and retrieve the audio. This example uses a verified section-based song request.

Configure authentication

Use your Vidgo API key as a Bearer credential and submit the request as JSON.

Submission endpoint: POSThttps://api.vidgo.ai/api/generate/submit
Authentication: Authorization: Bearer <VIDGO_API_KEY>

Submit the composition plan

The example arranges an intro, verse, chorus, and outro. Replace its styles and lyrics to create your own request.

Request example

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "elevenlabs/music",
  "input": {
    "composition_plan": {
      "positive_global_styles": [
        "indie folk with subtle organic electronica",
        "96 BPM, 4/4",
        "warm clear female lead vocal",
        "acoustic guitar, rounded bass, delicate electronic percussion",
        "hopeful intimate song about planting a rooftop garden",
        "clean spacious studio mix, clear Mandarin and English diction"
      ],
      "negative_global_styles": [
        "harsh distortion",
        "crowded arrangement",
        "spoken narration",
        "abrupt cut off"
      ],
      "sections": [
        {
          "section_name": "Acoustic introduction",
          "duration": 8,
          "positive_local_styles": [
            "instrumental only",
            "fingerpicked acoustic guitar introduces a memorable gentle motif",
            "soft airy pad, no drums"
          ],
          "negative_local_styles": [],
          "lines": []
        },
        {
          "section_name": "Mandarin verse",
          "duration": 16,
          "positive_local_styles": [
            "sing the supplied Mandarin lyrics clearly",
            "intimate gentle lead vocal",
            "fingerpicked guitar and soft bass, restrained percussion"
          ],
          "negative_local_styles": [],
          "lines": [
            "把春天种在屋顶上",
            "等风翻过旧砖墙"
          ]
        },
        {
          "section_name": "English chorus",
          "duration": 16,
          "positive_local_styles": [
            "sing the supplied English lyrics clearly",
            "open uplifting melody",
            "full warm drums and bass enter",
            "layered backing vocal harmonies, retain the acoustic motif"
          ],
          "negative_local_styles": [],
          "lines": [
            "Little seeds above the street",
            "Find the sunlight, find the beat"
          ]
        },
        {
          "section_name": "Instrumental resolution",
          "duration": 8,
          "positive_local_styles": [
            "instrumental only, no vocals",
            "return to fingerpicked guitar motif",
            "drums fall away, warm sustained final chord with natural decay"
          ],
          "negative_local_styles": [],
          "lines": []
        }
      ]
    },
    "respect_sections_durations": true,
    "output_format": "mp3_44100_128"
  }
}
JSON
)

RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

CODE=$(printf '%s' "$RESPONSE" | jq -r '.code // empty')
if [ "$CODE" != "0" ] && [ "$CODE" != "200" ]; then
  printf 'API error: %s
' "$RESPONSE" >&2
  exit 1
fi
printf '%s
' "$RESPONSE"

Check the task status

Insert the returned task_id into the status URL to check that task’s progress.

Status endpoint

GET https://api.vidgo.ai/api/generate/status/{task_id}

Use the same Bearer credential to check the task. Read files when finished, or error_message when failed.

not_startedrunningfinishedfailed

Submission response example

{
  "code": 200,
  "data": {
    "task_id": "W6KDNIQQOUAE1K8V",
    "status": "not_started"
  }
}

Completed response example

{
  "code": 200,
  "data": {
    "task_id": "W6KDNIQQOUAE1K8V",
    "status": "finished",
    "created_time": "2026-09-27T10:48:12",
    "progress": 100,
    "error_message": null,
    "files": [
      {
        "file_type": "audio",
        "file_url": "https://cdn.vidgo.ai/apis/models/elevenlabs/music/text-to-audio/v1/01/output.mp3"
      }
    ]
  }
}

Retrieve the audio file

When status is finished, read URLs from files entries whose file_type is audio to play or download the music.

Retrieve the audio file

set -euo pipefail
: "${VIDGO_API_KEY:?Set VIDGO_API_KEY in your environment}"

REQUEST_BODY=$(cat <<'JSON'
{
  "model": "elevenlabs/music",
  "input": {
    "composition_plan": {
      "positive_global_styles": [
        "indie folk with subtle organic electronica",
        "96 BPM, 4/4",
        "warm clear female lead vocal",
        "acoustic guitar, rounded bass, delicate electronic percussion",
        "hopeful intimate song about planting a rooftop garden",
        "clean spacious studio mix, clear Mandarin and English diction"
      ],
      "negative_global_styles": [
        "harsh distortion",
        "crowded arrangement",
        "spoken narration",
        "abrupt cut off"
      ],
      "sections": [
        {
          "section_name": "Acoustic introduction",
          "duration": 8,
          "positive_local_styles": [
            "instrumental only",
            "fingerpicked acoustic guitar introduces a memorable gentle motif",
            "soft airy pad, no drums"
          ],
          "negative_local_styles": [],
          "lines": []
        },
        {
          "section_name": "Mandarin verse",
          "duration": 16,
          "positive_local_styles": [
            "sing the supplied Mandarin lyrics clearly",
            "intimate gentle lead vocal",
            "fingerpicked guitar and soft bass, restrained percussion"
          ],
          "negative_local_styles": [],
          "lines": [
            "把春天种在屋顶上",
            "等风翻过旧砖墙"
          ]
        },
        {
          "section_name": "English chorus",
          "duration": 16,
          "positive_local_styles": [
            "sing the supplied English lyrics clearly",
            "open uplifting melody",
            "full warm drums and bass enter",
            "layered backing vocal harmonies, retain the acoustic motif"
          ],
          "negative_local_styles": [],
          "lines": [
            "Little seeds above the street",
            "Find the sunlight, find the beat"
          ]
        },
        {
          "section_name": "Instrumental resolution",
          "duration": 8,
          "positive_local_styles": [
            "instrumental only, no vocals",
            "return to fingerpicked guitar motif",
            "drums fall away, warm sustained final chord with natural decay"
          ],
          "negative_local_styles": [],
          "lines": []
        }
      ]
    },
    "respect_sections_durations": true,
    "output_format": "mp3_44100_128"
  }
}
JSON
)

SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  --request POST \
  --url "https://api.vidgo.ai/api/generate/submit" \
  --header "Authorization: Bearer $VIDGO_API_KEY" \
  --header "Content-Type: application/json" \
  --data "$REQUEST_BODY")

TASK_ID=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.data.task_id // .task_id // empty')
BUSINESS_CODE=$(printf '%s' "$SUBMIT_RESPONSE" | jq -r '.code // empty')
if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
  printf 'Submit failed:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi
if [ -z "$TASK_ID" ]; then
  printf 'Submit response did not include task_id:
%s
' "$SUBMIT_RESPONSE" >&2
  exit 1
fi

START_TIME=$(date +%s)
POLL_DELAY=2
while true; do
  if [ $(( $(date +%s) - START_TIME )) -ge 600 ]; then
    printf 'Timed out after 600 seconds
' >&2
    exit 1
  fi
  STATUS_RESPONSE=$(curl --silent --show-error --fail-with-body \
    --url "https://api.vidgo.ai/api/generate/status/$TASK_ID" \
    --header "Authorization: Bearer $VIDGO_API_KEY")
  STATUS=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.data.status // .status // empty')
  BUSINESS_CODE=$(printf '%s' "$STATUS_RESPONSE" | jq -r '.code // empty')
  if [ "$BUSINESS_CODE" != "0" ] && [ "$BUSINESS_CODE" != "200" ]; then
    printf 'Status request failed:
%s
' "$STATUS_RESPONSE" >&2
    exit 1
  fi

  case "$STATUS" in
    finished)
      printf '%s' "$STATUS_RESPONSE" | jq -r '(.data.files // .files // [])[]?.file_url'
      break
      ;;
    failed)
      printf '%s' "$STATUS_RESPONSE" | jq -r '.data.error_message // .error_message // "Generation failed"' >&2
      exit 1
      ;;
    not_started|running)
      sleep "$POLL_DELAY"
      if [ "$POLL_DELAY" -lt 10 ]; then POLL_DELAY=$((POLL_DELAY + 1)); fi
      ;;
    *)
      printf 'Unexpected task status: %s
' "$STATUS" >&2
      exit 1
      ;;
  esac
done

Request parameters

The request contains model and input. Set model to elevenlabs/music, then choose text or composition_plan inside input. An optional top-level callback_url accepts an HTTP or HTTPS URL.

Field	Type	Requirement	Default	Description
input.text	string	Required for text	—	Music description, 1–4,100 characters. Choose this or composition_plan.
input.composition_plan	object	Required for a plan	—	Arrange the track by section, with global styles and sections. Choose this or text.
input.duration	number	Optional with text	—	Target length for text input: 3–600 seconds, including decimals. Omit for model-selected length.
input.is_instrumental	boolean	Optional with text	false	Set true for instrumental music. Applies to text input.
input.respect_sections_durations	boolean	Optional with a plan	true	Controls adherence to requested section durations. Applies to composition_plan.
input.output_format	string	Optional	mp3_44100_128	Select the audio codec, sample rate, and bitrate from the listed values. mp3_22050_32, mp3_44100_32, mp3_44100_64, mp3_44100_96, mp3_44100_128, mp3_44100_192, pcm_8000, pcm_16000, pcm_22050, pcm_24000, pcm_44100, pcm_48000, ulaw_8000, alaw_8000, opus_48000_32, opus_48000_64, opus_48000_96, opus_48000_128, opus_48000_192
input.composition_plan.positive_global_styles	string[]	Required for a plan	—	Style directions for the whole track, such as genre, instruments, and rhythm. An empty array is valid.
input.composition_plan.negative_global_styles	string[]	Required for a plan	—	Style elements to avoid throughout the track. An empty array is valid.
input.composition_plan.sections	object[]	Required for a plan	—	At least one section, arranged in array order.
input.composition_plan.sections[].section_name	string	Required per section	—	Section name, 1–100 characters, identifying structures such as an intro, verse, or chorus.
input.composition_plan.sections[].positive_local_styles	string[]	Required per section	—	Instrument, vocal, and mood directions for this section. An empty array is valid.
input.composition_plan.sections[].negative_local_styles	string[]	Required per section	—	Style elements to avoid in this section. An empty array is valid.
input.composition_plan.sections[].duration	number	Required per section	—	Target duration for this section: 3–120 seconds, including decimals.
input.composition_plan.sections[].lines	string[]	Required per section	—	One lyric line per item, up to 200 characters each. For instrumental sections, use an empty array and instrumental style directions.

Response fields

A successful response uses code 0 or 200 with the task object in data. On completion, read the audio files from data.files.

Field	Type	Description
task_id	string	Task identifier for subsequent status checks.
status	string	Current task status; see Task states for its values.
files	object[]	List of files returned on completion.
files[].file_url	string	Audio file URL for playback or download.
files[].file_type	string	Music results use the file type audio.
progress	number	Task progress when included in the response.
error_message	string \| null	Error details when a task fails.

Task states

Save the task_id returned on submission and use it to check generation progress.

not_started
The task is queued and waiting to begin.
running
Music generation is in progress. Keep checking the same task.
finished
Generation is complete. Read the audio file URLs from files.
failed
The task failed. Read error_message and review the input.

Status checks and error handling

Validate the creation pathUse the fields for your text or plan path, checking numeric durations, boolean switches, and string arrays.
Keep checking the existing taskKeep checking while the task is not_started or running. If playground checks pause, use Resume status checks.
Handle the returned errorFor request errors, inspect the HTTP status and response message. For a failed task, read error_message and review the input before retrying.

Interface specifications

Item	Value	Description
Model identifier	elevenlabs/music	Set model to this value in the submission request.
Input paths	text / composition_plan	Choose one creation path per request.
Text duration	3–600 s	Optional; omit for model-selected length.
Section duration	3–120 s	Set a duration for each section in a plan.
Output type	audio	Read the file URLs from files after completion.

View the ElevenLabs Music Text to Audio API docs

ElevenLabs Music Text to Audio

ElevenLabs Music Text to Audio is an ElevenLabs model for creating songs and instrumentals from text descriptions or composition plans. Global styles establish a track’s musical direction, while local styles, lyrics, and durations shape individual sections. Use this control to develop background music for video edits, sketch podcast themes, or turn original lyrics into a song you can audition.

Why choose ElevenLabs Music

Set a musical direction in one promptDescribe genre, mood, instruments, and rhythm to create a track shaped around your scene or story.
Create songs or instrumentalsDescribe a vocal style or enable Is Instrumental for a music bed. Composition plans also let you supply lyrics section by section.
Plan the intro, verse, and chorusGive each section its own styles, lyrics, and duration to turn a track idea into a detailed arrangement.
Balance a shared style with section changesSet the overall character with global styles, then use local directions for a drum entrance, vocal lift, or instrumental ending.

Parameters

Parameter	Requirement	Description
text	Required for text	Music description, 1–4,100 characters. Choose this or composition_plan. Default`—`
composition_plan	Required for a plan	Arrange the track by section, with global styles and sections. Choose this or text. Default`—`
duration	Optional with text	Target length for text input: 3–600 seconds, including decimals. Omit for model-selected length. Default`—`
is_instrumental	Optional with text	Set true for instrumental music. Applies to text input. Default`false`
respect_sections_durations	Optional with a plan	Controls adherence to requested section durations. Applies to composition_plan. Default`true`
output_format	Optional	Select the audio codec, sample rate, and bitrate from the listed values. Default`mp3_44100_128mp3_22050_32mp3_44100_32mp3_44100_64mp3_44100_96mp3_44100_192pcm_8000pcm_16000pcm_22050pcm_24000pcm_44100pcm_48000ulaw_8000alaw_8000opus_48000_32opus_48000_64opus_48000_96opus_48000_128opus_48000_192`
composition_plan.positive_global_styles	Required for a plan	Style directions for the whole track, such as genre, instruments, and rhythm. An empty array is valid. Default`—`
composition_plan.negative_global_styles	Required for a plan	Style elements to avoid throughout the track. An empty array is valid. Default`—`
composition_plan.sections	Required for a plan	At least one section, arranged in array order. Default`—`
composition_plan.sections[].section_name	Required per section	Section name, 1–100 characters, identifying structures such as an intro, verse, or chorus. Default`—`
composition_plan.sections[].positive_local_styles	Required per section	Instrument, vocal, and mood directions for this section. An empty array is valid. Default`—`
composition_plan.sections[].negative_local_styles	Required per section	Style elements to avoid in this section. An empty array is valid. Default`—`
composition_plan.sections[].duration	Required per section	Target duration for this section: 3–120 seconds, including decimals. Default`—`
composition_plan.sections[].lines	Required per section	One lyric line per item, up to 200 characters each. For instrumental sections, use an empty array and instrumental style directions. Default`—`

How to create music

Choose your creation pathWrite a music description in Text, or edit Composition Plan to arrange sections, styles, and lyrics.
Set the sound and timingFor text input, set Duration and Is Instrumental. For a plan, set each section’s Duration and choose Respect Sections Durations.
Review the format and estimateChoose Output Format and review the estimate on Run. Sign in, check your credit balance, then click Run.
Listen and refinePlay the track in Output, then refine the instruments, lyrics, or section arrangement for your next generation.

Usage and pricing

ElevenLabs Music Text to Audio costs 128 credits ($0.64) per started minute. Divide the duration in seconds by 60 and round up; for a composition plan, sum all sections first.

Usage	Rate	Calculation
3–60 seconds	128 credits · $0.64	Billed as one started minute.
60.1 seconds	256 credits · $1.28	Rounded up to two started minutes.
Multiple sections	Round the combined duration up	30 + 30 seconds counts as one minute; 30 + 30.1 seconds counts as two.
Text duration omitted	Estimate: 128 credits · $0.64	The pre-submission estimate uses one minute; the model chooses the generated length.

Music projects to explore

Video background musicDescribe instruments and rhythm around the scene’s mood, then choose instrumental output to create music for an edit.
Podcast intros and outrosSpecify how the intro begins and the outro resolves, using short sections to develop a recognizable musical theme.
Game scene music sketchesDescribe the setting, tension, and rhythm of a scene. Audition a short section before developing a full arrangement.
Original songwritingPlace your lyrics into verses and choruses, set vocal and accompaniment directions, and audition the arrangement.

Prompt and arrangement tips

Build prompts around genre, mood, instruments, rhythm, and vocals: “Warm indie folk, acoustic guitar, light drums, relaxed tempo, soft female vocals.”
Use global styles for the track’s shared direction and local styles for changes, such as full drums and vocal harmonies entering in the chorus.
Place lyrics into Lines in singing order. Allow time for the words in each section and plan instrumental passages for the intro and outro.
Start with a short passage to audition the tone and arrangement, then expand the plan. Change one main direction at a time to compare results.

Creation settings to check

Choose either a text description or a composition plan for each request, with the controls for that path.
Include at least one section in a plan. Keep style and lyric fields as arrays, using [] for empty lists.
Review the estimate on Run before submitting. Once complete, listen in Output or download the track from the file URL returned by the API.

Add voice to your audio project

ElevenLabs V3 Text to SpeechTurn narration text into speech to accompany your music.

ElevenLabs Turbo v2.5 Text to Speech preview

ElevenLabs Turbo v2.5 Text to SpeechCreate voice tracks from text for a podcast or video.

ElevenLabs Music Text to Audio API frequently asked questions

What is the ElevenLabs Music Text to Audio API?

ElevenLabs Music Text to Audio is an ElevenLabs model for turning text descriptions into music. It creates songs or instrumentals, with composition plans for section-specific lyrics, styles, and timing. Global and local style controls combine an overall musical direction with changes across intros, verses, and choruses. You can call it programmatically or try it from the playground above.

How do I create instrumentals with ElevenLabs Music?

For text-based creation, enable Is Instrumental and describe the instruments, mood, and rhythm. In a composition plan, leave Lines empty for instrumental sections and specify instrumental music and the instrumentation in their style directions.

How do I use my own lyrics in ElevenLabs Music?

Enter your lyrics in each section’s Lines within Composition Plan, with one line per item and up to 200 characters per line. Use local styles to describe the language, vocal delivery, and accompaniment, then set the section’s duration.

How do I arrange verses and choruses in ElevenLabs Music?

Use Composition Plan to add an intro, verses, choruses, and an outro in performance order. Give each section its own name, styles, lyrics, and duration. Enable Respect Sections Durations to follow the requested section timing.

How do global styles shape an ElevenLabs Music arrangement?

Global styles set the shared genre, instruments, and mood; local styles describe a particular section. Positive lists specify elements to include, while negative lists specify elements to avoid. For example, set an acoustic folk direction globally and add drums and harmonies in the chorus.

How long can an ElevenLabs Music track be?

Text input accepts a requested duration of 3–600 seconds; leaving it blank lets the model choose the length. In a composition plan, set each section to 3–120 seconds and use multiple sections to organize the track. Durations accept decimal values.

How should I write an ElevenLabs Music prompt?

Start with genre and mood, then add the main instruments, rhythm, and vocal direction, such as “Light jazz, warm piano, brushed drums, instrumental.” For distinct structural changes, use a composition plan with local styles for each section. Text descriptions accept up to 4,100 characters.

Which audio formats does ElevenLabs Music offer?

Output Format offers MP3, Opus, PCM, μ-law, and A-law across 19 encoding and sample-rate configurations. The default mp3_44100_128 produces 44.1 kHz MP3 at 128 kbps. See Parameters for the complete list.

How does minute billing work for ElevenLabs Music?

Each started minute costs 128 credits ($0.64). Text input uses the requested duration; composition plans sum all section durations before rounding up. A 60-second request costs 128 credits, while 60.1 seconds costs 256. When text duration is omitted, the pre-submission estimate uses one minute and the model chooses the track length.