Music

ElevenLabs Music Generation

Generate music from text prompts - supports instrumental tracks, songs with lyrics, and fine-grained control via composition plans.

Setup: See Installation Guide. For JavaScript, use @elevenlabs/* packages only.

Quick Start

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.music.compose(
    prompt="A chill lo-fi hip hop beat with jazzy piano chords",
    music_length_ms=30000
)

with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

JavaScript

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";

const client = new ElevenLabsClient();
const audio = await client.music.compose({
  prompt: "A chill lo-fi hip hop beat with jazzy piano chords",
  musicLengthMs: 30000,
});
audio.pipe(createWriteStream("output.mp3"));

cURL

curl -X POST "https://api.elevenlabs.io/v1/music" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "A chill lo-fi beat", "music_length_ms": 30000}' --output output.mp3

Methods

See API Reference for full parameter details.

music.upload is available to enterprise clients with access to the inpainting feature.

Video to Music

Generate background music that follows one or more uploaded video clips. The API combines videos in order, accepts an optional natural-language description, and lets you steer style with up to 10 tags such as upbeat or cinematic.

Python

from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.music.video_to_music(
    videos=["trailer.mp4"],
    description="Build suspense, then resolve with a warm cinematic finish.",
    tags=["cinematic", "suspenseful", "uplifting"],
)

with open("video-score.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

cURL

curl -X POST "https://api.elevenlabs.io/v1/music/video-to-music" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "videos=@trailer.mp4" \
  -F "description=Build suspense, then resolve with a warm cinematic finish." \
  -F "tags=cinematic" \
  -F "tags=suspenseful" \
  -F "tags=uplifting" \
  --output video-score.mp3

Constraints from the current API schema:

• Upload 1-10 video files per request
• Keep total combined upload size at or below 200 MB
• Keep total combined video duration at or below 600 seconds
• Use description for high-level musical direction and tags for concise style cues

Composition Plans

For granular control, generate a composition plan first, modify it, then compose:

plan = client.music.composition_plan.create(
    prompt="An epic orchestral piece building to a climax",
    music_length_ms=60000
)

# Inspect/modify styles and sections
print(plan.positiveGlobalStyles)  # e.g. ["orchestral", "epic", "cinematic"]

audio = client.music.compose(
    composition_plan=plan,
    music_length_ms=60000
)

Content Restrictions

• Cannot reference specific artists, bands, or copyrighted lyrics
• bad_prompt errors include a prompt_suggestion with alternative phrasing
• bad_composition_plan errors include a composition_plan_suggestion

Error Handling

try:
    audio = client.music.compose(prompt="...", music_length_ms=30000)
except Exception as e:
    print(f"API error: {e}")

Common errors: 401 (invalid key), 422 (invalid params), 429 (rate limit).

References

• Installation Guide
• API Reference

Music API Reference

Table of Contents

• compose
• composition_plan.create
• compose_detailed
• upload
• video_to_music
• Error Handling

compose

Generate music from a text prompt. Returns an audio stream.

Parameters

*Provide either prompt or composition_plan, not both.

Python

audio = client.music.compose(
    prompt="An upbeat electronic track with synth leads",
    music_length_ms=30000
)

with open("output.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

JavaScript

const audio = await client.music.compose({
  prompt: "An upbeat electronic track with synth leads",
  musicLengthMs: 30000,
});

const writeStream = createWriteStream("output.mp3");
audio.pipe(writeStream);

With Composition Plan

plan = client.music.composition_plan.create(
    prompt="A jazz ballad with piano and saxophone",
    music_length_ms=60000
)

# Modify the plan as needed
audio = client.music.compose(
    composition_plan=plan,
    music_length_ms=60000
)

composition_plan.create

Generate a structured composition plan from a prompt for granular control before generating audio.

Parameters

Response Structure

{
  "positiveGlobalStyles": ["jazz", "smooth", "warm"],
  "negativeGlobalStyles": ["aggressive", "distorted"],
  "sections": [
    {
      "name": "Intro",
      "localStyles": ["soft", "building"],
      "duration_ms": 15000,
      "lines": [
        { "text": "Instrumental intro", "type": "instrumental" }
      ]
    }
  ]
}

Python

plan = client.music.composition_plan.create(
    prompt="A peaceful ambient track with nature sounds",
    music_length_ms=60000
)

# Inspect and modify the plan
print(plan.positiveGlobalStyles)
for section in plan.sections:
    print(f"{section.name}: {section.duration_ms}ms")

compose_detailed

Generate music while returning both the composition plan and metadata alongside the audio.

Returns

Python

result = client.music.compose_detailed(
    prompt="A pop song about summer adventures",
    music_length_ms=120000
)

# Access the composition plan and metadata
print(result.json)

# Save the audio
with open(result.filename, "wb") as f:
    f.write(result.audio)

upload

Upload a music file for later inpainting workflows. This endpoint is available to enterprise clients with access to the inpainting feature.

Parameters

Returns

Python

client.music.upload(
    file="example_file",
)

cURL

curl -X POST "https://api.elevenlabs.io/v1/music/upload" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "file=@<file1>"

video_to_music

Generate background music that follows one or more uploaded video clips. Videos are combined in order before music generation.

Parameters

Python

audio = client.music.video_to_music(
    videos=[open("scene-1.mp4", "rb"), open("scene-2.mp4", "rb")],
    description="Cinematic ambient score with a gentle build",
    tags=["cinematic", "ambient"],
)

with open("video-score.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

cURL

curl -X POST "https://api.elevenlabs.io/v1/music/video-to-music?output_format=mp3_44100_128" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -F "videos=@scene-1.mp4" \
  -F "videos=@scene-2.mp4" \
  -F "description=Cinematic ambient score with a gentle build" \
  -F "tags=cinematic" \
  -F "tags=ambient" \
  --output video-score.mp3

Error Handling

bad_prompt

Occurs when the prompt references copyrighted material (specific artists, bands, or copyrighted lyrics). The error response includes a prompt_suggestion with alternative phrasing.

try:
    audio = client.music.compose(
        prompt="A song like Beatles",
        music_length_ms=30000
    )
except Exception as e:
    print(f"Request failed: {e}")

bad_composition_plan

Returned when a composition plan contains copyrighted styles. The error includes a composition_plan_suggestion with corrected styles. No suggestion is provided for harmful content.

Common HTTP Errors

Installation

JavaScript / TypeScript

npm install @elevenlabs/elevenlabs-js

Important: Always use @elevenlabs/elevenlabs-js. The old elevenlabs npm package (v1.x) is deprecated and should not be used.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Option 1: Environment variable (recommended)
// Set ELEVENLABS_API_KEY in your environment
const client = new ElevenLabsClient();

// Option 2: Pass directly
const client = new ElevenLabsClient({ apiKey: "your-api-key" });

Python

pip install elevenlabs

from elevenlabs import ElevenLabs

# Option 1: Environment variable (recommended)
# Set ELEVENLABS_API_KEY in your environment
client = ElevenLabs()

# Option 2: Pass directly
client = ElevenLabs(api_key="your-api-key")

cURL / REST API

Set your API key as an environment variable:

export ELEVENLABS_API_KEY="your-api-key"

Include in requests via the xi-api-key header:

curl -X POST "https://api.elevenlabs.io/v1/music" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "A chill lo-fi beat", "music_length_ms": 30000}'

Getting an API Key

1. Sign up at elevenlabs.io 2. Go to API Keys 3. Click Create API Key 4. Copy and store securely

Or use the setup-api-key skill for guided setup.

Note: Music generation requires a paid ElevenLabs plan.