music

ElevenLabs 音乐生成

根据文本提示生成音乐——支持纯音乐、带歌词的歌曲，以及通过编曲计划进行精细控制。

**开始编写代码前先完成设置：**如果尚未为此项目设置 ELEVENLABS_API_KEY，请先在应用文件夹中运行 npx -y @elevenlabs/cli@latest onboard init，并按提示操作：该命令会为用户登录并为项目保存密钥，因此无需手动复制密钥。否则，请参阅安装指南。对于 JavaScript，只使用 @elevenlabs/* packages。

以下示例均使用最先进的生成模型 music_v2_5。只有在明确要求使用旧版模型时，才传入 music_v2 或 music_v1。

快速入门

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

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

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_5",
});
audio.pipe(createWriteStream("output.mp3"));

CLI

elevenlabs music compose \
  --prompt "A chill lo-fi beat" \
  --music-length-ms 30000 \
  --model-id music_v2_5 \
  --output output.mp3

方法

方法	说明
music.compose	根据提示或编曲计划生成音频
music.stream	在生成音频片段时实时串流（付费计划）
music.composition_plan.create	生成结构化计划，实现精细控制
music.compose_detailed	生成音频、编曲计划和元数据；传入 store_for_inpainting=True 以启用局部重绘
music.compose_detailed_stream	以 Server-Sent Events 的形式串流音频、编曲计划、元数据，以及可选的词级时间戳
music.video_to_music	根据一个或多个上传的视频文件生成背景音乐
music.upload	上传音频文件，以供后续局部重绘工作流使用；还可选择提取其编曲计划或词级时间戳
music.finetunes.list	列出可访问的音乐微调模型
music.finetunes.create	使用上传的音频训练音乐微调模型
music.finetunes.get	获取微调模型状态和元数据
music.finetunes.update	更新微调模型的元数据或可见性
music.finetunes.delete	删除音乐微调模型

完整参数详情请参阅 API 参考。

music.upload 面向可使用局部重绘功能的企业客户端开放。

音乐微调模型

使用训练音频创建微调模型： POST /v1/music/finetunes， 然后轮询get endpoint，直到 其状态变为 completed。编曲时，将返回的 id 作为 finetune_id 传入。

使用 list、 update 和 delete 端点管理 可访问的微调模型。

视频转音乐

通过 POST /v1/music/video-to-music （client.music.video_to_music）根据上传的视频片段生成背景音乐。这与基于提示的 music.compose（POST /v1/music）是两个独立功能。

API 会按顺序合并视频，接受可选的自然语言描述，并支持使用最多 10 个标签（例如 upbeat 或 cinematic）来引导音乐风格。此端点仍默认使用 music_v1；传入 model_id="music_v2_5" 即可使用最先进的模型。

三个可选标志可调整生成结果：use_audio_as_reference 会从视频自带音频中提取流派、BPM、乐器配置和情绪；add_sfx 会添加与视频匹配的音效；separate_tracks 则会返回一个 ZIP 文件，其中音乐和音效分为独立文件，便于混音。

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

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

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")],
  description: "Build suspense, then resolve with a warm cinematic finish.",
  tags: ["cinematic", "suspenseful", "uplifting"],
  modelId: "music_v2_5",
});

audio.pipe(createWriteStream("video-score.mp3"));

CLI

elevenlabs music video_to_music \
  --videos trailer.mp4 \
  --description "Build suspense, then resolve with a warm cinematic finish." \
  --tags cinematic \
  --model-id music_v2_5 \
  --output video-score.mp3

CLI 目前每个请求仅接受一个 --videos 文件和一个 --tags 值；如需发送多个视频或标签，请使用 Python 或 TypeScript SDK。

当前 API 架构的限制：

• 每个请求上传 1-10 个视频文件
• 总上传大小不超过 200 MB
• 视频总时长不超过 600 秒
• 使用 description 描述整体音乐方向，使用 tags 提供简洁的风格提示

Composition Plans

music_v2_5 组合计划是一个有序的 chunks 列表。每个 chunk 都包含自己的 text（段落标签、歌词、行内提示）、duration_ms、positive_styles、negative_styles 和 context_adherence（low、medium 或 high，默认为 high）。每个计划最多包含 30 个 chunk，每个 chunk 时长为 3,000–120,000 ms，总时长为 3 秒至 10 分钟。每个 chunk 的 text 最多支持 6,132 个字符，最多 30 行，每行 200 个字符。

先生成计划，再编辑，然后进行创作：

plan = client.music.composition_plan.create(
    prompt="An epic orchestral piece building to a climax",
    music_length_ms=60000,
    model_id="music_v2_5",
)

# Edit chunks in place
plan["chunks"][0]["text"] = "[Intro]\nQuiet strings rising"

audio = client.music.compose(
    composition_plan=plan,
    model_id="music_v2_5",
)

const plan = await client.music.compositionPlan.create({
  prompt: "An epic orchestral piece building to a climax",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
});

plan.chunks[0].text = "[Intro]\nQuiet strings rising";

const audio = await client.music.compose({
  compositionPlan: plan,
  modelId: "music_v2_5",
});

也可以手动构建计划，以控制每个段落的歌词和风格：

composition_plan = {
    "chunks": [
        {
            "text": "[Verse]\nWalking down an empty street",
            "duration_ms": 15000,
            "positive_styles": ["pop", "upbeat", "female vocals", "acoustic guitar"],
            "negative_styles": ["dark", "slow"],
            "context_adherence": "high",
        },
        {
            "text": "[Chorus]\nThis is my moment",
            "duration_ms": 15000,
            "positive_styles": ["powerful vocals", "full band"],
            "negative_styles": [],
            "context_adherence": "high",
        },
    ]
}

audio = client.music.compose(composition_plan=composition_plan, model_id="music_v2_5")

const compositionPlan = {
  chunks: [
    {
      text: "[Verse]\nWalking down an empty street",
      durationMs: 15000,
      positiveStyles: ["pop", "upbeat", "female vocals", "acoustic guitar"],
      negativeStyles: ["dark", "slow"],
      contextAdherence: "high",
    },
    {
      text: "[Chorus]\nThis is my moment",
      durationMs: 15000,
      positiveStyles: ["powerful vocals", "full band"],
      negativeStyles: [],
      contextAdherence: "high",
    },
  ],
};

const audio = await client.music.compose({
  compositionPlan,
  modelId: "music_v2_5",
});

将更广泛的特征（流派、乐器、人声风格）放入 positive_styles，而不是 text。第一个 chunk 的风格决定整体基调，请在其中加入 6–7 种风格。

输出格式

在 compose、detailed compose 或 stream 请求中使用 output_format 查询参数，选择生成的音频格式。auto 会选择适合模型的 MP3 格式；对于 music_v2 和 music_v2_5，会选择 mp3_48000_192。更高比特率的 MP3 选项包括 mp3_48000_240 和 mp3_48000_320。

流式传输

付费套餐可在音频分块生成时进行流式传输，而无需等待完整文件：

from io import BytesIO

stream = client.music.stream(
    prompt="A driving synthwave track with arpeggiated leads",
    music_length_ms=30000,
    model_id="music_v2_5",
)

buffer = BytesIO()
for chunk in stream:
    if chunk:
        buffer.write(chunk)

const stream = await client.music.stream({
  prompt: "A driving synthwave track with arpeggiated leads",
  musicLengthMs: 30000,
  modelId: "music_v2_5",
});

const chunks: Buffer[] = [];
for await (const chunk of stream) {
  chunks.push(chunk);
}

详细流式传输

当应用需要在音频仍在传输时获取生成的音乐元数据，请使用详细流式传输。POST /v1/music/detailed/stream 接受与 detailed compose 相同的提示词或组合计划请求体，以 text/event-stream 格式进行流式传输，并可通过 with_timestamps 包含词语时间戳。

elevenlabs music compose_detailed_stream \
  --prompt "A bright indie pop hook with warm guitars" \
  --music-length-ms 30000 \
  --model-id music_v2_5 \
  --with-timestamps true \
  --output-format auto

修补

修补通过在单个组合计划中混合音频参考分块（存储歌曲中保持不变的片段）与新的生成分块，来编辑或延长已存储的歌曲。

步骤 1 — 获取 song_id，可以存储新生成的歌曲，也可以上传现有音频：

# Option A: keep a generation for later editing
result = client.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 = result.song_id

# Option B: upload an existing track and extract its plan
uploaded = client.music.upload(
    file=open("my-song.mp3", "rb"),
    extract_composition_plan="music_v2_5",
)
song_id = uploaded.song_id
composition_plan = uploaded.composition_plan

import { createReadStream } from "fs";

// Option A: keep a generation for later editing
const result = await client.music.composeDetailed({
  prompt: "An upbeat pop song with verse and chorus",
  musicLengthMs: 60000,
  modelId: "music_v2_5",
  storeForInpainting: true,
});
let songId = result.songId;

// Option B: upload an existing track and extract its plan
const uploaded = await client.music.upload({
  file: createReadStream("my-song.mp3"),
  extractCompositionPlan: "music_v2_5",
});
songId = uploaded.songId;
const compositionPlan = uploaded.compositionPlan;

步骤 2 — 编写引用已存储音频的计划，并重新生成你想要更改的部分：

plan = {
    "chunks": [
        {"song_id": song_id, "range": {"start_ms": 0, "end_ms": 30000}},
        {
            "text": "[Chorus]\nWe're rising up tonight",
            "duration_ms": 30000,
            "positive_styles": ["bigger drums", "layered vocals", "anthemic"],
            "negative_styles": ["sparse"],
            "context_adherence": "high",
        },
    ]
}

audio = client.music.compose(composition_plan=plan, model_id="music_v2_5")

const plan = {
  chunks: [
    { songId, range: { startMs: 0, endMs: 30000 } },
    {
      text: "[Chorus]\nWe're rising up tonight",
      durationMs: 30000,
      positiveStyles: ["bigger drums", "layered vocals", "anthemic"],
      negativeStyles: ["sparse"],
      contextAdherence: "high",
    },
  ],
};

const audio = await client.music.compose({
  compositionPlan: plan,
  modelId: "music_v2_5",
});

如需贴近已存储片段的感觉而不直接复制，可为生成分块附加一个 conditioning_ref（最长 30,000 ms）以及一个 condition_strength，其值可为 low、medium、high 或 xhigh。在第一个 chunk 上设置的条件会影响后续所有 chunk。

完整的修补参数列表请参阅 API 参考。

内容限制

• 不能引用特定艺人、乐队或受版权保护的歌词
• bad_prompt 错误会包含 prompt_suggestion，提供替代表述
• bad_composition_plan 错误会包含 composition_plan_suggestion

错误处理

try:
    audio = client.music.compose(prompt="...", music_length_ms=30000)
except Exception as e:
    print(f"API error: {e}")

try {
  const audio = await client.music.compose({
    prompt: "...",
    musicLengthMs: 30000,
  });
} catch (err) {
  console.error("API error:", err);
}

常见错误：401（密钥无效）、422（参数无效）、429（速率限制）。

参考资料

• 安装指南
• API 参考