如何使用 MiniMax Music API（minimax-music-1.5）：curl、Python 与可运行的请求

本指南介绍如何在 hiapi 的统一任务 API 上使用 minimax-music-1.5，通过风格提示词和歌词语生成一首完整歌曲——含人声、乐器和曲式结构。以下内容均已针对实际端点验证过，可直接复制、粘贴并运行。

你要构建什么，以及需要准备什么

目标：提交一段音乐风格的文字描述和你的歌词，然后得到一个可下载的音频轨道。

你只需要一样东西：一个 hiapi API 密钥。请从你的仪表盘获取——它以 sk- 开头。以下所有示例都假设它已存入环境变量：

export HIAPI_KEY="sk-your-key-here"

hiapi 上的音乐生成与所有其他模型走同一套异步任务接口：POST /v1/tasks 创建任务，然后要么轮询 GET /v1/tasks/<taskId>，要么在任务完成时接收回调。

输入 schema（已验证）

minimax-music-1.5 在 input 中接受以下字段——其他任何字段都会以 400 拒绝：

字段	是否必填	类型	约束
prompt	是	string	10–300 个字符。描述曲风、情绪、配器和人声风格。
lyrics	是	string	10–600 个字符。要演唱的歌词；支持 [Verse] 和 [Chorus] 等段落标签。
sample_rate	否	integer	16000、24000、32000、44100 之一。
bitrate	否	integer	32000、64000、128000、256000 之一。

有两个容易踩坑的地方：

1. prompt 和 lyrics 都是必填的。 prompt 控制听起来怎样；lyrics 控制唱的是什么。缺少任何一个都会得到 invalid input: ... missing required field。
2. schema 是严格的。你可能从其他音乐 API 预期存在的字段——duration、seed、format、instrumental——不被接受。发送它们会返回 additional properties ... not allowed。

最小可运行示例：curl

创建任务：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-1.5",
    "input": {
      "prompt": "Uplifting acoustic pop, warm female vocals, gentle guitar and light percussion",
      "lyrics": "[Verse]\nMorning light on a quiet street\nCoffee steam and a steady beat\n[Chorus]\nWe keep on going, we find our way\nOne small step at a time, every day",
      "sample_rate": 44100,
      "bitrate": 256000
    }
  }'

创建成功会返回一个任务 id：

{"code": 200, "data": {"taskId": "task_abc123..."}}

然后轮询，直到任务到达终态：

curl https://api.hiapi.ai/v1/tasks/task_abc123 \
  -H "Authorization: Bearer $HIAPI_KEY"

任务运行期间你会看到一个非终态的 status；完成时 status 变为 success，音频 URL 出现在 output 中：

{
  "code": 200,
  "data": {
    "taskId": "task_abc123",
    "status": "success",
    "output": [{"url": "https://.../track.mp3"}]
  }
}

请尽快下载文件——输出 URL 有时限，应当把它当作取件窗口而非永久存储：

curl -o track.mp3 "https://.../track.mp3"

完整 Python 脚本：提交、轮询、下载

import os
import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
HEADERS = {
    "Authorization": f"Bearer {os.environ['HIAPI_KEY']}",
    "Content-Type": "application/json",
}

def create_task() -> str:
    payload = {
        "model": "minimax-music-1.5",
        "input": {
            "prompt": ("Uplifting acoustic pop, warm female vocals, "
                       "gentle guitar and light percussion"),
            "lyrics": ("[Verse]\nMorning light on a quiet street\n"
                       "Coffee steam and a steady beat\n"
                       "[Chorus]\nWe keep on going, we find our way\n"
                       "One small step at a time, every day"),
            "sample_rate": 44100,
            "bitrate": 256000,
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_s: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = (r.json().get("data") or {})
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

def download(url: str, path: str = "track.mp3") -> str:
    r = requests.get(url, timeout=120)
    r.raise_for_status()
    with open(path, "wb") as f:
        f.write(r.content)
    return path

if __name__ == "__main__":
    task_id = create_task()
    print(f"submitted: {task_id}")
    task = wait_task(task_id)
    url = task["output"][0]["url"]
    print(f"done, downloading: {url}")
    print(f"saved to {download(url)}")

用 python3 make_song.py 运行它。脚本会提交任务、每 5 秒轮询一次，并将完成的轨道保存到本地。

生产环境模式

用回调代替轮询

对于任何超出快速脚本范围的用途，注册一个回调，让 hiapi 在任务到达终态时把结果推送给你。添加一个顶层 callback 对象（它与 model 同级，不在 input 内部）：

{
  "model": "minimax-music-1.5",
  "input": {"prompt": "...", "lyrics": "..."},
  "callback": {"url": "https://your.domain.example/hiapi/callback", "when": "final"}
}

仅支持 "when": "final"——任务成功或失败时你会收到一次 POST，而不是增量进度事件。轮询适合开发和一次性任务；当你要生成大量轨道或处于队列之后运行时，回调更优，因为你不必维持开放循环，也不会因高频轮询触发速率限制。如果回调始终未到达，请按照为什么你的 hiapi 任务回调未触发中的检查清单逐项排查。

幂等性与重试

任务创建本身不幂等：重试一个超时的 POST /v1/tasks 可能创建两个任务（并产生两次费用）。在创建调用返回后立即持久化 taskId，重启时通过轮询该 id 恢复，而不是盲目重新提交。如果任务看起来卡住了，不要立即杀掉并重新创建——参见hiapi /v1/tasks 任务挂起或超时时，了解如何区分慢任务和死任务。

错误处理

两类失败的表现不同：

• 请求级错误同步返回。错误或未授权的密钥会返回 permission_denied 错误（"This API key cannot use the selected model..."），并附带一个可向支持团队引用的 request_id。schema 违规会返回 400 INVALID_REQUEST，并附精确信息，例如 prompt: minLength: got 1, want 10。
• 任务级失败出现在轮询/回调结果中，表现为 status: "fail"，并带有 error.code 和 error.message——创建调用成功了，但生成没有成功。这些才是应进入重试逻辑的失败。

提交前在客户端校验长度：prompt 最多 300 个字符，lyrics 最多 600 个字符，API 会拒绝超长输入，而不是截断它们。

定价与限制

MiniMax Music 1.5 按生成的轨道计费，采用按用量定价——请在 hiapi 定价页和 minimax-music-1.5 模型页查看当前费率，在模型页你还可以在写任何代码前先在 playground 中试用模型。

常见问题

minimax-music-1.5 接受哪些输入字段？

恰好四个：prompt（必填，10–300 字符）、lyrics（必填，10–600 字符）、sample_rate（可选，16000/24000/32000/44100）和 bitrate（可选，32000/64000/128000/256000）。其他任何字段都会以 additional properties not allowed 被拒绝。

能控制歌曲结构吗？

可以——在 lyrics 中使用 [Verse] 和 [Chorus] 等段落标签来组织结构。模型会利用这些标签来塑造编曲。整个歌词字符串（含标签）须保持在 600 字符限制内。

能生成纯器乐音乐吗？

输入 schema 没有器乐开关。该端点由歌词驱动，因此请在 prompt 中描述你想要的配器和情绪；对于纯器乐用例，请查看模型页了解当前能力列表。

如何获取音频文件？

当任务状态为 success 时，data.output[0].url 中保存着下载链接。请立即获取并自行存储字节——输出 URL 会过期。

应该轮询还是使用回调？

开发和单个任务请用轮询（5 秒间隔足够）。生产环境请使用带 when: "final" 的 callback，以免保持连接打开——尤其是当你批量生成轨道时。

为什么我会收到 permission_denied？

你的密钥无效，或者没有访问该模型的权限。请在仪表盘中验证密钥，并确保以 Authorization: Bearer sk-... 形式发送。