Plans de composition | ElevenLabs Documentation

Les plans de composition offrent un contrôle précis de la génération musicale. Un plan music_v2 ou music_v2_5 est une liste ordonnée de segments, chaque segment définissant une section du morceau avec ses propres styles, paroles et durée. Utilisez des prompts textuels pour le prototypage rapide et des plans de composition lorsque vous avez besoin d’une structure de segments spécifique, d’un minutage précis des paroles ou d’arrangements complexes.

Les plans de composition et les prompts textuels s’excluent mutuellement. Utilisez l’un ou l’autre, pas les deux.

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

Les plans de composition basés sur des segments nécessitent music_v2 ou music_v2_5. Transmettez model_id="music_v2_5" lors de la composition.

Démarrage rapide

Suivez le guide de démarrage rapide de la musique pour configurer votre clé API et installer le SDK, puis utilisez les plans de composition pour bénéficier de davantage de contrôle.

Générer de la musique avec un plan de composition

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)

Générer un plan à partir d’un prompt

Générez un plan de composition à partir d’une description textuelle, puis modifiez-le avant la génération :

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

Référence de structure

Segments

Un plan de composition est une liste ordonnée de 30 segments maximum. Chaque segment génère une section du morceau à partir de son text et de ses styles. Le premier segment est le plus important : ses styles définissent le ton et le genre généraux de tout le morceau.

Champ	Type	Description
`text`	chaîne	Nom de section entre crochets (`[Verse 1]`), lignes de paroles et indications intégrées entre accolades (`{scratching}`).
`duration_ms`	nombre	Durée en millisecondes (3 000 - 120 000).
`positive_styles`	tableau	Styles et indications à inclure (50 maximum).
`negative_styles`	tableau	Styles et indications à éviter (50 maximum). Vide par défaut.
`context_adherence`	chaîne	`low`, `medium` ou `high` (par défaut). Indique à quel point le segment suit les segments environnants.

Un morceau peut comporter jusqu’à 30 segments. Sa durée totale doit être comprise entre 3 secondes et 10 minutes, chaque segment durant entre 3 et 120 secondes.

Les styles du premier segment sont les plus importants, car ils définissent le ton et le genre généraux. Visez au moins 6 à 7 styles dans les premiers segments, jusqu’à ce que la direction soit établie. Des styles génériques tels que « great production quality » sont de bons paramètres par défaut à ajouter à la liste.

Les segments peuvent également référencer l’audio d’un morceau stocké pour conserver des sections existantes inchangées ou conditionner de nouveaux fichiers audio à partir de celles-ci. Consultez l’inpainting musical pour modifier et combiner des morceaux existants.

Écrire des paroles

Le champ text combine le nom de la section, les paroles et les indications intégrées :

Nom de section entre crochets : [Verse 1], [Chorus], [Bridge]
Paroles en texte brut, chaque ligne étant séparée par un saut de ligne (\n)
Sons phonétiques entre parenthèses : (hmmm hmmm), (ooh), (yeah)
Indications intégrées entre accolades : {guitar solo}, {scratching}, {instrumental break}

Utilisez les accolades pour des indications intégrées courtes. Pour des caractéristiques plus générales qui s’appliquent à l’ensemble du segment, comme le genre, l’instrumentation ou le style vocal global, utilisez plutôt positive_styles.

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

Dans l’exemple corrigé, le style vocal global passe dans positive_styles, tandis que l’indication intégrée courte reste dans text, entre accolades plutôt qu’entre parenthèses.

Conseils de style

Soyez précis dans vos descripteurs de style :

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

Utilisez largement les styles négatifs pour éviter les sons indésirables. Les styles doivent être en anglais, mais les paroles peuvent être dans n’importe quelle langue.

Si vous incluez du contenu protégé par des droits d’auteur dans les styles, l’API renvoie une erreur bad_composition_plan avec une alternative suggérée. Consultez la gestion des contenus protégés par des droits d’auteur.

Exemples

Instrumental cinématographique

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

Publicité avec voix off

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

Étapes suivantes

Démarrage rapide de la musique

Lancez-vous avec la génération musicale de base

Inpainting musical

Remixez, prolongez et assemblez des sections de morceaux existants

Guide de l’API

Documentation complète de l’API

Guide de prompting

Bonnes pratiques pour les prompts musicaux