minimax-music-3 API：curl 与 Python 指南

在 hiapi 上使用 minimax-music-3 生成一首曲目，只需一次 POST /v1/tasks 调用加上轮询——这与平台上所有模型使用的异步任务模式完全一致。本指南记录了真实的请求和响应（任务创建、轮询以及最终音频 URL），因此下面的代码可以直接复制运行，而非仅作示意。

你需要准备什么

1. 一个 hiapi API 密钥——在控制台中创建。每次请求都会以 Bearer 令牌的形式发送。
2. 就这些。与图生视频或图生图模型不同，minimax-music-3 不接受任何文件或 URL 输入——它仅根据文本生成。

最小可用请求（curl）

创建任务：

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-3",
    "input": {
      "prompt": "chill lofi hip hop beat, mellow piano, soft drums",
      "lyrics": "[Instrumental]"
    }
  }'

响应：

{"code":200,"data":{"taskId":"tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55"},"message":"success"}

轮询任务直到完成：

curl https://api.hiapi.ai/v1/tasks/tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55 \
  -H "Authorization: Bearer sk-<your-key>"

任务运行期间，status 会依次经过 handling → archiving，最终变为 success（或 failed）。在测试中，一首曲目从提交到 success 大约用了两分半钟。完成后的响应如下：

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M09A11R6WEC2JDQ8RK6E7N55",
    "status": "success",
    "model": "minimax-music-3",
    "created": 1787018905,
    "completed": 1787019051,
    "storage": "temp",
    "output": [
      {
        "type": "audio",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M09A11R6WEC2JDQ8RK6E7N55-0.wav",
        "artifactId": "78585",
        "expireAt": 1787623851
      }
    ]
  },
  "message": "success"
}

output[0].url 就是 WAV 文件。注意 expireAt——在构建任何依赖该 URL 长期有效的功能之前，请先阅读下面的存储说明。

Python 中的相同流程

import time
import requests

API_KEY = "sk-<your-key>"
BASE_URL = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def create_track(prompt: str, lyrics: str = "[Instrumental]") -> str:
    resp = requests.post(
        f"{BASE_URL}/tasks",
        headers=HEADERS,
        json={"model": "minimax-music-3", "input": {"prompt": prompt, "lyrics": lyrics}},
        timeout=30,
    )
    body = resp.json()
    if resp.status_code != 200 or "error" in body:
        raise RuntimeError(f"create failed: {body}")
    return body["data"]["taskId"]


def wait_for_track(task_id: str, timeout_s: int = 300, interval_s: int = 6) -> str:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        resp = requests.get(f"{BASE_URL}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = resp.json()["data"]
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "failed":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(interval_s)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")


if __name__ == "__main__":
    task_id = create_track("upbeat synthwave, driving bassline, retro 80s")
    audio_url = wait_for_track(task_id)
    audio = requests.get(audio_url, timeout=60).content
    with open("track.wav", "wb") as f:
        f.write(audio)
    print(f"saved track.wav from task {task_id}")

minimax-music-3 实际校验的参数

输入 schema 是严格的——发送未列出的字段，API 会在请求进入队列之前就拒绝整个请求：

• prompt（字符串，必填）——风格、情绪、配器。这实际上决定了曲目的形态。
• lyrics（字符串，必填）——始终必填，即使是纯器乐曲目。传入 "[Instrumental]" 作为占位符；对于有演唱的曲目，使用 [Verse] / [Chorus] 等段落标签。
• callback（对象，可选）——{"url": "...", "when": "final"}。when 唯一支持的值是 "final"；其他任何值都会返回 400，错误信息为 invalid callback.when: only 'final' is supported。

发送这三个顶层键之外的任何内容——如 sample_rate、duration 或拼写错误——你会得到：

{"code":400,"data":null,"error_code":"INVALID_REQUEST","message":"invalid input: <root>: additional properties 'sample_rate' not allowed"}

生产环境注意事项

• 两种不同的错误形态。 校验错误（缺少字段、枚举值错误、未知键）会在顶层返回 {"code":400,"error_code":"INVALID_REQUEST","message":"..."}。认证/权限错误则返回 {"error":{"code":"permission_denied","message":"...","request_id":"..."}}——一个嵌套的 error 对象，HTTP 401。请在你的错误处理中检查这两种形态；只检查 resp["code"] 的代码会漏掉 401 的情况。
• permission_denied 表示密钥的问题，而不是请求的问题。 如果 prompt/lyrics 存在且类型正确，但你仍然收到 401 permission_denied，说明该 API 密钥本身没有启用此模型——请在控制台中检查它，而不是反复阅读你的 JSON。
• 输出文件的存储是临时的。 storage: "temp" 以及每个输出上的 expireAt Unix 时间戳——在捕获的示例中，大约是创建后 7 天。任务一旦成功，就立即下载文件或将其推送到你自己的存储；不要把 temp.hiapi.ai 的 URL 当作永久链接来保存。
• 对于任何批量任务，请使用回调。 轮询一首曲目没问题；轮询五十首就是五十次重复往返。设置 callback.url 和 when: "final"，让 hiapi 在任务真正完成时一次性将结果推送给你。
• 在获得 taskId 之前重试，而不是之后。 初始 POST /v1/tasks 出现网络错误或 5xx 时重试是安全的——此时尚未创建任何内容。一旦你有了 taskId，重新提交相同的 prompt 会创建另一首无关的曲目；此时应改为轮询或等待回调。

相关内容

• minimax-music-3 模型页面——当前价格和在线体验区。
• hiapi 定价——目录中所有模型的费率。
• hiapi 文档——超越此单一模型的完整 API 参考。

常见问题

纯器乐曲目需要提供歌词吗？ 需要——无论你是否想要人声，lyrics 都是必填字段。传入 "[Instrumental]"，模型就会生成无演唱的曲目。

可以完全避免轮询吗？ 可以，在创建任务时设置 callback: {"url": "https://your-endpoint", "when": "final"}。当任务达到终态时，hiapi 会将与 GET /v1/tasks/:id 相同的载荷 POST 到你的 URL。"final" 目前是 when 唯一支持的值。

为什么我会收到 "additional properties not allowed"？ minimax-music-3 的输入 schema 在 input 内只接受 prompt 和 lyrics（外加顶层的 callback）。任何其他字段名——即使它在其他 hiapi 模型上有效——都会在请求运行之前被拒绝。

为什么在其他模型上可用的密钥，在这个模型上却返回 401？ 模型访问权限是按密钥授予的。返回 401 且 error_code: "permission_denied" 意味着这个特定的密钥尚未被授予 minimax-music-3 的权限——请在控制台中启用它，这不是你的请求体有 bug。

下载输出文件之前我可以等多久？ 不要等——output[0].url 是一个临时链接（实践中 expireAt 大约是一周之后）。请将其视为一次性交接：任务成功后立即下载或重新上传。