/music

Music API Reference

All endpoints below default to music_v1 unless noted for backwards compatibility. Pass music_v2_5 unless the caller explicitly needs an older model.

Table of Contents

• compose
• stream
• composition_plan.create
• compose_detailed
• compose_detailed_stream
• upload
• video_to_music
• Inpainting
• Error Handling

compose

Generate music from a text prompt or composition plan. 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,
    model_id="music_v2_5",
)

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

TypeScript

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

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,
    model_id="music_v2_5",
)

# Modify the plan as needed
audio = client.music.compose(
    composition_plan=plan,
    model_id="music_v2_5",
)

const plan = await client.music.compositionPlan.create({
  prompt: "A jazz ballad with piano and saxophone",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
});

// Modify the plan as needed
const audio = await client.music.compose({
  compositionPlan: plan,
  modelId: "music_v2_5",
});

stream

Stream audio chunks as they are generated. Same parameters as compose; returns an iterable/async-iterable of audio bytes instead of a single response. Available on paid plans only.

Python

from io import BytesIO

stream = client.music.stream(
    prompt="A driving synthwave track with arpeggiated leads",
    music_length_ms=30000,
    model_id="music_v2_5",
)

buffer = BytesIO()
for chunk in stream:
    if chunk:
        buffer.write(chunk)

TypeScript

const stream = await client.music.stream({
  prompt: "A driving synthwave track with arpeggiated leads",
  musicLengthMs: 30000,
  modelId: "music_v2_5",
});

const chunks: Buffer[] = [];
for await (const chunk of stream) {
  chunks.push(chunk);
}

composition_plan.create

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

Parameters

Plan Structure (music_v2 and music_v2_5)

A plan is an ordered list of chunks. Each chunk is either a generation chunk or an audio reference chunk (see Inpainting).

Python

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

# Inspect or edit the plan in place
print(plan["chunks"][0]["positive_styles"])
plan["chunks"][0]["text"] = "[Intro]\nSoft pad with rain"

audio = client.music.compose(composition_plan=plan, model_id="music_v2_5")

TypeScript

const plan = await client.music.compositionPlan.create({
  prompt: "A peaceful ambient track with nature sounds",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
});

plan.chunks[0].text = "[Intro]\nSoft pad with rain";
const audio = await client.music.compose({ compositionPlan: plan, modelId: "music_v2_5" });

compose_detailed

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

Parameters

*Provide either prompt or composition_plan, not both.

Returns

Python

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

print(result.json)        # composition plan + metadata
print(result.song_id)     # reusable identifier for inpainting

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

TypeScript

import { writeFileSync } from "fs";

const result = await client.music.composeDetailed({
  prompt: "A pop song about summer adventures",
  musicLengthMs: 120000,
  modelId: "music_v2_5",
  storeForInpainting: true,
});

console.log(result.json);    // composition plan + metadata
console.log(result.songId);  // reusable identifier for inpainting

writeFileSync(result.filename, result.audio);

compose_detailed_stream

Stream music generation details as Server-Sent Events from POST /v1/music/detailed/stream. Use this when a client should receive the composition plan, song metadata, audio chunks, optional word timestamps, and completion signal incrementally.

Parameters

*Provide either prompt or composition_plan, not both.

CLI

elevenlabs music compose_detailed_stream \
  --prompt "A bright indie pop hook with warm guitars" \
  --music-length-ms 30000 \
  --model-id music_v2_5 \
  --with-timestamps true \
  --output-format auto

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

response = client.music.upload(
    file=open("my-song.mp3", "rb"),
    extract_composition_plan="music_v2_5",
)
song_id = response.song_id
composition_plan = response.composition_plan

TypeScript

import { createReadStream } from "fs";

const response = await client.music.upload({
  file: createReadStream("my-song.mp3"),
  extractCompositionPlan: "music_v2_5",
});
const songId = response.songId;
const compositionPlan = response.compositionPlan;

CLI

elevenlabs music upload \
  --file my-song.mp3 \
  --extract-composition-plan music_v2_5

video_to_music

Generate background music from uploaded video clips. This is a separate endpoint from compose (POST /v1/music/video-to-music, not POST /v1/music). See the Video to music API reference.

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"],
    model_id="music_v2_5",
)

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

TypeScript

import { createReadStream, createWriteStream } from "fs";

const audio = await client.music.videoToMusic({
  videos: [createReadStream("scene-1.mp4"), createReadStream("scene-2.mp4")],
  description: "Cinematic ambient score with a gentle build",
  tags: ["cinematic", "ambient"],
  modelId: "music_v2_5",
});

audio.pipe(createWriteStream("video-score.mp3"));

CLI

elevenlabs music video_to_music \
  --videos scene-1.mp4 \
  --description "Cinematic ambient score with a gentle build" \
  --tags cinematic \
  --output-format mp3_44100_128 \
  --output video-score.mp3

The CLI currently accepts one --videos file and one --tags value per request; use the Python or TypeScript SDK to send multiple videos or tags.

Inpainting

Inpainting edits or extends a stored song by combining audio reference chunks (unchanged slices of stored audio) with generation chunks in a single music_v2 or music_v2_5 composition plan. Available to enterprise clients.

Getting a song_id

• Call compose_detailed or compose with store_for_inpainting=True to keep a generation for later editing.
• Call upload with extract_composition_plan="music_v2_5" to import an existing track and recover its plan.

Chunk Types

Audio reference chunk — replay a slice of a stored song unchanged:

Generation chunk — same fields as a normal v2 model plan chunk (text, duration_ms, positive_styles, negative_styles, context_adherence), with two optional fields for matching the feel of an existing slice:

conditioning_ref on the first chunk influences every subsequent chunk in the plan.

Constraints

Python

plan = {
    "chunks": [
        {"song_id": song_id, "range": {"start_ms": 0, "end_ms": 30000}},
        {
            "text": "[Chorus]\nWe're rising up tonight",
            "duration_ms": 30000,
            "positive_styles": ["bigger drums", "layered vocals", "anthemic"],
            "negative_styles": ["sparse"],
            "context_adherence": "high",
            "conditioning_ref": {
                "song_id": song_id,
                "range": {"start_ms": 30000, "end_ms": 45000},
            },
            "condition_strength": "high",
        },
    ]
}

audio = client.music.compose(composition_plan=plan, model_id="music_v2_5")

TypeScript

const plan = {
  chunks: [
    { songId, range: { startMs: 0, endMs: 30000 } },
    {
      text: "[Chorus]\nWe're rising up tonight",
      durationMs: 30000,
      positiveStyles: ["bigger drums", "layered vocals", "anthemic"],
      negativeStyles: ["sparse"],
      contextAdherence: "high",
      conditioningRef: { songId, range: { startMs: 30000, endMs: 45000 } },
      conditionStrength: "high",
    },
  ],
};

const audio = await client.music.compose({ compositionPlan: plan, modelId: "music_v2_5" });

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}")

try {
  const audio = await client.music.compose({
    prompt: "A song like Beatles",
    musicLengthMs: 30000,
  });
} catch (err) {
  console.error("Request failed:", err);
}

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