Guias práticosMúsica

Preenchimento de música

Edite e combine seções de músicas existentes

O preenchimento de música com o modelo music_v2 ou music_v2_5 permite modificar partes específicas de uma música sem alterar o restante. Armazene uma música gerada e, depois, faça referência às partes dela em um plano de composição para mantê-las inalteradas, regenerá-las ou condicionar um novo áudio com base no original.

Como funciona

Um plano de composição music_v2 ou music_v2_5 é uma lista ordenada de trechos. Cada trecho é de um dos dois tipos:

  • Trecho de geração — gera novo áudio a partir de text e estilos. Use-o para regenerar uma seção ou adicionar material novo.
  • Trecho de referência de áudio — insere inalterado um segmento de uma música armazenada. Use-o para manter uma seção de uma música existente exatamente como está.

Início rápido

1

Armazene uma música para preenchimento

Você pode armazenar uma música para preenchimento de duas formas: gere uma nova música com store_for_inpainting ou envie um arquivo de áudio existente.

import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs
load_dotenv()
elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
# Generate a song and store it for later inpainting
response = elevenlabs.music.compose_detailed(
    prompt="An upbeat pop song with verse and chorus",
    music_length_ms=60000,
    model_id="music_v2_5",
    store_for_inpainting=True
)
song_id = response.song_id
# Save the audio
with open("original.mp3", "wb") as f:
    f.write(response.audio)
2

Mantenha e regenere trechos

Crie um plano que combine trechos de referência de áudio (mantidos) com trechos de geração (regenerados) e, depois, passe-o para compose com model_id="music_v2_5":

# Keep the first 30 seconds, regenerate the rest with a new style
composition_plan = {
    "chunks": [
        # Keep the original first 30 seconds unchanged
        {
            "song_id": song_id,
            "range": {"start_ms": 0, "end_ms": 30000}
        },
        # Regenerate the chorus with a new style
        {
            "text": "[Chorus]\nWe're rising up tonight\nNothing can stop us now",
            "duration_ms": 30000,
            "positive_styles": ["bigger drums", "layered vocals", "anthemic"],
            "negative_styles": ["sparse", "minimal"],
            "context_adherence": "high"
        }
    ]
}
audio = elevenlabs.music.compose(
    composition_plan=composition_plan,
    model_id="music_v2_5",
)
with open("edited.mp3", "wb") as f:
    for chunk in audio:
        f.write(chunk)

Condicionamento

Um trecho de geração pode ser condicionado a um segmento de áudio armazenado com conditioning_ref. O modelo regenera o trecho, mantendo-se próximo às características musicais da referência. Controle o quanto o trecho segue a referência com condition_strength (low, medium, high ou xhigh).

{
  "text": "[Chorus]\nThis is my moment\nI won't let it go",
  "duration_ms": 15000,
  "positive_styles": ["powerful vocals", "full band", "anthemic"],
  "negative_styles": [],
  "context_adherence": "high",
  "conditioning_ref": {
    "song_id": "vVtPM1Sas70E2LIhQFch",
    "range": { "start_ms": 30000, "end_ms": 45000 }
  },
  "condition_strength": "high"
}

O primeiro trecho influencia a geração de todos os trechos subsequentes. Para condicionar a música inteira a uma referência, aplique conditioning_ref a partir do primeiro trecho.

Uma referência de condicionamento pode ter no máximo 30 segundos (30.000 ms).

Aderência ao contexto

Cada trecho de geração tem um nível de context_adherence que controla o quanto ele segue os trechos vizinhos:

  • high (padrão) — mantém a consistência com os trechos ao redor. Use-o para transições suaves entre áudio mantido e regenerado.
  • medium — equilibra consistência e liberdade criativa.
  • low — permite que o trecho se desvie do contexto e seja mais criativo.

Exemplos

Editar uma única seção

Gere uma trilha de trailer de filme e, em seguida, gere novamente apenas o final com letras diferentes.

1

Gerar o original

composition_plan = {
    "chunks": [
        {
            "text": "[Intro]\nIn a world beyond code\nWhere sound becomes life",
            "duration_ms": 15000,
            "positive_styles": ["cinematic", "epic", "orchestral", "low strings", "suspenseful"],
            "negative_styles": ["acoustic", "pop", "minimalistic"],
            "context_adherence": "high"
        },
        {
            "text": "[Build]\nTechnology awakens the future\nShaping every word into power",
            "duration_ms": 20000,
            "positive_styles": ["rising brass", "full orchestra", "epic"],
            "negative_styles": ["acoustic", "pop"],
            "context_adherence": "high"
        },
        {
            "text": "[Bridge]\n(ah ah ah ah)",
            "duration_ms": 15000,
            "positive_styles": ["ethereal choir", "crescendo"],
            "negative_styles": [],
            "context_adherence": "high"
        },
        {
            "text": "[Outro]\nThe voice of tomorrow, unleashed\nElevenLabs",
            "duration_ms": 10000,
            "positive_styles": ["deep narration", "epic finale"],
            "negative_styles": [],
            "context_adherence": "high"
        }
    ]
}
response = elevenlabs.music.compose_detailed(
    composition_plan=composition_plan,
    model_id="music_v2_5",
    store_for_inpainting=True
)
song_id = response.song_id
2

Editar apenas o final

Mantenha as três primeiras seções (segundos 0–50) com um único trecho de referência de áudio e gere novamente o final:

edited_plan = {
    "chunks": [
        # Keep the intro, build, and bridge unchanged
        {
            "song_id": song_id,
            "range": {"start_ms": 0, "end_ms": 50000}
        },
        # Regenerate the outro with new lyrics
        {
            "text": "[Outro]\nThe future has arrived\nElevenLabs",
            "duration_ms": 10000,
            "positive_styles": ["deep narration", "epic finale"],
            "negative_styles": [],
            "context_adherence": "high"
        }
    ]
}
audio = elevenlabs.music.compose(composition_plan=edited_plan, model_id="music_v2_5")

Estender uma música

Adicione uma nova introdução e um novo final a uma música existente.

1

Gerar o original

response = elevenlabs.music.compose_detailed(
    prompt="Berlin night club techno",
    music_length_ms=60000,
    model_id="music_v2_5",
    store_for_inpainting=True
)
song_id = response.song_id
2

Estender com uma nova introdução e um novo final

Coloque um trecho preservado do original entre dois novos trechos gerados:

extend_plan = {
    "chunks": [
        # New intro
        {
            "text": "[Intro]",
            "duration_ms": 30000,
            "positive_styles": ["techno", "building tension", "filtered synths"],
            "negative_styles": [],
            "context_adherence": "high"
        },
        # Keep the core of the original (seconds 10-50)
        {
            "song_id": song_id,
            "range": {"start_ms": 10000, "end_ms": 50000}
        },
        # New outro
        {
            "text": "[Outro]",
            "duration_ms": 30000,
            "positive_styles": ["techno", "fading out", "sparse"],
            "negative_styles": [],
            "context_adherence": "high"
        }
    ]
}
audio = elevenlabs.music.compose(composition_plan=extend_plan, model_id="music_v2_5")

Criar um loop contínuo

Gere uma frase musical e crie um loop usando um trecho de “ligação” que conecta o mesmo trecho repetido duas vezes.

1

Gerar um clipe curto

composition_plan = {
    "chunks": [
        {
            "text": "[Solo Acoustic]",
            "duration_ms": 10000,
            "positive_styles": ["acoustic guitar", "fingerpicking", "warm tone", "soft dynamics"],
            "negative_styles": ["electric", "drums", "electronic"],
            "context_adherence": "high"
        }
    ]
}
response = elevenlabs.music.compose_detailed(
    composition_plan=composition_plan,
    model_id="music_v2_5",
    store_for_inpainting=True
)
song_id = response.song_id
2

Criar um loop com um trecho de ligação

loop_plan = {
    "chunks": [
        # Loop start - keep a slice of the original
        {
            "song_id": song_id,
            "range": {"start_ms": 3000, "end_ms": 8000}
        },
        # Glue - generate a smooth transition between the two slices
        {
            "text": "[Glue]",
            "duration_ms": 3000,
            "positive_styles": ["acoustic guitar", "fingerpicking", "smooth transition"],
            "negative_styles": [],
            "context_adherence": "high"
        },
        # Loop end - keep the same slice again
        {
            "song_id": song_id,
            "range": {"start_ms": 3000, "end_ms": 8000}
        }
    ]
}
audio = elevenlabs.music.compose(composition_plan=loop_plan, model_id="music_v2_5")

Gerar uma música semelhante

Use um pequeno trecho de uma música existente como condicionamento para uma música totalmente nova, a fim de preservar suas características musicais. Como o primeiro trecho influencia todos os trechos seguintes, aplicar conditioning_ref ao primeiro trecho molda toda a geração, embora apenas esse trecho faça referência ao áudio armazenado.

1

Gerar o original

response = elevenlabs.music.compose_detailed(
    prompt="An upbeat pop song with bright synths and driving drums",
    music_length_ms=60000,
    model_id="music_v2_5",
    store_for_inpainting=True
)
song_id = response.song_id
2

Gerar uma nova música condicionada ao original

similar_plan = {
    "chunks": [
        # The first chunk conditions the whole song on the reference
        {
            "text": "[Verse]\nSalt on my skin from a borrowed sea\nCounting the heartbeats it takes to break free",
            "duration_ms": 30000,
            "positive_styles": ["pop", "energetic", "bright synths", "driving drums"],
            "negative_styles": ["sparse", "minimal"],
            "context_adherence": "high",
            "conditioning_ref": {
                "song_id": song_id,
                "range": {"start_ms": 0, "end_ms": 10000}
            },
            "condition_strength": "high"
        },
        {
            "text": "[Chorus]\nWe're rising up tonight\nNothing can stop us now",
            "duration_ms": 30000,
            "positive_styles": ["bigger drums", "layered vocals", "anthemic"],
            "negative_styles": ["sparse", "minimal"],
            "context_adherence": "high"
        }
    ]
}
audio = elevenlabs.music.compose(composition_plan=similar_plan, model_id="music_v2_5")

Referência dos trechos

Um plano music_v2 contém até 30 trechos. Cada trecho é um trecho de geração ou um trecho de referência de áudio.

Trecho de geração

CampoTipoDescrição
textstringNome da seção entre colchetes ([Verse 1]), linhas de letra e instruções em linha entre chaves ({scratching}).
duration_msnumberDuração em milissegundos (3.000 a 120.000).
positive_stylesarrayEstilos e instruções a incluir (máx. 50).
negative_stylesarrayEstilos e instruções a evitar (máx. 50). O padrão é vazio.
context_adherencestringlow, medium ou high (padrão). Define o quanto o trecho segue os trechos ao redor.
conditioning_refobject | nullTrecho opcional { song_id, range } de áudio armazenado usado como condicionamento. O padrão é null.
condition_strengthstring | nulllow, medium (padrão), high ou xhigh. Define o quanto o trecho segue a referência de condicionamento.

Os estilos do primeiro trecho são os mais importantes, pois definem o tom geral e o gênero. Procure usar pelo menos 6 a 7 estilos nos primeiros trechos até estabelecer a direção.

Trecho de referência de áudio

CampoTipoDescrição
song_idstringID da música armazenada da qual o áudio será obtido.
rangeobjectTrecho { start_ms, end_ms } da música armazenada a ser inserido sem alterações.

Limitações

LimitaçãoValor
Máximo de trechos por plano30
Duração mínima do trecho3 segundos (3.000 ms)
Duração máxima do trecho2 minutos (120.000 ms)
Máxima referência de condicionamento30 segundos (30.000 ms)
Intervalo de tempo mínimo50 ms

Próximas etapas

Planos de composição

Conheça os fundamentos dos planos de composição

Referência da API

Documentação completa da API