Guías prácticasMúsica

Planes de composición

Control preciso de la generación de música con JSON estructurado

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.

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

{
  "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"
    }
  ]
}

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 para configurar tu clave de API e instalar el SDK; después, usa planes de composición para tener más control.

1

Genera música con un plan de composición

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

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:

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

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.

CampoTipoDescripción
textstringNombre de la sección entre corchetes ([Verse 1]), líneas de letra e indicaciones en línea entre llaves ({scratching}).
duration_msnumberDuración en milisegundos (3000-120 000).
positive_stylesarrayEstilos e indicaciones que incluir (máx. 50).
negative_stylesarrayEstilos e indicaciones que evitar (máx. 50). Por defecto, está vacío.
context_adherencestringlow, 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.

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

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

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:

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

Ejemplos

Instrumental cinematográfico

{
  "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"
    }
  ]
}

Anuncio con locución

{
  "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"
    }
  ]
}

Siguientes pasos

Inicio rápido de música

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

Retoque de música

Remezcla, amplía y une secciones de canciones existentes

Referencia de la API

Documentación completa de la API

Guía de prompting

Prácticas recomendadas para prompts de música