音乐生成

创建一个生成任务。立即返回任务号，生成在后台进行。

请求

POST /v1/music/generate

请求头

名称	必填	说明
`Authorization`	是	`Bearer kemo_xxx`
`Content-Type`	是	`application/json`
`x-idempotency-key`	否	幂等键。也可放在 body 的 `idempotency_key`。建议使用

请求体

字段	类型	必填	说明
`prompt`	string	二选一	音乐描述。与 `lyrics` 至少给一个
`lyrics`	string	二选一	歌词正文。部分引擎强制要求（如 MiniMax 缺此项会报 `invalid params`）
`title`	string	否	曲目标题
`instrumental`	boolean	否	`true` 表示纯器乐，无人声
`model`	string	否	指定模型，如 `music-3.0`。默认由引擎决定
`backend`	string	否	指定引擎。默认 `auto`，按优先级自动路由
`idempotency_key`	string	否	幂等键，与请求头等价

响应

200 OK
{
  "data": {
    "task_id": "41d04fb6-969f-4acc-8f65-38092c79ef2f",
    "status": "PENDING",
    "backend": "minimax",
    "model": "music-3.0",
    "cost": { "credits": 5 },
    "poll": "/v1/music/tasks/41d04fb6-969f-4acc-8f65-38092c79ef2f",
    "created_at": "2026-10-23T02:10:23.993Z"
  }
}

字段	说明
`task_id`	任务唯一标识，用于查询结果
`status`	创建时固定为 `PENDING`
`backend`	实际命中的引擎。发生降级时是降级后的那个
`model`	实际使用的模型
`cost`	本次消耗积分。管理员账号或免费任务可能为 0
`poll`	查询该任务的相对路径

幂等

带相同 x-idempotency-key 的重复请求，返回同一个 task_id，不重复扣费。

# 第一次
{"data":{"task_id":"41d04fb6-...","status":"PENDING", ...}}

# 第二次（同一个 key）
{"data":{"task_id":"41d04fb6-...","status":"PENDING",
         "idempotent_replay":true,
         "note":"并发命中幂等，返回既有任务，未重复扣费"}}

幂等键的作用域是「同一用户 + 同一幂等键」。建议用业务侧的订单号或请求 UUID。

失败响应

400
{
  "error": {
    "code": 40002,
    "message": "请提供 prompt 或 lyrics"
  }
}

完整错误码见错误码。

当前可用引擎

backend	说明	备注
`minimax`	MiniMax 音乐	同步模式。需带 lyrics
`mureka`	Mureka	异步。响应自带无损 WAV 与逐字时间轴歌词
`kie`	KIE Suno	异步。需在后台启用
`auto`	自动路由（默认）	按 `ai_models` 的 priority 顺序尝试

可用引擎由站点后台配置，且受各上游账户状态影响。若某引擎未启用或余额不足，会在响应里以明确错误告知，或自动降级到其他引擎。

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