任务与回调

查询生成结果。异步任务的标准模式。

查询任务

GET /v1/music/tasks/{task_id}

curl "$BASE/v1/music/tasks/41d04fb6-..." \
  -H "Authorization: Bearer $KEY"

响应

{
  "data": {
    "task_id": "41d04fb6-969f-4acc-8f65-38092c79ef2f",
    "status": "SUCCESS",
    "backend": "minimax",
    "model": "music-3.0",
    "result": {
      "audio_urls": ["https://kemo.net.cn/storage/v1/object/public/audio/xxx.mp3"],
      "duration": 180,
      "title": "晚风穿过旧巷口",
      "cover_url": "https://kemo.net.cn/storage/v1/object/public/audio/xxx.jpg"
    },
    "error": null,
    "cost": { "credits": 5 }
  }
}

状态取值

只有这三种。无论上游返回什么内部状态，网关都会归一到这三个值：

status	含义	客户端应做
`PENDING`	生成中	继续轮询
`SUCCESS`	已完成	取 `result.audio_urls`，停止轮询
`FAILED`	失败	读 `error` 字段，停止轮询

上游内部的各种状态名（GENERATING / processing / pending 等）都会映射成 PENDING。客户端不需要为不同引擎写适配层。

result 字段

字段	类型	说明
`audio_urls`	string[]	音频直链数组。生成中为空数组
`duration`	number	时长（秒）
`title`	string	曲目标题
`cover_url`	string	封面图直链

失败时

{
  "data": {
    "task_id": "41d04fb6-...",
    "status": "FAILED",
    "result": { "audio_urls": [], "duration": null, "title": null, "cover_url": null },
    "error": "MiniMax 账户余额不足，请管理员在 MiniMax 开放平台充值后重试；免费降级模型亦不可用（MiniMax 该音乐模型已停用）",
    "cost": { "credits": 0 }
  }
}

失败时积分会自动退还，cost.credits 为 0 或已扣金额已退。 error 字段是完整的人话原因，不要只取前几个字符。

任务不存在

404
{
  "error": {
    "code": 40401,
    "message": "任务不存在"
  }
}

注意：查一个不存在的任务会明确返回 404，而不是报 PENDING。早期实现曾把这种情况误报为 PENDING，导致客户端无限轮询——这个坑已经填掉了。

回调（规划中）

计划支持 webhook_url 参数，任务完成时推送。

该能力尚未上线。当前请用轮询方式。回调上线后会写进变更日志。

kemo Music API · 聚合多引擎音乐生成 · 文档随实现同步更新
最后更新：2026-10-23 · 有问题请联系站点管理员