> This is a page from the ElevenLabs documentation. For a complete page index, fetch https://elevenlabs.io/docs/llms.txt. For the full documentation in a single file, fetch https://elevenlabs.io/docs/llms-full.txt.

# Retoque de música

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

```python
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)
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

const response = await elevenlabs.music.composeDetailed({
  prompt: "An upbeat pop song with verse and chorus",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
const songId = response.songId;
```

#### Subir archivo existente

```python
import os
from dotenv import load_dotenv
from elevenlabs.client import ElevenLabs

load_dotenv()
elevenlabs = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))

# Upload an existing audio file for inpainting
response = elevenlabs.music.upload(
    file=open("my-song.mp3", "rb"),
    extract_composition_plan="music_v2"  # Optional: extract the composition plan
)
song_id = response.song_id
composition_plan = response.composition_plan  # None if extract_composition_plan is False
```

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import "dotenv/config";
import fs from "fs";

const elevenlabs = new ElevenLabsClient({
  apiKey: process.env.ELEVENLABS_API_KEY,
});

const response = await elevenlabs.music.upload({
  file: fs.createReadStream("my-song.mp3"),
  extractCompositionPlan: true, // Optional: extract the composition plan
});
const songId = response.songId;
const compositionPlan = response.compositionPlan; // undefined if extractCompositionPlan is false
```

### 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"`:

```python
# 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)
```

```typescript
// Keep the first 30 seconds, regenerate the rest with a new style
const compositionPlan = {
  chunks: [
    // Keep the original first 30 seconds unchanged
    {
      songId,
      range: { startMs: 0, endMs: 30000 },
    },
    // Regenerate the chorus with a new style
    {
      text: "[Chorus]\nWe're rising up tonight\nNothing can stop us now",
      durationMs: 30000,
      positiveStyles: ["bigger drums", "layered vocals", "anthemic"],
      negativeStyles: ["sparse", "minimal"],
      contextAdherence: "high",
    },
  ],
};

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

## 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`).

```json
{
  "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"
}
```

> **Tip**
>
> 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

```python
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
```

```typescript
const compositionPlan = {
  chunks: [
    {
      text: "[Intro]\nIn a world beyond code\nWhere sound becomes life",
      durationMs: 15000,
      positiveStyles: ["cinematic", "epic", "orchestral", "low strings", "suspenseful"],
      negativeStyles: ["acoustic", "pop", "minimalistic"],
      contextAdherence: "high",
    },
    {
      text: "[Build]\nTechnology awakens the future\nShaping every word into power",
      durationMs: 20000,
      positiveStyles: ["rising brass", "full orchestra", "epic"],
      negativeStyles: ["acoustic", "pop"],
      contextAdherence: "high",
    },
    {
      text: "[Bridge]\n(ah ah ah ah)",
      durationMs: 15000,
      positiveStyles: ["ethereal choir", "crescendo"],
      negativeStyles: [],
      contextAdherence: "high",
    },
    {
      text: "[Outro]\nThe voice of tomorrow, unleashed\nElevenLabs",
      durationMs: 10000,
      positiveStyles: ["deep narration", "epic finale"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const response = await elevenlabs.music.composeDetailed({
  compositionPlan,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Tráiler de película original" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/movie_trailer.mp3" />

### Editar solo el outro

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

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

```typescript
const editedPlan = {
  chunks: [
    // Keep the intro, build, and bridge unchanged
    {
      songId,
      range: { startMs: 0, endMs: 50000 },
    },
    // Regenerate the outro with new lyrics
    {
      text: "[Outro]\nThe future has arrived\nElevenLabs",
      durationMs: 10000,
      positiveStyles: ["deep narration", "epic finale"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const audio = await elevenlabs.music.compose({
  compositionPlan: editedPlan,
  modelId: "music_v2_5",
});
```

<elevenlabs-audio-player audio-title="Outro editado" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/movie_trailer_edited.mp3" />

### Extender una canción

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

### Generar el original

```python
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
```

```typescript
const response = await elevenlabs.music.composeDetailed({
  prompt: "Berlin night club techno",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Original (60 s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/berlin_night_club_techno.mp3" />

### Extender con un nuevo intro y outro

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

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

```typescript
const extendPlan = {
  chunks: [
    // New intro
    {
      text: "[Intro]",
      durationMs: 30000,
      positiveStyles: ["techno", "building tension", "filtered synths"],
      negativeStyles: [],
      contextAdherence: "high",
    },
    // Keep the core of the original (seconds 10-50)
    {
      songId,
      range: { startMs: 10000, endMs: 50000 },
    },
    // New outro
    {
      text: "[Outro]",
      durationMs: 30000,
      positiveStyles: ["techno", "fading out", "sparse"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const audio = await elevenlabs.music.compose({
  compositionPlan: extendPlan,
  modelId: "music_v2_5",
});
```

<elevenlabs-audio-player audio-title="Extendida (100 s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/berlin_night_club_techno_extended.mp3" />

### 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

```python
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
```

```typescript
const compositionPlan = {
  chunks: [
    {
      text: "[Solo Acoustic]",
      durationMs: 10000,
      positiveStyles: ["acoustic guitar", "fingerpicking", "warm tone", "soft dynamics"],
      negativeStyles: ["electric", "drums", "electronic"],
      contextAdherence: "high",
    },
  ],
};

const response = await elevenlabs.music.composeDetailed({
  compositionPlan,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Original (10 s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/acoustic_guitar.mp3" />

### Crear un bucle con un fragmento de unión

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

```typescript
const loopPlan = {
  chunks: [
    // Loop start - keep a slice of the original
    {
      songId,
      range: { startMs: 3000, endMs: 8000 },
    },
    // Glue - generate a smooth transition between the two slices
    {
      text: "[Glue]",
      durationMs: 3000,
      positiveStyles: ["acoustic guitar", "fingerpicking", "smooth transition"],
      negativeStyles: [],
      contextAdherence: "high",
    },
    // Loop end - keep the same slice again
    {
      songId,
      range: { startMs: 3000, endMs: 8000 },
    },
  ],
};

const audio = await elevenlabs.music.compose({ compositionPlan: loopPlan, modelId: "music_v2_5" });
```

<elevenlabs-audio-player audio-title="Bucle continuo" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/acoustic_guitar_looped.mp3" />

### 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

```python
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
```

```typescript
const response = await elevenlabs.music.composeDetailed({
  prompt: "An upbeat pop song with bright synths and driving drums",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
const songId = response.songId;
```

<elevenlabs-audio-player audio-title="Original" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/conditioning-original.mp3" />

### Generar una nueva canción condicionada por la original

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

```typescript
const similarPlan = {
  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",
      durationMs: 30000,
      positiveStyles: ["pop", "energetic", "bright synths", "driving drums"],
      negativeStyles: ["sparse", "minimal"],
      contextAdherence: "high",
      conditioningRef: {
        songId,
        range: { startMs: 0, endMs: 10000 },
      },
      conditionStrength: "high",
    },
    {
      text: "[Chorus]\nWe're rising up tonight\nNothing can stop us now",
      durationMs: 30000,
      positiveStyles: ["bigger drums", "layered vocals", "anthemic"],
      negativeStyles: ["sparse", "minimal"],
      contextAdherence: "high",
    },
  ],
};

const audio = await elevenlabs.music.compose({
  compositionPlan: similarPlan,
  modelId: "music_v2_5",
});
```

<elevenlabs-audio-player audio-title="Nueva canción condicionada" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/conditioning-new.mp3" />

## 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. |

> **Tip**
>
> 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](/docs/es/eleven-api/guides/how-to/music/composition-plans)

Aprende los fundamentos de los planes de composición

#### [Referencia de la API](/docs/es/api-reference/music/compose)

Documentación completa de la API