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

# Musik-Inpainting

Mit Musik-Inpainting und dem Modell `music_v2` oder `music_v2_5` können Sie bestimmte Teile eines Songs ändern und den Rest unverändert lassen. Speichern Sie einen generierten Song und verweisen Sie dann in einem Kompositionsplan auf seine Teile, um sie unverändert zu lassen, neu zu generieren oder neues Audio auf das Original zu konditionieren.

## So funktioniert es

Ein `music_v2`- oder `music_v2_5`-Kompositionsplan ist eine geordnete Liste von **Chunks**. Jeder Chunk gehört zu einem von zwei Typen:

* **Generierungs-Chunk** — generiert neues Audio aus `text` und Stilen. Verwenden Sie ihn, um einen Abschnitt neu zu generieren oder neues Material hinzuzufügen.
* **Audio-Referenz-Chunk** — fügt einen Ausschnitt eines gespeicherten Songs unverändert ein. Verwenden Sie ihn, um einen Abschnitt eines bestehenden Songs exakt unverändert zu lassen.

## Schnellstart

### Einen Song für Inpainting speichern

Sie können einen Song auf zwei Arten für Inpainting speichern: Generieren Sie einen neuen Song mit `store_for_inpainting` oder laden Sie eine bestehende Audiodatei hoch.

#### Generieren und speichern

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

#### Bestehende Datei hochladen

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

### Chunks beibehalten und neu generieren

Erstellen Sie einen Plan, der Audio-Referenz-Chunks (beibehalten) mit Generierungs-Chunks (neu generiert) kombiniert, und übergeben Sie ihn dann mit `model_id="music_v2_5"` an `compose`:

```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",
});
```

## Konditionierung

Ein Generierungs-Chunk kann mit `conditioning_ref` auf einem Ausschnitt gespeicherten Audios konditioniert werden. Das Modell generiert den Chunk neu und bleibt dabei nahe an den musikalischen Merkmalen der Referenz. Steuern Sie mit `condition_strength` (`low`, `medium`, `high` oder `xhigh`), wie eng der Chunk der Referenz folgt.

```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**
>
> Der erste Chunk beeinflusst die Generierung aller nachfolgenden Chunks. Um den gesamten Song auf eine Referenz zu konditionieren,
> wenden Sie `conditioning_ref` ab dem ersten Chunk an.

Eine Konditionierungsreferenz darf höchstens 30 Sekunden (30.000 ms) lang sein.

## Kontexttreue

Jeder Generierungs-Chunk hat eine Stufe für `context_adherence`, die steuert, wie eng er seinen benachbarten Chunks folgt:

* `high` (Standard) — bleibt mit den umgebenden Chunks konsistent. Verwenden Sie dies für fließende Übergänge zwischen beibehaltenem und neu generiertem Audio.
* `medium` — schafft ein Gleichgewicht zwischen Konsistenz und kreativer Freiheit.
* `low` — ermöglicht dem Chunk, von seinem Kontext abzuweichen und kreativer zu sein.

## Beispiele

### Einen einzelnen Abschnitt bearbeiten

Erstellen Sie einen Filmtrailer und generieren Sie dann nur das Outro mit einem anderen Songtext neu.

### Das Original erstellen

```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="Original Movie Trailer" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/movie_trailer.mp3" />

### Nur das Outro bearbeiten

Behalten Sie die ersten drei Abschnitte (Sekunden 0–50) mit einem einzelnen Audio-Referenz-Chunk bei und generieren Sie das Outro neu:

```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="Edited Outro" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/movie_trailer_edited.mp3" />

### Einen Song verlängern

Fügen Sie einem vorhandenen Song ein neues Intro und Outro hinzu.

### Das Original erstellen

```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 (60s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/berlin_night_club_techno.mp3" />

### Mit neuem Intro und Outro verlängern

Fügen Sie einen beibehaltenen Ausschnitt des Originals zwischen zwei neue Generierungs-Chunks ein:

```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="Extended (100s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/berlin_night_club_techno_extended.mp3" />

### Eine nahtlose Schleife erstellen

Generieren Sie eine musikalische Phrase und erstellen Sie eine Schleife mit einem „Glue“-Chunk, der denselben zweimal wiederholten Ausschnitt verbindet.

### Einen kurzen Clip generieren

```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 (10s)" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/acoustic_guitar.mp3" />

### Eine Schleife mit einem Glue-Chunk erstellen

```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="Seamless Loop" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/acoustic_guitar_looped.mp3" />

### Einen ähnlichen Song generieren

Konditionieren Sie einen völlig neuen Song mit einem kurzen Ausschnitt eines vorhandenen Songs, um dessen musikalische Merkmale zu übernehmen. Da der erste Chunk alle folgenden Chunks beeinflusst, prägt `conditioning_ref` im ersten Chunk die gesamte Generierung, obwohl nur dieser Chunk auf das gespeicherte Audio verweist.

### Das Original erstellen

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

### Einen neuen Song erstellen, der auf dem Original basiert

```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="Conditioned New Song" audio-src="https://storage.googleapis.com/eleven-public-cdn/documentation_assets/audio/conditioning-new.mp3" />

## Chunk-Referenz

Ein `music_v2`-Plan enthält bis zu 30 Chunks. Jeder Chunk ist entweder ein Generierungs-Chunk oder ein Audio-Referenz-Chunk.

### Generierungs-Chunk

| Feld                 | Typ            | Beschreibung                                                                                                                       |
| -------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `text`               | string         | Abschnittsname in eckigen Klammern (`[Verse 1]`), Songtextzeilen und Inline-Anweisungen in geschweiften Klammern (`{scratching}`). |
| `duration_ms`        | number         | Länge in Millisekunden (3.000–120.000).                                                                                            |
| `positive_styles`    | array          | Einzuschließende Stile und Anweisungen (max. 50).                                                                                  |
| `negative_styles`    | array          | Zu vermeidende Stile und Anweisungen (max. 50). Standardmäßig leer.                                                                |
| `context_adherence`  | string         | `low`, `medium` oder `high` (Standard). Legt fest, wie eng der Chunk seinen umgebenden Chunks folgt.                               |
| `conditioning_ref`   | object \| null | Optionaler `{ song_id, range }`-Ausschnitt gespeicherten Audios zur Konditionierung. Standardmäßig `null`.                         |
| `condition_strength` | string \| null | `low`, `medium` (Standard), `high` oder `xhigh`. Legt fest, wie stark der Chunk der Konditionierungsreferenz folgt.                |

> **Tip**
>
> Die Stile des ersten Chunks sind am wichtigsten, da sie den Gesamtton und das Genre festlegen. Verwenden Sie
> in frühen Chunks mindestens 6–7 Stile, bis die Richtung feststeht.

### Audio-Referenz-Chunk

| Feld      | Typ    | Beschreibung                                                                               |
| --------- | ------ | ------------------------------------------------------------------------------------------ |
| `song_id` | string | ID des gespeicherten Songs, aus dem Audio verwendet wird.                                  |
| `range`   | object | `{ start_ms, end_ms }`-Ausschnitt des gespeicherten Songs, der unverändert eingefügt wird. |

## Einschränkungen

| Einschränkung                     | Wert                    |
| --------------------------------- | ----------------------- |
| Maximale Chunks pro Plan          | 30                      |
| Mindestdauer eines Chunks         | 3 Sekunden (3.000 ms)   |
| Maximale Dauer eines Chunks       | 2 Minuten (120.000 ms)  |
| Maximale Konditionierungsreferenz | 30 Sekunden (30.000 ms) |
| Minimaler Zeitbereich             | 50 ms                   |

## Nächste Schritte

#### [Kompositionspläne](/docs/de/eleven-api/guides/how-to/music/composition-plans)

Grundlagen zu Kompositionsplänen

#### [API-Referenz](/docs/de/api-reference/music/compose)

Vollständige API-Dokumentation