Retoque de música | ElevenLabs Documentation

El retoque de música con el modelo music_v2 o music_v2_5 te permite modificar partes específicas de una canción manteniendo intacto el resto. Almacena una canción generada y, después, haz referencia a sus partes en un plan de composición para mantenerlas sin cambios, regenerarlas o condicionar nuevo audio a partir del original.

Cómo funciona

Un plan de composición music_v2 o music_v2_5 es una lista ordenada de fragmentos. Cada fragmento es de uno de estos dos tipos:

Fragmento de generación — genera audio nuevo a partir de text y estilos. Úsalo para regenerar una sección o añadir material nuevo.
Fragmento de referencia de audio — inserta sin cambios un fragmento de una canción almacenada. Úsalo para mantener una sección de una canción existente exactamente como está.

Inicio rápido

Almacena una canción para retocarla

Puedes almacenar una canción para retocarla de dos formas: genera una canción nueva con store_for_inpainting o sube un archivo de audio existente.

Generar y almacenar

Subir archivo 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)

Mantén y regenera fragmentos

Crea un plan que combine fragmentos de referencia de audio (mantenidos) con fragmentos de generación (regenerados) y pásalo a compose con 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)

Condicionamiento

Un fragmento de generación puede condicionarse a partir de un segmento de audio almacenado con conditioning_ref. El modelo regenera el fragmento manteniéndose próximo a las características musicales de la referencia. Controla hasta qué punto el fragmento sigue la referencia con condition_strength (low, medium, high o 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"
}

El primer fragmento influye en la generación de todos los fragmentos posteriores. Para condicionar toda la canción a una referencia, aplica conditioning_ref desde el primer fragmento.

Una referencia de condicionamiento puede durar como máximo 30 segundos (30 000 ms).

Adherencia al contexto

Cada fragmento de generación tiene un nivel de context_adherence que controla hasta qué punto sigue a los fragmentos adyacentes:

high (predeterminado) — mantiene la coherencia con los fragmentos circundantes. Úsalo para lograr transiciones fluidas entre el audio mantenido y el regenerado.
medium — equilibra la coherencia con la libertad creativa.
low — permite que el fragmento se aleje de su contexto y sea más creativo.

Ejemplos

Editar una sola sección

Genera un tráiler de película y, después, regenera solo el outro con una letra diferente.

Generar el 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

Editar solo el outro

Conserva las tres primeras secciones (segundos 0–50) con un único fragmento de referencia de audio y regenera el outro:

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

Extender una canción

Añade un nuevo intro y outro a una canción existente.

Generar el 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

Extender con un nuevo intro y outro

Rodea un fragmento conservado del original con dos nuevos fragmentos de generación:

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

Crear un bucle continuo

Genera una frase musical y crea un bucle con un fragmento de «unión» que conecte el mismo corte repetido dos veces.

Generar un clip corto

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

Crear un bucle con un fragmento de unión

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

Generar una canción similar

Condiciona una canción completamente nueva con un fragmento corto de una ya existente para conservar sus características musicales. Como el primer fragmento influye en todos los que le siguen, aplicar conditioning_ref al primer fragmento da forma a toda la generación, aunque solo ese fragmento haga referencia al audio almacenado.

Generar el 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

Generar una nueva canción condicionada por la 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")

Referencia de fragmentos

Un plan de music_v2 contiene hasta 30 fragmentos. Cada fragmento es de generación o de referencia de audio.

Fragmento de generación

Campo	Tipo	Descripción
`text`	cadena	Nombre de la sección entre corchetes (`[Verse 1]`), líneas de letra e indicaciones en línea entre llaves (`{scratching}`).
`duration_ms`	número	Duración en milisegundos (3.000-120.000).
`positive_styles`	matriz	Estilos e indicaciones que incluir (máx. 50).
`negative_styles`	matriz	Estilos e indicaciones que evitar (máx. 50). De forma predeterminada, está vacío.
`context_adherence`	cadena	`low`, `medium` o `high` (valor predeterminado). Indica hasta qué punto el fragmento sigue a los fragmentos de su entorno.
`conditioning_ref`	objeto \| null	Corte opcional `{ song_id, range }` de audio almacenado para condicionarlo. El valor predeterminado es `null`.
`condition_strength`	cadena \| null	`low`, `medium` (valor predeterminado), `high` o `xhigh`. Indica con qué intensidad el fragmento sigue la referencia de condicionamiento.

Los estilos del primer fragmento son los más importantes, ya que definen el tono y el género generales. Procura incluir al menos 6-7 estilos en los primeros fragmentos hasta que se establezca la dirección.

Fragmento de referencia de audio

Campo	Tipo	Descripción
`song_id`	cadena	ID de la canción almacenada de la que obtener el audio.
`range`	objeto	Corte `{ start_ms, end_ms }` de la canción almacenada que se inserta sin cambios.

Restricciones

Restricción	Valor
Máximo de fragmentos por plan	30
Duración mínima del fragmento	3 segundos (3.000 ms)
Duración máxima del fragmento	2 minutos (120.000 ms)
Máxima referencia de condicionamiento	30 segundos (30.000 ms)
Intervalo de tiempo mínimo	50 ms

Siguientes pasos

Planes de composición

Aprende los fundamentos de los planes de composición

Referencia de la API

Documentación completa de la API