博客

教程

minimax-music-1.5 API 教程:curl 与 Python Requests

2026年11月12日
封面图:暖炭底色上一条宽阔琥珀光带斜穿狭缝,辅以低调深色几何块,构图克制留白。
本页内容

minimax-music-1.5 对请求的要求

在写第一行代码之前,最好先弄清楚一次音乐生成调用究竟包含什么。与文本补全不同,音乐请求有两个各司其职的创意输入,外加若干用于塑造输出的控制项。

从高层来看,一个 minimax-music-1.5 请求包含:

  • 风格或提示词描述 —— 音乐方向:流派、情绪、乐器编排、速度感、制作特征。
  • 歌词 —— 当曲目带人声时,实际演唱的文字。纯器乐请求留空或省略此项。
  • 结构控制 —— 比如生成曲目的目标时长,它限制了模型作曲的长度。
  • 模型标识符 —— minimax-music-1.5 —— 让网关把任务路由到正确的后端。

要牢记的心智模型:风格输入告诉模型它听起来应该是什么样,歌词输入告诉模型唱的是什么。两者不可互换。如果你把流派描述塞进歌词字段,会得到混乱的输出;如果你留空歌词却要求带人声的曲目,模型就只能自己编造。开始之前先确定你处于两种模式中的哪一种。

写代码之前还有两点需要内化:

  1. 音乐生成不是即时的。 生成一首成品曲目需要真实的计算时间,因此该 API 在设计上就是异步的。你提交任务,然后取回结果。任何只展示一次阻塞调用的教程,都是在向你隐藏轮询循环。
  2. 输出通过引用交付。 你收到的是生成音频的 URL,而不是内联的原始字节。需要另行下载或流式传输。

一旦你能说清这三件事——风格与歌词的区别、异步生命周期、基于 URL 的输出——实际请求体就很容易读了。

在 HiAPI 上完成初始配置

首次调用前你需要三样东西:一个 API 密钥、基础接口地址,以及不把密钥硬编码的习惯。

API 密钥

在你的 HiAPI 账户控制台创建密钥。把它当作密码对待:它用于验证每一个请求,并与你账户的用量绑定。绝不要提交到版本库,绝不要粘贴到公开的 gist,也绝不要打包进移动端或浏览器端的 bundle 中。

基础接口地址

所有调用都发往 HiAPI 网关,它在单一统一接口后暴露 minimax-music-1.5。你不需要为每个模型准备单独的凭证或 SDK——请求体中的模型名称即可选择后端。请查阅 API 参考文档以获取准确的基础 URL 和当前的请求路径。

让密钥远离源码

从临时脚本到生产环境都适用的模式是环境变量:

export HIAPI_API_KEY="your-key-here"

然后在运行时读取它。在 Python 中是 os.environ["HIAPI_API_KEY"];在 shell 中是 $HIAPI_API_KEY。如果你在本地使用 .env 文件,请在首次提交之前就把它加入 .gitignore——而不是之后。对于部署的服务,通过平台的密钥管理器注入密钥,而不是把它打进镜像里。

在动手构建任何东西之前做一个快速检查:确认你即将运行的进程能看到该密钥(在同一个 shell 中执行 echo $HIAPI_API_KEY)。大多数“认证失败”的报告都能追溯到在一个终端里导出了密钥,却在另一个终端里运行了脚本。

用 curl 发出第一个可用请求

从 curl 开始。它剥离每一层抽象,让你确切看到网络上传输的内容。下面的请求生成一首简短的带人声曲目;请根据你自己的意图调整字段值。

curl -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "prompt": "温暖独立民谣,指弹原声吉他,轻柔刷鼓,亲密的近场人声",
    "lyrics": "[verse]\n晨光洒在厨房地板上\n[chorus]\n我们依然在这里,我们依然在这里",
    "duration": 30
  }'

逐行解释:

  • -X POST —— 生成是创建操作,不是读取操作。
  • Authorization: Bearer $HIAPI_API_KEY —— 上一节的密钥,由 shell 展开,因此只要你引用变量,它就不会出现在你的历史记录中。
  • Content-Type: application/json —— 网关期望 JSON;省略此头是导致令人困惑的 4xx 响应的常见原因。
  • model —— 将请求固定到 minimax-music-1.5。
  • prompt —— 风格描述。具体说明乐器编排和情绪,而不是只用一个形容词。
  • lyrics —— 演唱文本,用 [verse] 和 [chorus] 这类轻量段落标签来提示结构。\n 转义是 JSON 换行符。
  • duration —— 以秒为单位限制生成曲目的长度。

返回的是任务引用,而不是音频。把它捕获下来:

curl -s -X POST "$HIAPI_BASE_URL/minimax-music-1.5" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d @payload.json | tee job.json

用 -d @payload.json 从文件读取请求体,可以保持你的 shell 历史干净,并让过渡到 Python 变得轻而易举——这个文件就是请求体。检查响应,记下任务或 task 标识符以及任何状态字段;你需要该标识符来取回结果。

将请求移植到 Python

Python 版本应该感觉像是 curl 调用的转写,而不是重写。使用 requests,从环境变量读取密钥,并把请求体保持为字典以便阅读。

import os
import json
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ["HIAPI_BASE_URL"]

payload = {
    "model": "minimax-music-1.5",
    "prompt": "温暖独立民谣,指弹原声吉他,轻柔刷鼓,亲密的近场人声",
    "lyrics": "[verse]\n晨光洒在厨房地板上\n[chorus]\n我们依然在这里,我们依然在这里",
    "duration": 30,
}

response = requests.post(
    f"{BASE_URL}/minimax-music-1.5",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    data=json.dumps(payload),
    timeout=60,
)
response.raise_for_status()
job = response.json()
print(json.dumps(job, indent=2))

几条避免意外的移植说明:

  • 使用 json.dumps 配合 data=,或使用 json=payload。 两者都可行;json=payload 会让 requests 替你设置内容类型。如果你把一个字典直接传给 data= 而不序列化,服务器会收到表单编码的请求体并拒绝它。
  • 始终设置 timeout。 不设置的话,一个停滞的连接会让你的进程无限挂起。记住这个超时覆盖的是提交,而不是生成——那是下一节要处理的问题。
  • 在解析之前调用 raise_for_status()。 它把 4xx 或 5xx 变成清晰的异常,而不是当你访问一个不存在的字段时出现神秘的 KeyError。
  • 保留响应对象。 调试时,打印 response.status_code 和 response.text 能告诉你远比解析后的错误更多的信息。

这个脚本的结果与 curl 产生的任务引用相同。提交之后的一切——轮询、重试、下载——无论用哪种语言都完全相同,这正是它值得单独成节的原因。

处理异步任务生命周期

音乐生成最常见的错误就是把它当成聊天补全:发送、等待、读取曲目。提交调用会很快返回,但音频还不存在。你的代码必须闭环。

三种状态

每个任务都会经过一个小型状态机:

  1. 已提交(Submitted) —— 你拿到了任务标识符,工作在排队或运行中。
  2. 已完成(Finished) —— 音频已就绪,响应中带有指向它的 URL。
  3. 已失败(Failed) —— 生成中止;响应会解释原因。

你的轮询循环应能区分全部三种状态。状态为 submitted 意味着继续等待,而不是重试。

轮询,不要猛打

一个以 CPU 允许的最快速度发起状态检查的朴素循环会消耗速率限制,且不会告诉你任何新信息——渲染一首曲目需要几十秒,所以每分钟数百次检查纯属浪费。加入退避:

import time

def wait_for_job(job_id, base_url, api_key, interval=2.0, max_wait=300):
    deadline = time.time() + max_wait
    while time.time() < deadline:
        r = requests.get(
            f"{base_url}/jobs/{job_id}",
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=30,
        )
        r.raise_for_status()
        data = r.json()
        status = data.get("status")
        if status == "finished":
            return data
        if status == "failed":
            raise RuntimeError(f"job failed: {data}")
        time.sleep(interval)
    raise TimeoutError(f"job {job_id} not finished after {max_wait}s")

查阅 API 参考文档以获取准确的轮询路径和状态字符串——把上面的名称视为示意,并与文档中的值对齐。

重试正确的对象

重试属于两个不同层级,把它们混为一谈会导致重复工作。传输重试——HTTP 调用本身因 5xx 或连接重置而失败——对轮询请求而言可以安全重复。生成重试则是新的提交,会再花费一次渲染,因此只在任务明确报告失败时才做,并且要限制次数。绝不要因为轮询慢而重试提交。

最后,在你收到任务标识符的那一刻就把它持久化。如果你的进程在提交与完成之间崩溃,该标识符是恢复已完成曲目而无需付费重新生成的唯一方式。

调整歌词、风格和时长输入

从 minimax-music-1.5 得到一首可用曲目,主要在于有意识地撰写这两个文本字段。几个习惯决定了输出是泛泛之作还是你真正愿意发布的东西。

把风格提示词写成制作人的简报

单个流派词给模型太多自由。堆叠具体的维度:

  • 流派与年代 —— “90 年代末 trip hop”胜过“电子”。
  • 乐器编排 —— 点名主奏乐器和节奏组。
  • 情绪与能量 —— “忧郁但推进感强”营造出单个形容词无法表达的张力。
  • 制作特征 —— “lo-fi、磁带饱和、宽立体声”引导混音。

保持在一到两句话。长篇段落式的提示词往往会稀释而非精炼。

用标签组织歌词结构

轻量的段落标记——[verse]、[chorus]、[bridge]——给模型一张路线图,通常比无标记的整块文本产生更清晰的歌曲结构。保持每行短到可以演唱;十二个词一行很少能契合旋律。对于器乐曲目,完全省略 lyrics,而不是发送一个内含风格文本的空字符串。

让时长匹配素材

时长限制了作曲。短时长配上完整的 verse-chorus-verse 歌词表会迫使压缩,结果听起来仓促;长时长配上两行歌词则会招致重复。先决定歌曲的形态,再设置契合它的时长。如果你需要更长的作品,请扩展歌词,而不是拉长时间然后指望它奏效。

用小改动迭代

当一首曲目接近但不对时,一次只改一个输入——提示词中的乐器编排,或速度词,或那句效果不好的歌词。同时改变一切会让你无法得知是哪个字段带来了改进。把你最好的请求体保存在文件中,并从它分支出去。

排查常见错误

大多数失败都落入少数几个可识别的类别。匹配症状,应用修复,继续前进。

认证失败

症状: 401 或 403,消息涉及凭证。

  • 确认头部是 Authorization: Bearer <key>——Bearer 一词和空格都是必需的。
  • 验证环境变量确实在发起请求的进程中设置。在一个 shell 中导出的密钥不会到达 cron 任务或 Docker 容器。
  • 检查随密钥一起复制进来的多余空白或换行。

格式错误的请求体

症状: 400,带有验证消息。

  • 发送 Content-Type: application/json。缺少该头会让服务器误解一个完全正确的请求体。
  • 如果使用 requests,传 json=payload 或 data=json.dumps(payload)。把原始字典传给 data= 会对其进行表单编码。
  • 对照 API 参考文档验证字段名和类型:model 必须恰好是 minimax-music-1.5,duration 是整数,歌词换行在 JSON 中需正确转义为 \n。
  • 拿不准时,用 curl -d @payload.json 在涉及任何 Python 之前先隔离判断请求体本身是否有效。

超时和连接错误

症状: 请求挂起,或抛出连接错误。

  • 为每次调用设置明确的 timeout。提交超时应足够宽裕以覆盖队列延迟,但它不是渲染时间。
  • 不要把你的轮询超时设成等于整体的 max_wait;单次缓慢的状态检查不应中止仍在运行的任务。
  • 如果提交反复超时而轮询成功,你的请求体可能太大——精简歌词。

轮询错误

症状: 你持续轮询却始终看不到 finished,或者你轮询了错误的资源。

  • 确认你使用的是提交响应中的任务标识符,而不是请求 ID 或关联头。
  • 把 submitted/running 视为“继续等待”而不是“重试提交”。重复提交会生成第二首曲目。
  • 加入退避。激进的轮询会招致速率限制,这看起来像失败,但其实是自己造成的。
  • 如果任务报告 failed,在重新提交前先读消息——无效的歌词标签或超出范围的时长每次都会以相同方式失败。

卡住时,退回到原始 curl 调用并加上 -v,以查看实际的状态行和头部。这一步比任何数量的 Python 调试都能更快地消除大多数歧义。

立即开始构建持久 AI 产物

获取 API 密钥,通过一个基于任务(task)的 API 调用图像、视频和音频模型。

阅读 API 文档