music

Files (4)

• SKILL.md
• api_reference.md · references/
• generated_music.md · references/
• installation.md · references/

SKILL.md (first lines)

# ElevenLabs Music Generation

Generate music from text prompts - supports instrumental tracks, songs with lyrics, and fine-grained control via composition plans.

> **Setup:** See [Installation Guide](references/installation.md). For JavaScript, use `@elevenlabs/*` packages only.

All examples below default to `music_v2`, the current generation model. Pass `model_id="music_v1"` only when explicitly requested to.

## Workspace BGM Workflow

For video background music in this workspace:

1. Read [Generated Music Registry](references/generated_music.md) before calling the API. Search by use case, mood, BPM, tags, and prompt. Audition and reuse a suitable recorded audio file when available. Reusing a prompt alone still triggers a paid generation; reuse its linked audio file to avoid spending credits.
2. Generate only when the registry has no suitable track. Keep new BGM requests at or below 30 seconds unless the user explicitly requests otherwise. Prefer 10–20 seconds for reusable loops.
3. For narration BGM, use `force_instrumental=true` and prompt for stable density, restrained melody, no intro or ending, no fade, no build or breakdown, and an ending that connects to the beginning. Specify BPM and a whole-bar duration when practical.
4. Preserve the exact API response as an immutable `*-raw.*` file. Never overwrite, trim, normalize, or re-encode it. Create loop masters, mix versions, and previews as separate derived files. Prefer a lossless 48 kHz WAV loop master.
5. Fix an otherwise suitable seam locally with a short circular crossfade instead of paying for another generation. Make a repeated preview to verify the seam before approving the loop.
6. After every successful generation, append an entry to [Generated Music Registry](references/generated_music.md) before handoff. Record the exact prompt verbatim, date, project/use case, model, request duration, output format, instrumental setting, raw and derived file paths, measured durations, SHA-256 hashes, tags, approval status, and processing notes. Use workspace-relative paths and never record API keys.

## Quick Start

### Python

```python
from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.music.compose(
    prompt="A chill lo-fi hip hop beat with jazzy piano chords",
    music_length_ms=30000,
    model_id="music_v2",
)

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

### TypeScript

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createWriteStream } from "fs";

const client = new ElevenLabsClient();
const audio = await client.music.compose({
  prompt: "A chill lo-fi hip hop beat with jazzy piano chords",
  musicLengthMs: 30000,
  modelId: "music_v2",
});
audio.pipe(createWriteStream("output.mp3"));
```

### cURL

```bash
curl -X POST "https://api.elevenlabs.io/v1/music" \
  -H "xi-api-key: $ELEVENLABS_API_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "A chill lo-fi beat", "music_length_ms": 30000, "model_id": "music_v2"}' \
  --output output.mp3
```

## Methods

| Method | Description |
|--------|-------------|
| `music.compose` | Generate audio from a prompt or composition plan |
| `music.stream` | Stream audio chunks as they are generated (paid plans) |
| `music.composition_plan.create` | Generate a structured plan for fine-grained control |
| `music.compose_detailed` | Generate audio + composition plan + metadata; pass `store_for_inpainting=True` to enable inpainting |
| `music.compose_detailed_stream` | Stream audio plus composition plan, metadata, and optional word timestamps as Server-Sent Events |
| `music.video_to_music` | Generate background music from one or more uploaded video files |
| `music.upload` | Upload an audio file for later inpainting workflows, optionally extracting its composition plan or word-level timestamps |

See [API Reference](references/api_reference.md) for full parameter details.

`music.upload` is available to enterprise clients with access to the inpainting feature.

## Video to Music

Generate background music from uploaded video clips via
[`POST /v1/music/video-to-music`](https://elevenlabs.io/docs/api-reference/music/video-to-music)
(`client.music.video_to_music`). This is separate from prompt-based
[`music.compose`](https://elevenlabs.io/docs/api-reference/music/compose) (`POST /v1/music`).

The API combines videos in order, accepts an optional natural-language description, and lets you
steer style with up to 10 tags such as `upbeat` or `cinematic`. This endpoint still defaults to
`music_v1`; pass `model_id="music_v2"` to use the newer model.

### Python

```python
from elevenlabs import ElevenLabs

client = ElevenLabs()

audio = client.music.video_to_music(
    videos=["trailer.mp4"],
    description="Build suspense, then resolve with a warm cinematic finish.",
    tags=["cinematic", "suspenseful", "uplifting"],
    model_id="music_v2",
)

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

### TypeScript

```typescript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream, createWriteStream } from "fs";

const client = new ElevenLabsClient();

const audio = await client.music.videoToMusic({
  videos: [createReadStream("trailer.mp4")],

From bozhouDev/video-skills-toolkit, MIT.

More from bozhouDev/video-skills-toolkit