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

# Planes de composición

Los planes de composición ofrecen un control detallado sobre la generación de música. Un plan `music_v2` o `music_v2_5` es una lista ordenada de fragmentos, donde cada fragmento define una sección de la canción con sus propios estilos, letra y duración. Usa prompts de texto para crear prototipos rápidamente y planes de composición cuando necesites una estructura de fragmentos específica, una sincronización precisa de la letra o arreglos complejos.

> **Warning**
>
> Los planes de composición y los prompts de texto son mutuamente excluyentes. Usa uno u otro, pero no ambos.

```json
{
  "chunks": [
    {
      "text": "[Verse 1]\nWoke up today with a feeling inside\nSomething is changing I cannot hide\nThe sun on my face and the wind at my back\nI'm finally ready to get on track",
      "duration_ms": 16000,
      "positive_styles": [
        "upbeat pop",
        "female vocalist with clear tone",
        "acoustic guitar and light synths",
        "gentle and conversational vocals",
        "light drums in background",
        "polished production",
        "120 BPM",
        "C major"
      ],
      "negative_styles": ["dark", "aggressive", "slow tempo", "a cappella"],
      "context_adherence": "high"
    },
    {
      "text": "[Verse 2]\nUsed to be scared of the world outside\nBuilding up walls where I used to hide\nBut now I see clearly what I need to do\nTake that first step into something new",
      "duration_ms": 16000,
      "positive_styles": [
        "confident vocals",
        "fuller guitar strumming",
        "steady drum beat",
        "bass joins in"
      ],
      "negative_styles": ["a cappella", "sparse", "quiet"],
      "context_adherence": "high"
    },
    {
      "text": "[Pre-Chorus]\nNo more waiting for tomorrow\nThis is my time now",
      "duration_ms": 8000,
      "positive_styles": [
        "building intensity",
        "rising synth melody",
        "driving drums",
        "full band playing"
      ],
      "negative_styles": ["a cappella", "dropping out"],
      "context_adherence": "high"
    },
    {
      "text": "[Chorus]\nI'm breaking through\nNothing's gonna stop me now\nI'm breaking through\nFinally found out how",
      "duration_ms": 16000,
      "positive_styles": [
        "powerful and anthemic vocals",
        "full band at maximum energy",
        "punchy drums and bass",
        "layered synths and guitar"
      ],
      "negative_styles": ["a cappella", "minimal", "stripped back"],
      "context_adherence": "high"
    },
    {
      "text": "[Outro]",
      "duration_ms": 8000,
      "positive_styles": [
        "instrumental fade out",
        "guitar melody repeating",
        "drums softening",
        "gentle ending"
      ],
      "negative_styles": ["vocals", "abrupt ending", "building"],
      "context_adherence": "high"
    }
  ]
}
```

<elevenlabs-audio-player audio-title="Pop Song" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-pop-song.mp3" />

> **Note**
>
> Los planes de composición basados en fragmentos requieren `music_v2` o `music_v2_5`. Pasa `model_id="music_v2_5"`
> al componer.

## Inicio rápido

Sigue la [guía de inicio rápido de música](/docs/es/eleven-api/guides/cookbooks/music) para configurar tu clave de API e instalar el SDK; después, usa planes de composición para tener más control.

### Genera música con un plan de composición

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

composition_plan = {
    "chunks": [
        {
            "text": "[Verse]\nWalking down an empty street\nWondering who I'll meet",
            "duration_ms": 15000,
            "positive_styles": ["pop", "upbeat", "female vocals", "soft vocals", "acoustic guitar"],
            "negative_styles": ["dark", "slow"],
            "context_adherence": "high"
        },
        {
            "text": "[Chorus]\nThis is my moment\nI won't let it go",
            "duration_ms": 15000,
            "positive_styles": ["powerful vocals", "full band"],
            "negative_styles": [],
            "context_adherence": "high"
        }
    ]
}

audio = elevenlabs.music.compose(
    composition_plan=composition_plan,
    model_id="music_v2_5",
    # with_timestamps=True,  # Optional: return word-level timestamps
)

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

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

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

const compositionPlan = {
  chunks: [
    {
      text: "[Verse]\nWalking down an empty street\nWondering who I'll meet",
      durationMs: 15000,
      positiveStyles: ["pop", "upbeat", "female vocals", "soft vocals", "acoustic guitar"],
      negativeStyles: ["dark", "slow"],
      contextAdherence: "high",
    },
    {
      text: "[Chorus]\nThis is my moment\nI won't let it go",
      durationMs: 15000,
      positiveStyles: ["powerful vocals", "full band"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const audio = await elevenlabs.music.compose({
  compositionPlan,
  modelId: "music_v2_5",
  // withTimestamps: true,  // Optional: return word-level timestamps
});
```

### Genera un plan a partir de un prompt

Genera un plan de composición a partir de una descripción de texto y modifícalo antes de generar:

```python
plan = elevenlabs.music.composition_plan.create(
    prompt="An upbeat pop song about summer adventures",
    music_length_ms=60000,
    model_id="music_v2_5"
)

# Modify the generated plan
plan["chunks"][0]["text"] = "[Verse 1]\nCustom lyrics here"

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

```typescript
const plan = await elevenlabs.music.compositionPlan.create({
  prompt: "An upbeat pop song about summer adventures",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
});

// Modify the generated plan
plan.chunks[0].text = "[Verse 1]\nCustom lyrics here";

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

## Referencia de estructura

### Fragmentos

Un plan de composición es una lista ordenada de hasta 30 fragmentos. Cada fragmento genera una sección de la canción a partir de su `text` y sus estilos. El primer fragmento es el más importante: sus estilos definen el tono y el género generales de toda la canción.

| Campo               | Tipo   | Descripción                                                                                                                |
| ------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------- |
| `text`              | string | Nombre de la sección entre corchetes (`[Verse 1]`), líneas de letra e indicaciones en línea entre llaves (`{scratching}`). |
| `duration_ms`       | number | Duración en milisegundos (3000-120 000).                                                                                   |
| `positive_styles`   | array  | Estilos e indicaciones que incluir (máx. 50).                                                                              |
| `negative_styles`   | array  | Estilos e indicaciones que evitar (máx. 50). Por defecto, está vacío.                                                      |
| `context_adherence` | string | `low`, `medium` o `high` (predeterminado). Indica hasta qué punto el fragmento sigue a los fragmentos circundantes.        |

Una canción puede tener hasta 30 fragmentos. La duración total debe estar entre 3 segundos y 10 minutos, y cada fragmento debe durar entre 3 y 120 segundos.

> **Tip**
>
> Los estilos del primer fragmento son los más importantes, ya que definen el tono y el género generales. Intenta
> usar al menos 6-7 estilos en los primeros fragmentos hasta que la dirección quede establecida. Los estilos genéricos como
> "great production quality" son buenas opciones predeterminadas para añadir a la lista.

Los fragmentos también pueden hacer referencia al audio de una canción almacenada para mantener secciones existentes sin cambios o condicionar nuevo audio a partir de ellas. Consulta [retoque de música](/docs/es/eleven-api/guides/how-to/music/inpainting) para editar y combinar canciones existentes.

## Escribir letras

El campo `text` combina el nombre de la sección, la letra y las indicaciones en línea:

* **Nombre de la sección** entre corchetes: `[Verse 1]`, `[Chorus]`, `[Bridge]`
* **Letra** como texto sin formato, con cada línea separada por un salto de línea (`\n`)
* **Sonidos fonéticos** entre paréntesis: `(hmmm hmmm)`, `(ooh)`, `(yeah)`
* **Indicaciones en línea** entre llaves: `{guitar solo}`, `{scratching}`, `{instrumental break}`

Usa llaves para indicaciones cortas en línea. Para características más amplias que se aplican a todo el fragmento —género, instrumentación o estilo vocal general— usa `positive_styles` en su lugar.

**`Incorrecto`**

```json title="Incorrecto"
{
  "text": "[Verse]\n(soft female vocals) I've been waiting\n(instrumental break)\nfor you"
}
```

**`Correcto`**

```json title="Correcto"
{
  "text": "[Verse]\nI've been waiting\n{instrumental break}\nfor you",
  "positive_styles": ["soft female vocals"]
}
```

En el ejemplo corregido, el estilo vocal general pasa a `positive_styles`, mientras que la indicación corta en línea permanece en `text` usando llaves en lugar de paréntesis.

## Consejos de estilo

Sé específico con los descriptores de estilo:

```json
{
  "positive_styles": [
    "warm acoustic guitar with light fingerpicking",
    "soft female vocals with intimate delivery",
    "gentle percussion with brushed snare",
    "80 BPM"
  ]
}
```

Usa estilos negativos sin escatimar para evitar sonidos no deseados. Los estilos deben estar en inglés (la letra puede estar en cualquier idioma).

Si incluyes contenido protegido por derechos de autor en los estilos, la API devuelve un error `bad_composition_plan` con una alternativa sugerida. Consulta [gestión de material protegido por derechos de autor](/docs/es/eleven-api/guides/cookbooks/music#copyrighted-material).

## Ejemplos

### Instrumental cinematográfico

```json
{
  "chunks": [
    {
      "text": "[Tension Build]",
      "duration_ms": 15000,
      "positive_styles": [
        "cinematic",
        "orchestral",
        "epic",
        "low strings tremolo",
        "building intensity",
        "80 BPM",
        "D minor"
      ],
      "negative_styles": ["vocals", "lyrics", "pop", "electronic", "bright"],
      "context_adherence": "high"
    },
    {
      "text": "[Climax]",
      "duration_ms": 15000,
      "positive_styles": ["full orchestra", "brass fanfare", "triumphant"],
      "negative_styles": ["quiet", "vocals"],
      "context_adherence": "high"
    },
    {
      "text": "[Resolution]",
      "duration_ms": 10000,
      "positive_styles": ["gentle strings", "piano melody", "fading out"],
      "negative_styles": ["intense", "vocals"],
      "context_adherence": "high"
    }
  ]
}
```

<elevenlabs-audio-player audio-title="Cinematic Instrumental" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-cinematic-instrumental.mp3" />

### Anuncio con locución

```json
{
  "chunks": [
    {
      "text": "[Intro]",
      "duration_ms": 5000,
      "positive_styles": [
        "upbeat",
        "modern pop",
        "energetic",
        "120 BPM",
        "instrumental",
        "catchy hook"
      ],
      "negative_styles": ["sad", "slow", "dark", "vocals"],
      "context_adherence": "high"
    },
    {
      "text": "[Voiceover]\nIntroducing the future of productivity\nWork smarter, not harder",
      "duration_ms": 10000,
      "positive_styles": ["spoken voiceover", "confident male voice", "background music"],
      "negative_styles": ["singing"],
      "context_adherence": "high"
    },
    {
      "text": "[Outro]",
      "duration_ms": 5000,
      "positive_styles": ["musical sting", "memorable"],
      "negative_styles": ["vocals"],
      "context_adherence": "high"
    }
  ]
}
```

<elevenlabs-audio-player audio-title="Advertisement" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/example-advertisement.mp3" />

## Siguientes pasos

#### [Inicio rápido de música](/docs/es/eleven-api/guides/cookbooks/music)

Empieza con la generación de música básica

#### [Retoque de música](/docs/es/eleven-api/guides/how-to/music/inpainting)

Remezcla, amplía y une secciones de canciones existentes

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

Documentación completa de la API

#### [Guía de prompting](/docs/es/overview/capabilities/music/best-practices)

Prácticas recomendadas para prompts de música