跳转到内容
HiAPI Docs
HiAPI
在线试用 获取 API Key
中文
English 中文

Eleven Music v2.5 API

POST Base URL: https://api.hiapi.ai /v1/tasks

图片、视频和音频模型通过统一异步接口 POST /v1/tasks 调用，区别只在 input 字段（见下方 input 参数）。

模型概览

模型名称 elevenlabs/music-v2.5
类型 音频生成（text-to-music）
接口 POST /v1/tasks
价格 见 HiAPI 定价

ElevenLabs Eleven Music v2.5 文生音乐：用一句音乐描述生成 3 秒到 10 分钟的歌曲或纯音乐，也可按段落编写创作计划，逐段控制歌词、时长、风格和参考音频。

生产建议

生产环境建议
  • 生产环境建议在请求体顶层传 callback.url，让 HiAPI 在任务进入终态时主动通知你的服务，减少无效轮询。
  • GET /v1/tasks/:id 更适合本地调试、低频任务，或作为回调失败后的补偿查询。
  • callback.when 当前建议固定为 final；success 和 fail 都可能触发终态通知，你的服务端需要按 taskId 做幂等处理。

适用场景

快速出稿

只用一句音乐描述就能得到完整歌曲或纯音乐，适合广告配乐、短视频背景音乐和灵感试听。

promptmusic_length_msforce_instrumental
精确结构

用创作计划逐段安排前奏、主歌、副歌的歌词、时长与风格，适合需要严格结构的作品。

composition_planseed
参考风格

在段落里挂上参考音频，让整首歌或某一段贴近你已有的风格。

composition_plan.chunks[].audio_reference

请求参数

model string 必填

固定填 elevenlabs/music-v2.5。

示例 elevenlabs/music-v2.5
input object 必填

业务参数对象；Eleven Music v2.5 的模型专属配置都放在这里。

prompt string 可选

音乐描述，最多 4,100 个字符：写出曲风、情绪、乐器、人声、结构或歌词。prompt 与 composition_plan 必须且只能填写一项。

music_length_ms integer 可选

生成音频的时长，单位毫秒，3,000–600,000 的整数。仅在使用 prompt 时生效。

默认 60000
force_instrumental boolean 可选

设为 true 时保证生成结果没有人声。仅在使用 prompt 时生效。

默认 false
composition_plan object 可选

分段创作计划：把歌曲拆成 1–30 个段落，逐段指定文本、时长与风格，适合需要精确结构的作品。prompt 与 composition_plan 必须且只能填写一项。

chunks object[] 必填

按播放顺序排列的段落，1–30 项，总时长 3,000–600,000 毫秒。

text string 必填

这一段的文本。可以用方括号段落名开头，如 [Verse 1]，后面逐行写歌词；大括号内写演唱指示，如 {whisper}。最多 30 行，每行最多 200 个字符；纯音乐段落只写段落名即可。

duration_ms integer 必填

这一段的时长，单位毫秒，3,000–120,000 的整数。所有段落的时长之和必须在 3,000–600,000 毫秒之间。

positive_styles string[] 必填

这一段要包含的风格与音乐方向，英文效果最好。第一段的风格决定整首歌的基调，后续段落可以增加细节、推进或转向。

negative_styles string[] 可选

这一段要避免的风格与方向。留空是好的默认选择，只在需要明确排除某种风格时填写，例如 vocals。

context_adherence enum 可选

这一段与前后段落的衔接程度：low 允许更多变化和创意，high 保持与上下文一致。

可选值: lowmediumhigh
audio_reference object 可选

用一段参考音频来引导这一段的风格。

audio_url string 必填

可公开访问的音频文件地址，模型会参考它的风格来生成这一段。放在第一段上的参考会影响整首歌。

strength enum 可选

跟随参考音频的强度：low 更自由发挥，xhigh 最贴近参考。

可选值: lowmediumhighxhigh
start_ms integer 可选

参考片段在音频中的起点，单位毫秒，不小于 0。

默认 0
end_ms integer 可选

参考片段的终点，单位毫秒，必须大于 start_ms。省略时取 start_ms 之后 30,000 毫秒或音频结尾；参考片段最长 30,000 毫秒。

seed integer 可选

随机种子，0–2147483647 的整数。相同种子和参数会得到更一致的结果，但不保证完全相同。仅在使用 composition_plan 时生效。

output_format enum 可选

输出音频的编码、采样率和码率，格式为「编码_采样率_码率」。MP3 得到 MP3 文件，Opus 得到 Ogg 文件，PCM 得到 16 位 WAV 音频（下载链接扩展名可能不是 .wav）。

默认 mp3_48000_192 可选值: mp3_22050_32mp3_24000_48mp3_44100_32mp3_44100_64mp3_44100_96mp3_44100_128mp3_44100_192mp3_48000_128mp3_48000_192mp3_48000_240mp3_48000_320pcm_8000pcm_16000pcm_22050pcm_24000pcm_32000pcm_44100pcm_48000ulaw_8000alaw_8000opus_48000_32opus_48000_64opus_48000_96opus_48000_128opus_48000_192
callback object 可选

可选回调配置；设置后任务进入终态时 HiAPI 会主动通知你的服务，减少轮询。

url string 必填

传入 callback 时必填；接收任务终态通知的 HTTPS 地址。

示例 https://your-domain.com/hiapi/callback
when enum 可选

回调触发时机；当前建议固定为 final。

默认 final 可选值: final

段落文本写法

composition_plan.chunks[].text 的常用写法；段落名可选，不需要每段都用全部元素。

写法含义示例
[Section]段落名，放在文本开头的方括号内，1–100 个字符。[Intro]、[Verse 1]、[Chorus]、[Bridge]、[Outro]
歌词行段落名之后每行一句歌词，最多 30 行，每行最多 200 个字符。Neon rain on empty streets
{direction}大括号内写演唱或表演指示。{whisper}、{scratching}
仅段落名纯音乐段落只写段落名，并在 negative_styles 中加入 vocals。[Intro]

用例示例

深夜 lo-fi 纯音乐

用音乐描述生成 30 秒无人声的 lo-fi hip hop。

请求体
{
  "model": "elevenlabs/music-v2.5",
  "input": {
    "prompt": "Warm lo-fi hip hop instrumental with dusty drums, soft Rhodes piano chords, vinyl crackle, and a mellow late-night mood.",
    "music_length_ms": 30000,
    "force_instrumental": true
  }
}
两段式合成器浪潮

用创作计划先安排 10 秒纯音乐前奏，再接 20 秒带歌词的主歌，并固定随机种子。

请求体
{
  "model": "elevenlabs/music-v2.5",
  "input": {
    "composition_plan": {
      "chunks": [
        {
          "text": "[Intro]",
          "duration_ms": 10000,
          "positive_styles": [
            "synthwave",
            "analog drum machine",
            "great production quality"
          ],
          "negative_styles": [
            "vocals"
          ]
        },
        {
          "text": "[Verse 1]\nNeon rain on empty streets\nI keep walking to the beat",
          "duration_ms": 20000,
          "positive_styles": [
            "synthwave",
            "driving bass",
            "confident vocals"
          ],
          "context_adherence": "high"
        }
      ]
    },
    "seed": 42
  }
}

获取结果

  1. 提交成功后立即返回 taskId（不等待生成完成）。
  2. 生产环境优先等待 callback.url 收到终态通知；本地调试时可轮询 GET /v1/tasks/:id。
  3. status=success 后，从返回的 output 中找到 type=audio 的条目，通过 url 下载生成的音频。
  4. 如果 status=fail，按返回的错误信息修正请求，不要盲目重试同一个无效请求。

常见问题

音乐描述和创作计划有什么区别？

音乐描述用一段文字交给模型自由发挥，适合快速出稿；创作计划把歌曲拆成 1–30 段，每段单独指定歌词文本、时长、要包含或避免的风格，适合需要精确结构的作品。两种方式二选一，不能同时使用。

可以生成纯音乐吗？

可以。使用音乐描述时把 force_instrumental 设为 true 即可保证无人声；使用创作计划时在段落的 negative_styles 中加入 vocals，并在 positive_styles 中描述器乐编排。

时长如何控制？

使用音乐描述时用 music_length_ms 指定 3,000–600,000 毫秒，省略时按 60,000 毫秒（1 分钟）生成；使用创作计划时总时长等于所有段落 duration_ms 之和，同样需要在 3,000–600,000 毫秒之间。

如何用参考音频引导风格？

在创作计划的段落里填写 audio_reference，提供一个可公开访问的音频 URL，并可用 start_ms、end_ms 选择最长 30 秒的片段、用 strength 控制跟随强度。第一段的参考会影响整首歌。

支持哪些输出格式？

默认输出 mp3_48000_192。MP3 格式得到 MP3 文件；Opus 格式得到 Ogg 文件；PCM 格式得到 16 位 WAV 音频，下载链接的扩展名可能不是 .wav，请按 WAV 保存；μ-law 与 A-law 为 8 kHz 电话语音编码。格式名为「编码_采样率_码率」，完整列表见 output_format 参数。

怎么计费？

按生成音频的分钟数计费，不足一分钟按一分钟计算；音频时长由 music_length_ms 或各段落 duration_ms 之和决定。实时价格以价格页为准。 查看价格页

下一步