教程

音乐快速入门

了解如何使用 Music API 生成音乐。

本指南将介绍如何使用 Music API 生成音乐。

使用 ElevenLabs music skill，通过 AI 编程助手生成音乐曲目：

npx skills add elevenlabs/skills --skill music
Music API 仅面向付费用户开放。

使用 Music API

1

创建 API 密钥

在控制台创建 API 密钥，用于安全地访问 API。

将密钥存储为托管密钥，并根据需要通过 .env 文件将其作为环境变量传递给 SDK，或直接在应用配置中设置。

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

安装 SDK

我们还会使用 dotenv 库从环境变量加载 API 密钥。

pip install elevenlabs
pip install python-dotenv
3

发起 API 请求

根据所选语言，新建名为 example.py 或 example.mts 的文件，并添加以下代码：

# example.py
from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
import os
from dotenv import load_dotenv
load_dotenv()
elevenlabs = ElevenLabs(
    api_key=os.getenv("ELEVENLABS_API_KEY"),
)
track = elevenlabs.music.compose(
    prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    music_length_ms=10000,
    model_id="music_v2_5",
)
# Save the track to a file
with open("path/to/music.mp3", "wb") as f:
    for chunk in track:
        f.write(chunk)

然后运行：

python example.py

你应该会听到生成的音乐开始播放。

编曲计划

编曲计划是一个 JSON 对象，用于更细致地描述想要生成的音乐。快速原型设计可使用文本提示词；如需特定分块结构、精确的歌词时间安排或复杂编排，请使用编曲计划。

编曲计划指南

了解如何通过分块、风格和歌词构建歌曲，实现精确控制。

生成编曲计划

可通过 API 根据提示词生成编曲计划。

from elevenlabs.client import ElevenLabs
from elevenlabs.play import play
import os
from dotenv import load_dotenv
load_dotenv()
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
composition_plan = elevenlabs.music.composition_plan.create(
    prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    music_length_ms=10000,
    model_id="music_v2_5",
)
print(composition_plan)

以上代码会生成类似如下的编曲计划：

{
  "chunks": [
    {
      "text": "[Intro]",
      "durationMs": 3000,
      "positiveStyles": [
        "electronic",
        "fast-paced",
        "rising synth arpeggio",
        "glitch fx",
        "filtered noise sweep",
        "soft punchy kick building tension",
        "high adrenaline"
      ],
      "negativeStyles": ["soft pads", "melodic vocals", "ambient textures"],
      "contextAdherence": "high"
    },
    {
      "text": "[Peak Drop]",
      "durationMs": 4000,
      "positiveStyles": [
        "full punchy drums",
        "distorted bass stab",
        "aggressive rhythmic hits",
        "rapid arpeggio sequences"
      ],
      "negativeStyles": ["smooth transitions", "clean bass", "slow buildup"],
      "contextAdherence": "high"
    },
    {
      "text": "[Final Burst]",
      "durationMs": 3000,
      "positiveStyles": [
        "glitch stutter",
        "energy burst vox chopped sample",
        "quick transitions",
        "snare rolls"
      ],
      "negativeStyles": ["long reverb tails", "fadeout", "gentle melodies"],
      "contextAdherence": "high"
    }
  ]
}

使用编曲计划

将编曲计划传递给 compose 方法即可生成音乐。

# You can pass in composition_plan or prompt, but not both.
composition = elevenlabs.music.compose(
    composition_plan=composition_plan,
    model_id="music_v2_5",
)
play(composition)

生成包含详细信息的音乐

每次生成音乐时，都会根据提示词创建一个编曲计划。你可以通过详细响应端点获取此计划。

track_details = elevenlabs.music.compose_detailed(
    prompt="Create an intense, fast-paced electronic track for a high-adrenaline video game scene. Use driving synth arpeggios, punchy drums, distorted bass, glitch effects, and aggressive rhythmic textures. The tempo should be fast, 130–150 bpm, with rising tension, quick transitions, and dynamic energy bursts.",
    music_length_ms=10000,
    model_id="music_v2_5",
)
print(track_details.json) # json contains composition_plan and song_metadata. The composition plan will include lyrics (if applicable)
print(track_details.filename)
# track_details.audio contains the audio bytes

受版权保护的材料

尝试生成包含受版权保护材料的音乐或编曲计划会导致出错。这包括提及乐队或音乐家的姓名，或使用受版权保护的歌词。

包含受版权保护材料的提示词

在这些情况下，API 会返回 bad_prompt 错误，其中会建议可改用的提示词。

try:
    # This will result in a bad_prompt error
    track = elevenlabs.music.compose(
        prompt="A song that sounds like 'Bohemian Rhapsody'",
        music_length_ms=10000,
        model_id="music_v2_5",
    )
  except Exception as e:
      if e.body['detail']['status'] == 'bad_prompt':
          prompt_suggestion = e.body['detail']['data']['prompt_suggestion']
          print(prompt_suggestion) # Prints: An epic rock ballad with dramatic tempo changes, operatic harmonies, and a narrative structure that blends melancholy with bursts of theatrical intensity.
          # Use the prompt suggestion to generate the track instead

包含受版权保护材料的编曲计划

如果在生成编曲计划时使用了涉及受版权保护材料的风格，将返回 bad_composition_plan 错误。与音乐提示词类似，错误中会返回建议的编曲计划 composition_plan_suggestion。

如果编曲计划或提示词包含有害材料，不会返回建议的提示词。

后续步骤

流式传输音乐

实时流式传输生成的音乐，无需等待完整文件

音乐局部重绘

修改或扩展现有音乐曲目的特定部分

API 参考文档

查看所有 Music API 参数和响应格式