教程

HiAPI 上的 ElevenLabs Music API：使用 curl、Python 和提示词配方生成音乐

一份通过 HiAPI 调用 elevenlabs/music-v2.5 的实操教程，以及用于风格、情绪和时长的可复制提示词配方

2026年11月12日

本页内容

为什么通过 HiAPI 调用 elevenlabs/music-v2.5

如果你要为产品添加音乐生成功能，最快的路径往往不是最干净的路径。将后端直接接入模型提供商，意味着你要自己负责该提供商的账户设置、认证方案、重试语义和请求结构。每采用一个新模型，就会多出一组这类决策，每次实验都会留下一个集成分支。

通过 HiAPI 调用 elevenlabs/music-v2.5 会改变这项工作的形态。你只需一个基础 URL、一个认证请求头，以及一套在模型之间切换时保持稳定的请求约定。模型标识符（elevenlabs/music-v2.5）只是请求体中的一个字符串，因此在音乐模型之间切换，或尝试第二个模型进行对比，只需改一行，而不必导入新的 SDK。

对选择集成方式的开发者来说，有三个实际好处值得关注：

统一的凭据管理面。 密钥管理、轮换和环境隔离（开发/预发/生产）集中在一处，而不是按提供商成倍增加。
可移植的请求模式。 下面的 curl 和 Python 代码片段与你在 HiAPI 上使用其他模型时的一致。学习一次模式就够了。
用量集中在一处。 音乐生成按输出时长计费，将它与其他模型用量放在一起，意味着在单一仪表盘中跟踪成本，而不是面对散落各处的账单。

代价是你要经过一层抽象，因此提供商特有的怪癖会被规范化。对于首次集成和大多数生产用例来说，这种规范化正是你想要的。当你需要理解模型的具体行为时，网站上的详情页是权威来源。

首次音乐请求前的准备工作

在写代码之前确认四件事，这样第一次调用返回的是音频，而不是 401 或验证错误。

1. API 密钥

你需要从 HiAPI 账户获取一个 API 密钥。像对待任何其他密钥一样对待它：保存在环境变量中，绝不要提交到源码里，并为本地开发和生产使用不同的密钥，这样你可以吊销其中一个而不影响另一个。

export HIAPI_API_KEY="your_key_here"

2. 基础 URL 和端点约定

所有模型调用都走同一个基础 URL，模型在请求内部标识，而不是在路径中。在项目中为基础 URL 保留一个常量，这样如果你的环境不同，只需改一个地方。

3. 一段用自然语言写的提示词

elevenlabs/music-v2.5 接受一段描述你想要的音乐的文本提示词。你不需要乐谱或 MIDI 文件。用一两句话说明流派、配器、情绪和预期时长，就足以开始。后续章节会给出可复用的配方。

4. 对输出有正确的预期

音乐生成返回的是音频，而不是 JSON 乐谱。要规划好如何处理响应负载：开发时写入文件，生产环境中流式传输或存储。提前决定你希望片段大概多长，因为时长既影响请求，也影响计费。

首次请求前还有一件事：在网站的定价面板查看 elevenlabs/music-v2.5 当前的速率限制和价格，而不是把假设硬编码进代码。价格和限制会变化，你的集成应把它们作为配置读取，而不是嵌入脚本的常量。

用 curl 发出第一次调用

从 curl 开始，因为它移除了你和 HTTP 请求之间的所有层级。如果 curl 调用成功，那么应用中的任何失败都是应用自身的问题，而不是 API 的问题。

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "elevenlabs/music-v2.5",
    "messages": [
      {
        "role": "user",
        "content": "Instrumental lo-fi hip hop, warm vinyl texture, mellow electric piano, soft brushed drums, 80 BPM, relaxed late-night mood, about 30 seconds."
      }
    ]
  }'

各部分的作用如下：

-sS 让进度输出保持安静，但仍然显示错误。当你把输出粘贴到文件时很有用。
URL 是统一端点。注意模型名不出现在路径中，而是出现在请求体里。
Authorization: Bearer $HIAPI_API_KEY 从环境读取密钥，这样它就不会以明文形式留在 shell 历史记录中。在 Windows 上，相应地用 set 或 PowerShell 的 $env: 语法设置变量。
Content-Type: application/json 是必需的；该端点不接受表单编码。
model 是精确的标识符 elevenlabs/music-v2.5。这里拼错会产生模型未找到错误，而不是通用失败，这对调试很有帮助。
messages 将你的提示词作为用户消息内容传递。把提示词放在一条消息里；长而结构化的提示词比分散成几条效果更好。

响应体包含生成的音频以及关于请求的元数据。开发时，将输出重定向到文件，这样你可以立即试听结果：

curl -sS https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @request.json -o response.json

将负载放入 request.json 并用 -d @request.json 读取，是应该尽早养成的习惯。它让请求可对比、可审查，并且在一次只改一个参数时容易重放。

在 Python 中重复该调用

一旦 curl 调用返回音频，就把它移植到 Python。目标不仅是一个能跑的脚本，而是一个可以从任务队列、API 处理器或笔记本中调用而不会出现复制粘贴偏差的函数。

import json
import os
import urllib.request

BASE_URL = "https://api.hiapi.ai/v1/chat/completions"
MODEL = "elevenlabs/music-v2.5"

def generate_music(prompt: str, timeout: int = 120) -> dict:
    """通过 HiAPI 向 elevenlabs/music-v2.5 发送音乐提示词。"""
    api_key = os.environ.get("HIAPI_API_KEY")
    if not api_key:
        raise RuntimeError("HIAPI_API_KEY is not set")

    payload = {
        "model": MODEL,
        "messages": [{"role": "user", "content": prompt}],
    }

    request = urllib.request.Request(
        BASE_URL,
        data=json.dumps(payload).encode("utf-8"),
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        method="POST",
    )

    with urllib.request.urlopen(request, timeout=timeout) as response:
        return json.loads(response.read().decode("utf-8"))

if __name__ == "__main__":
    result = generate_music(
        "Cinematic orchestral swell, strings and low brass, hopeful build, "
        "no percussion, about 20 seconds."
    )
    print(json.dumps(result, indent=2)[:500])

随着函数增长，有几个值得保留的决策：

优先使用标准库。 urllib 避免了教程中的依赖变动。如果你的项目已经使用 requests 或 httpx，转换是机械性的：传入 json=payload、headers=headers 和 timeout。
超时是强制性的。 音乐生成比聊天补全耗时更长。设置显式超时，不要依赖默认值。选择一个比你所请求的最长片段预期生成时间更长的值。
在调用时读取密钥，而不是在导入时，这样同一个模块在本地和运行时注入环境的容器中都能工作。
返回结构化数据，而不是打印字符串。由调用方决定是将音频写入磁盘、上传到对象存储，还是转发给客户端。

在基于它们构建任何东西之前，确认 Python 函数和 curl 调用对同一提示词产生等价的结果。这种一致性是你的回归基线。

风格、情绪和时长的提示词配方

音乐提示词在按顺序回答三个问题时效果最好：什么流派和配器、什么情感基调、多长。模糊的提示词产生通用输出；过长的提示词会稀释重要的描述词。目标是一句密集的句子，或三个短分句。

将这些作为可复制粘贴的起点，并一次只调整一个维度。

风格主导的配方

Solo piano, felt hammers, close-miked, slow arpeggios in the style of a modern film score.
Upbeat synthwave, analog bass, gated reverb drums, arpeggiated lead, 120 BPM.
Acoustic folk ensemble, fingerpicked guitar, upright bass, light tambourine, organic room sound.
Ambient drone, layered pads, no rhythm section, slowly evolving texture.

情绪主导的配方

Warm and nostalgic, like a summer evening, major key, gentle dynamics.
Tense and minimal, low pulsing bass, sparse percussion, unresolved harmony.
Playful and bright, staccato strings, bouncy rhythm, light-hearted.
Melancholic and spacious, reverb-heavy, sparse piano, slow tempo.

时长主导的配方

时长应作为明确目标写在提示词中，并且应与编曲一致。一个 15 秒的请求如果带有缓慢铺垫和长尾奏，会被生硬截断。

... about 15 seconds, short intro, no outro, ends cleanly.
... about 30 seconds, one clear section, loopable ending.
... about 60 seconds, intro, main section, and a natural fade.

组合示例

Lo-fi hip hop for focus, dusty vinyl crackle, soft electric piano, brushed drums, 80 BPM, calm and unhurried, about 30 seconds, loopable.

当输出不符合预期时

每次尝试只调整一个变量，这样你就能了解究竟是什么改变了结果。

太通用： 用具体的配器和速度替换情绪词。“Energetic”不如“driving 16th-note bass at 128 BPM”有力。
太繁忙或杂乱： 明确移除乐器（no drums、no vocals、sparse arrangement），而不是添加更多正向描述词。
长度感觉不对： 如果片段戛然而止，要求更短的目标并明确结尾；如果感觉仓促，减少请求的段落数量。
风格漂移： 将流派和配器移到提示词前面。靠前的 token 权重更高。

在仓库中保留一个小提示词文件，记录有效的配方。这个文件比任何单个生成的片段都更有价值，因为它将提示词写作变成可重复的工程产物。

常见错误及修复方法

大多数首次集成都以少数可预测的方式失败。在开始猜测之前，先过一遍这份清单。

认证失败

401 几乎总是意味着请求头格式错误，或进程环境中缺少密钥。检查 Bearer 后是否有杂散空格、密钥是否从错误的 .env 文件加载，或者 export 是否在运行脚本的不同会话中执行。打印密钥长度（不是密钥本身）以确认它已填充。

模型标识符不匹配

模型未找到或验证错误通常意味着 model 字符串不是精确匹配。elevenlabs/music-v2.5 区分大小写并包含一个斜杠。如果你从聊天窗口复制它，检查是否有智能引号或换行残留。

请求体格式错误

如果 curl 可用但 Python 不可用，差异几乎总是序列化问题。在期望 JSON 字符串的地方直接传 Python dict、用 json.dumps 双重编码，或忘记 Content-Type: application/json，都会产生服务端解析错误，看起来与真正原因无关。记录代码发送的精确请求体，并与可用的 curl 负载逐字符比较。

较长片段的超时

更长的时长需要更长的生成时间。对聊天请求合适的客户端超时，会截断较长的音乐请求。专门为此端点提高超时，并且只对连接级失败添加带退避的重试，绝不要盲目重试可能已经计费的请求。

提示词长度和内容

极长的提示词，或包含关于 API 本身指令的提示词，往往产生更差的音乐。让提示词只关于音乐。如果昨天有效的提示词停止工作，将其简化为风格/情绪/时长骨架，然后重建。

将响应当作文本处理

该端点返回音频数据，而不是可读的转录文本。将原始响应体写入 .txt 文件，然后纳闷为什么无法播放，是常见的首日错误。用正确的音频扩展名保存，并在进一步构建之前验证文件能在播放器中打开。

当错误确实不清晰时，用尽可能小的 curl 请求复现它。这样可以隔离问题出在 API 契约还是你的代码。

从测试调用到可重复的工作流

成功的测试调用是起点，不是集成。使用这份清单将其变成团队可以依赖的东西。

外置配置。 基础 URL、模型标识符、超时和默认时长目标放入配置，而不是散落的字符串字面量。环境特定的值来自环境。
集中客户端。 由一个函数或轻量客户端类负责请求。任何模块都不应自行构建对音乐端点的 HTTP 调用，否则你会在请求头和错误处理上产生分歧。
按类别处理错误。 区分认证、验证、超时和服务器错误。只重试瞬态错误，带退避和上限。绝不要重试可能已经产生输出并计费的请求。
正确存储音频。 用确定性键写入对象存储，将提示词与生成的资产放在一起，并记录模型标识符。以后重现结果取决于确切知道当时请求了什么。
将时长作为一等参数跟踪。 由于计费跟随输出时长，在提示词模板中明确目标时长，并按请求记录它，以便成本报告与用量对齐。
构建提示词库。 将验证过的配方纳入版本控制，并简短注明每个配方的用途。新团队成员从可用的提示词开始，而不是靠猜。
分离同步和异步路径。 生成可能很慢。对于面向用户的功能，提交作业、持久化请求，让 worker 调用模型。HTTP 处理器不应在整个生成期间保持打开。
用冒烟测试验证。 一个发送固定短提示词并断言音频响应格式正确的测试，可以及早发现凭据和契约漂移。

当你准备深入了解参数和限制时，HiAPI 上的 elevenlabs/music-v2.5 模型页面是硬编码假设之前查看当前能力的地方。

查看全部文章 →