Compositieplannen | ElevenLabs Documentation

Compositieplannen bieden gedetailleerde controle over muziekgeneratie. Een music_v2- of music_v2_5-plan is een geordende lijst met chunks, waarbij elke chunk een sectie van het nummer definieert met eigen stijlen, songtekst en duur. Gebruik tekstprompts voor snelle prototyping en compositieplannen wanneer je een specifieke chunkstructuur, nauwkeurige timing van songteksten of complexe arrangementen nodig hebt.

Compositieplannen en tekstprompts sluiten elkaar uit. Gebruik het een of het ander, niet beide.

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

Compositieplannen op basis van chunks vereisen music_v2 of music_v2_5. Geef bij het componeren model_id="music_v2_5" door.

Quickstart

Volg de quickstart voor muziek om je API-sleutel in te stellen en de SDK te installeren, en gebruik vervolgens compositieplannen voor meer controle.

Muziek genereren met een compositieplan

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)

Een plan genereren vanuit een prompt

Genereer een compositieplan op basis van een tekstbeschrijving en pas het aan voordat je genereert:

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

Structuurreferentie

Chunks

Een compositieplan is een geordende lijst met maximaal 30 chunks. Elke chunk genereert één sectie van het nummer vanuit de bijbehorende text en stijlen. De eerste chunk is het belangrijkst: de stijlen bepalen de algemene sfeer en het genre voor het hele nummer.

Veld	Type	Beschrijving
`text`	string	Sectienaam tussen vierkante haken (`[Verse 1]`), regels met songtekst en inline-instructies tussen accolades (`{scratching}`).
`duration_ms`	number	Lengte in milliseconden (3.000 - 120.000).
`positive_styles`	array	Stijlen en instructies om op te nemen (max. 50).
`negative_styles`	array	Stijlen en instructies om te vermijden (max. 50). Standaard leeg.
`context_adherence`	string	`low`, `medium` of `high` (standaard). Hoe nauw de chunk de omringende chunks volgt.

Een nummer kan maximaal 30 chunks hebben. De totale duur moet tussen 3 seconden en 10 minuten liggen, met elke chunk tussen 3 en 120 seconden.

De stijlen voor de eerste chunk zijn het belangrijkst, omdat ze de algemene sfeer en het genre bepalen. Streef naar minstens 6-7 stijlen in vroege chunks totdat de richting is vastgesteld. Algemene stijlen zoals “great production quality” zijn goede standaardwaarden om aan de lijst toe te voegen.

Chunks kunnen ook verwijzen naar audio van een opgeslagen nummer om bestaande secties ongewijzigd te houden of nieuwe audio daarop te baseren. Zie muziek-inpainting voor het bewerken en combineren van bestaande nummers.

Songteksten schrijven

Het veld text combineert de sectienaam, songtekst en inline-instructies:

Sectienaam tussen vierkante haken: [Verse 1], [Chorus], [Bridge]
Songtekst als platte tekst, met elke regel gescheiden door een regeleinde (\n)
Fonetische klanken tussen haakjes: (hmmm hmmm), (ooh), (yeah)
Inline-instructies tussen accolades: {guitar solo}, {scratching}, {instrumental break}

Gebruik accolades voor korte, inline aanwijzingen. Gebruik voor bredere kenmerken die gelden voor de hele chunk — genre, instrumentatie of algemene zangstijl — in plaats daarvan positive_styles.

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

In het gecorrigeerde voorbeeld wordt de algemene zangstijl verplaatst naar positive_styles, terwijl de korte inline-aanwijzing in text blijft met accolades in plaats van haakjes.

Stijltips

Wees specifiek met stijlbeschrijvingen:

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

Gebruik negatieve stijlen ruimhartig om ongewenste geluiden te voorkomen. Stijlen moeten in het Engels zijn (songteksten mogen in elke taal zijn).

Als je auteursrechtelijk beschermde content in stijlen opneemt, retourneert de API een fout bad_composition_plan met een voorgesteld alternatief. Zie omgaan met auteursrechtelijk beschermd materiaal.

Voorbeelden

Cinematisch instrumentaal

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

Advertentie met voice-over

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

Volgende stappen

Quickstart voor muziek

Ga aan de slag met eenvoudige muziekgeneratie

Muziek-inpainting

Remix, verleng en voeg secties van bestaande nummers samen

API-referentie

Volledige API-documentatie

Promptinggids

Best practices voor muziekprompts