Music inpainting

Edit and combine sections of existing songs

Music inpainting is an enterprise feature. Contact sales for access.

Music inpainting allows you to modify specific sections of a song while keeping the rest unchanged. Store a generated song, then reference its sections in new composition plans to regenerate parts, extend with new intros and outros, or combine sections from multiple songs.

Quickstart

Store a song for inpainting

You can store a song for inpainting in two ways: generate a new song with store_for_inpainting, or upload an existing audio file.

Generate and store

Upload existing file

1 import os
2 from dotenv import load_dotenv
3 from elevenlabs.client import ElevenLabs
4 
5 load_dotenv()
6 elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
7 
8 # Generate a song and store it for later inpainting
9 response = elevenlabs.music.compose_detailed(
10     prompt="An upbeat pop song with verse and chorus",
11     music_length_ms=60000,
12     store_for_inpainting=True
13 )
14 song_id = response.song_id
15 
16 # Save the audio
17 with open("original.mp3", "wb") as f:
18     f.write(response.audio)

Edit a section using source_from

Reference stored sections with source_from to keep them unchanged, and omit it to regenerate:

1 # Keep the first 30 seconds, regenerate the rest with new style
2 composition_plan = {
3     "positive_global_styles": ["pop", "energetic"],
4     "negative_global_styles": [],
5     "sections": [
6         {
7             # Keep original verse (first 30 seconds)
8             "section_name": "Original Verse",
9             "duration_ms": 30000,
10             "source_from": {
11                 "song_id": song_id,
12                 "range": {"start_ms": 0, "end_ms": 30000}
13             },
14             "positive_local_styles": [],
15             "negative_local_styles": [],
16             "lines": []
17         },
18         {
19             # Regenerate chorus with new style
20             "section_name": "New Chorus",
21             "duration_ms": 30000,
22             "positive_local_styles": ["bigger drums", "layered vocals", "anthemic"],
23             "negative_local_styles": ["sparse", "minimal"],
24             "lines": ["We're rising up tonight", "Nothing can stop us now"]
25         }
26     ]
27 }
28 
29 audio = elevenlabs.music.compose(composition_plan=composition_plan)
30 
31 with open("edited.mp3", "wb") as f:
32     for chunk in audio:
33         f.write(chunk)

Negative ranges

Edit a small portion within a section using negative_ranges:

1 {
2   "section_name": "Verse with edited portion",
3   "duration_ms": 15500,
4   "source_from": {
5     "song_id": "ePfznvNUzFziFj8mRBbS",
6     "range": { "start_ms": 0, "end_ms": 15500 },
7     "negative_ranges": [{ "start_ms": 8000, "end_ms": 12000 }]
8   },
9   "positive_local_styles": ["celebratory"],
10   "negative_local_styles": [],
11   "lines": [
12     "Happy birthday to you",
13     "Happy birthday to you",
14     "Happy birthday dear Johnny",
15     "Happy birthday to you"
16   ]
17 }

This keeps seconds 0-8 and 12-15.5 from the original, regenerating only seconds 8-12.

Examples

Edit a single section

Generate a movie trailer, then regenerate just the outro with different lyrics.

Generate the original

1 composition_plan = {
2     "positive_global_styles": ["cinematic", "epic", "orchestral", "trailer"],
3     "negative_global_styles": ["acoustic", "pop", "minimalistic"],
4     "sections": [
5         {
6             "section_name": "Intro",
7             "positive_local_styles": ["low strings", "suspenseful"],
8             "negative_local_styles": [],
9             "duration_ms": 15000,
10             "lines": ["In a world beyond code", "Where sound becomes life"]
11         },
12         {
13             "section_name": "Build",
14             "positive_local_styles": ["rising brass", "full orchestra"],
15             "negative_local_styles": [],
16             "duration_ms": 20000,
17             "lines": ["Technology awakens the future", "Shaping every word into power"]
18         },
19         {
20             "section_name": "Bridge",
21             "positive_local_styles": ["ethereal choir", "crescendo"],
22             "negative_local_styles": [],
23             "duration_ms": 15000,
24             "lines": ["(ah ah ah ah)"]
25         },
26         {
27             "section_name": "Outro",
28             "positive_local_styles": ["deep narration", "epic finale"],
29             "negative_local_styles": [],
30             "duration_ms": 10000,
31             "lines": ["The voice of tomorrow, unleashed", "Elevenlabs"]
32         }
33     ]
34 }
35 
36 response = elevenlabs.music.compose_detailed(
37     composition_plan=composition_plan,
38     store_for_inpainting=True
39 )
40 song_id = response.song_id

Edit just the outro

1 from copy import deepcopy
2 
3 edited_plan = deepcopy(composition_plan)
4 
5 # Keep first 3 sections from original
6 edited_plan["sections"][0]["source_from"] = {
7     "song_id": song_id,
8     "range": {"start_ms": 0, "end_ms": 15000}
9 }
10 edited_plan["sections"][1]["source_from"] = {
11     "song_id": song_id,
12     "range": {"start_ms": 15000, "end_ms": 35000}
13 }
14 edited_plan["sections"][2]["source_from"] = {
15     "song_id": song_id,
16     "range": {"start_ms": 35000, "end_ms": 50000}
17 }
18 
19 # Change the outro lyrics (no source_from = regenerate)
20 edited_plan["sections"][3]["lines"] = ["The future has arrived", "ElevenLabs"]
21 
22 audio = elevenlabs.music.compose(composition_plan=edited_plan)

Extend a song

Add a new intro and outro to an existing song.

Generate the original

1 response = elevenlabs.music.compose_detailed(
2     prompt="Berlin night club techno",
3     music_length_ms=60000,
4     store_for_inpainting=True
5 )
6 song_id = response.song_id

Extend with new intro and outro

1 extend_plan = {
2     "positive_global_styles": [],
3     "negative_global_styles": [],
4     "sections": [
5         {
6             "section_name": "New Intro",
7             "positive_local_styles": [],
8             "negative_local_styles": [],
9             "duration_ms": 30000,
10             "lines": []
11         },
12         {
13             "section_name": "Original Core",
14             "positive_local_styles": [],
15             "negative_local_styles": [],
16             "duration_ms": 40000,
17             "source_from": {
18                 "song_id": song_id,
19                 "range": {"start_ms": 10000, "end_ms": 50000}
20             },
21             "lines": []
22         },
23         {
24             "section_name": "New Outro",
25             "positive_local_styles": [],
26             "negative_local_styles": [],
27             "duration_ms": 30000,
28             "lines": []
29         }
30     ]
31 }
32 
33 audio = elevenlabs.music.compose(composition_plan=extend_plan)

Create a seamless loop

Generate a musical phrase and create a loop using a “glue” section.

Generate a short clip

1 composition_plan = {
2     "positive_global_styles": ["acoustic guitar", "fingerpicking", "warm tone"],
3     "negative_global_styles": ["electric", "drums", "electronic"],
4     "sections": [
5         {
6             "section_name": "Solo Acoustic",
7             "positive_local_styles": ["fingerpicking", "soft dynamics"],
8             "negative_local_styles": [],
9             "duration_ms": 10000,
10             "lines": []
11         }
12     ]
13 }
14 
15 response = elevenlabs.music.compose_detailed(
16     composition_plan=composition_plan,
17     store_for_inpainting=True
18 )
19 song_id = response.song_id

Create a loop with glue section

1 loop_plan = {
2     "positive_global_styles": [],
3     "negative_global_styles": [],
4     "sections": [
5         {
6             "section_name": "Loop Start",
7             "positive_local_styles": [],
8             "negative_local_styles": [],
9             "duration_ms": 5000,
10             "source_from": {
11                 "song_id": song_id,
12                 "range": {"start_ms": 3000, "end_ms": 8000}
13             },
14             "lines": []
15         },
16         {
17             # Glue section - model generates a smooth transition
18             "section_name": "Glue",
19             "positive_local_styles": [],
20             "negative_local_styles": [],
21             "duration_ms": 3000,
22             "lines": []
23         },
24         {
25             "section_name": "Loop End",
26             "positive_local_styles": [],
27             "negative_local_styles": [],
28             "duration_ms": 5000,
29             "source_from": {
30                 "song_id": song_id,
31                 "range": {"start_ms": 3000, "end_ms": 8000}
32             },
33             "lines": []
34         }
35     ]
36 }
37 
38 audio = elevenlabs.music.compose(composition_plan=loop_plan)

Constraints

Constraint	Value
Maximum context window	5 minutes (300,000ms)
Minimum section duration	3 seconds (3,000ms)
Minimum negative range	50ms

Next steps

Composition plans

Learn composition plan fundamentals

API reference

Complete API documentation

1	import os
2	from dotenv import load_dotenv
3	from elevenlabs.client import ElevenLabs
4
5	load_dotenv()
6	elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
7
8	# Generate a song and store it for later inpainting
9	response = elevenlabs.music.compose_detailed(
10	prompt="An upbeat pop song with verse and chorus",
11	music_length_ms=60000,
12	store_for_inpainting=True
13	)
14	song_id = response.song_id
15
16	# Save the audio
17	with open("original.mp3", "wb") as f:
18	f.write(response.audio)

1	# Keep the first 30 seconds, regenerate the rest with new style
2	composition_plan = {
3	"positive_global_styles": ["pop", "energetic"],
4	"negative_global_styles": [],
5	"sections": [
6	{
7	# Keep original verse (first 30 seconds)
8	"section_name": "Original Verse",
9	"duration_ms": 30000,
10	"source_from": {
11	"song_id": song_id,
12	"range": {"start_ms": 0, "end_ms": 30000}
13	},
14	"positive_local_styles": [],
15	"negative_local_styles": [],
16	"lines": []
17	},
18	{
19	# Regenerate chorus with new style
20	"section_name": "New Chorus",
21	"duration_ms": 30000,
22	"positive_local_styles": ["bigger drums", "layered vocals", "anthemic"],
23	"negative_local_styles": ["sparse", "minimal"],
24	"lines": ["We're rising up tonight", "Nothing can stop us now"]
25	}
26	]
27	}
28
29	audio = elevenlabs.music.compose(composition_plan=composition_plan)
30
31	with open("edited.mp3", "wb") as f:
32	for chunk in audio:
33	f.write(chunk)

1	{
2	"section_name": "Verse with edited portion",
3	"duration_ms": 15500,
4	"source_from": {
5	"song_id": "ePfznvNUzFziFj8mRBbS",
6	"range": { "start_ms": 0, "end_ms": 15500 },
7	"negative_ranges": [{ "start_ms": 8000, "end_ms": 12000 }]
8	},
9	"positive_local_styles": ["celebratory"],
10	"negative_local_styles": [],
11	"lines": [
12	"Happy birthday to you",
13	"Happy birthday to you",
14	"Happy birthday dear Johnny",
15	"Happy birthday to you"
16	]
17	}

1	composition_plan = {
2	"positive_global_styles": ["cinematic", "epic", "orchestral", "trailer"],
3	"negative_global_styles": ["acoustic", "pop", "minimalistic"],
4	"sections": [
5	{
6	"section_name": "Intro",
7	"positive_local_styles": ["low strings", "suspenseful"],
8	"negative_local_styles": [],
9	"duration_ms": 15000,
10	"lines": ["In a world beyond code", "Where sound becomes life"]
11	},
12	{
13	"section_name": "Build",
14	"positive_local_styles": ["rising brass", "full orchestra"],
15	"negative_local_styles": [],
16	"duration_ms": 20000,
17	"lines": ["Technology awakens the future", "Shaping every word into power"]
18	},
19	{
20	"section_name": "Bridge",
21	"positive_local_styles": ["ethereal choir", "crescendo"],
22	"negative_local_styles": [],
23	"duration_ms": 15000,
24	"lines": ["(ah ah ah ah)"]
25	},
26	{
27	"section_name": "Outro",
28	"positive_local_styles": ["deep narration", "epic finale"],
29	"negative_local_styles": [],
30	"duration_ms": 10000,
31	"lines": ["The voice of tomorrow, unleashed", "Elevenlabs"]
32	}
33	]
34	}
35
36	response = elevenlabs.music.compose_detailed(
37	composition_plan=composition_plan,
38	store_for_inpainting=True
39	)
40	song_id = response.song_id

1	from copy import deepcopy
2
3	edited_plan = deepcopy(composition_plan)
4
5	# Keep first 3 sections from original
6	edited_plan["sections"][0]["source_from"] = {
7	"song_id": song_id,
8	"range": {"start_ms": 0, "end_ms": 15000}
9	}
10	edited_plan["sections"][1]["source_from"] = {
11	"song_id": song_id,
12	"range": {"start_ms": 15000, "end_ms": 35000}
13	}
14	edited_plan["sections"][2]["source_from"] = {
15	"song_id": song_id,
16	"range": {"start_ms": 35000, "end_ms": 50000}
17	}
18
19	# Change the outro lyrics (no source_from = regenerate)
20	edited_plan["sections"][3]["lines"] = ["The future has arrived", "ElevenLabs"]
21
22	audio = elevenlabs.music.compose(composition_plan=edited_plan)

1	response = elevenlabs.music.compose_detailed(
2	prompt="Berlin night club techno",
3	music_length_ms=60000,
4	store_for_inpainting=True
5	)
6	song_id = response.song_id

1	extend_plan = {
2	"positive_global_styles": [],
3	"negative_global_styles": [],
4	"sections": [
5	{
6	"section_name": "New Intro",
7	"positive_local_styles": [],
8	"negative_local_styles": [],
9	"duration_ms": 30000,
10	"lines": []
11	},
12	{
13	"section_name": "Original Core",
14	"positive_local_styles": [],
15	"negative_local_styles": [],
16	"duration_ms": 40000,
17	"source_from": {
18	"song_id": song_id,
19	"range": {"start_ms": 10000, "end_ms": 50000}
20	},
21	"lines": []
22	},
23	{
24	"section_name": "New Outro",
25	"positive_local_styles": [],
26	"negative_local_styles": [],
27	"duration_ms": 30000,
28	"lines": []
29	}
30	]
31	}
32
33	audio = elevenlabs.music.compose(composition_plan=extend_plan)

1	composition_plan = {
2	"positive_global_styles": ["acoustic guitar", "fingerpicking", "warm tone"],
3	"negative_global_styles": ["electric", "drums", "electronic"],
4	"sections": [
5	{
6	"section_name": "Solo Acoustic",
7	"positive_local_styles": ["fingerpicking", "soft dynamics"],
8	"negative_local_styles": [],
9	"duration_ms": 10000,
10	"lines": []
11	}
12	]
13	}
14
15	response = elevenlabs.music.compose_detailed(
16	composition_plan=composition_plan,
17	store_for_inpainting=True
18	)
19	song_id = response.song_id

1	loop_plan = {
2	"positive_global_styles": [],
3	"negative_global_styles": [],
4	"sections": [
5	{
6	"section_name": "Loop Start",
7	"positive_local_styles": [],
8	"negative_local_styles": [],
9	"duration_ms": 5000,
10	"source_from": {
11	"song_id": song_id,
12	"range": {"start_ms": 3000, "end_ms": 8000}
13	},
14	"lines": []
15	},
16	{
17	# Glue section - model generates a smooth transition
18	"section_name": "Glue",
19	"positive_local_styles": [],
20	"negative_local_styles": [],
21	"duration_ms": 3000,
22	"lines": []
23	},
24	{
25	"section_name": "Loop End",
26	"positive_local_styles": [],
27	"negative_local_styles": [],
28	"duration_ms": 5000,
29	"source_from": {
30	"song_id": song_id,
31	"range": {"start_ms": 3000, "end_ms": 8000}
32	},
33	"lines": []
34	}
35	]
36	}
37
38	audio = elevenlabs.music.compose(composition_plan=loop_plan)