Mureka 音乐生成接口

本文档介绍魔芋 AI 的音乐生成接口，覆盖歌曲生成与任务查询。

平台采用异步任务模式：提交生成请求后获得任务 ID，再通过查询接口轮询获取结果。

支持模型

模型	说明
`mureka-8`	V8 常规模型
`mureka-9`	V9 常规模型

model 为必填参数，且取值必须是上表中已开通的模型；传入未开通的模型名会返回 404「模型不存在」。
API Key 必须归属可使用相应模型的分组，否则会返回模型无权限错误。

鉴权

所有请求均需携带令牌：

一、生成歌曲

请求参数

参数	类型	必填	说明
`model`	string	是	模型名称，取值见上方「支持模型」。本平台必填，缺省会返回 400「未指定模型名称」。
`lyrics`	string	是	生成音乐的歌词，最大 5000 个字符。
`prompt`	string	否	通过输入提示词控制音乐生成，最大 1024 个字符。可与 `vocal_id` 组合，与 `reference_id` 互斥。
`gender`	string	否	指定生成歌曲的人声性别倾向，优先遵循上传音频的人声特征。取值：`female`、`male`。
`reference_id`	string	否	通过参考音乐控制音乐生成，由上传文件接口生成（`purpose` 为 `reference`）。可与 `vocal_id` 组合，与 `prompt` 互斥。
`vocal_id`	string	否	通过音色控制音乐生成，由音色克隆接口生成。可与 `reference_id` 或 `prompt` 组合。
`melody_id`	string	否	通过旋律控制音乐生成，由上传文件接口生成（`purpose` 为 `melody`）。不能与任何其他控制选项组合。
`stream`	boolean	否	本平台暂不支持流式，传入后服务端会强制置为 `false`，任务不会进入 `streaming` 阶段。
`n`	integer	否	生成歌曲数量。本平台固定按 1 首生成与计费，传入其他值会被服务端强制钳制为 1。

必要参数组合

一次有效的生成请求需同时满足：

带 model；

带 lyrics（必填，官方 song/generate 端点硬性要求，最大 5000 个字符）；

melody_id 与 prompt/reference_id/vocal_id 不能同时传。

不带 lyrics 会立即返回 400。

控制选项组合规则

prompt、reference_id、vocal_id、melody_id 之间有以下约束：

组合	是否允许
无额外控制选项（仅 `lyrics`）	✅
`prompt` 单独（+ `lyrics`）	✅
`reference_id` 单独（+ `lyrics`）	✅
`vocal_id` 单独（+ `lyrics`）	✅
`melody_id` 单独（+ `lyrics`）	✅
`prompt` + `vocal_id`	✅
`reference_id` + `vocal_id`	✅
`prompt` + `reference_id`	❌ 互斥
`melody_id` + 任意其他控制选项	❌

请求示例

响应示例

{
  "id": "165573451513857",
  "created_at": 1677610602,
  "model": "mureka-8",
  "status": "preparing",
  "trace_id": "1e94aba5a2de4cc4bff54a2813c8d36c"
}

字段	类型	说明
`id`	string	异步音乐生成任务的任务 ID，用于后续查询。
`created_at`	integer	任务创建的时间戳（秒）。
`model`	string	用于音乐生成的模型。
`status`	string	任务当前状态，提交后恒为 `preparing`。
`trace_id`	string	请求链路追踪 ID，排查问题时可提供给技术支持。

二、查询任务

路径参数

参数	类型	必填	说明
`task_id`	string	是	生成歌曲接口返回的任务 ID。

请求示例

响应示例

{
  "code": "success",
  "data": {
    "task_id": "165573451513857",
    "status": "SUCCESS",
    "fail_reason": "",
    "result_url": "https://cdn.mureka.cn/xxxx.mp3",
    "progress": "100%",
    "data": {
      "id": "165573451513857",
      "created_at": 1677610602,
      "finished_at": 1677610802,
      "model": "mureka-9",
      "status": "succeeded",
      "watermarked": true,
      "choices": [
        {
          "id": "87654321",
          "url": "https://cdn.mureka.cn/xxxx.mp3",
          "wav_url": "https://cdn.mureka.cn/xxxx.wav",
          "flac_url": "https://cdn.mureka.cn/xxxx.flac",
          "duration": 157150,
          "lyrics_sections": []
        }
      ]
    }
  }
}

响应由两层组成：

外层（data 字段，平台包装）：

字段	类型	说明
`code`	string	`"success"` 表示请求本身成功（不代表任务已完成）。
`data.task_id`	string	任务 ID，与提交响应中的 `id` 一致。
`data.status`	string	平台状态枚举：`QUEUED`、`IN_PROGRESS`、`SUCCESS`、`FAILURE`，见下方状态表。
`data.fail_reason`	string	任务失败原因（仅 `FAILURE` 时非空）。
`data.result_url`	string	任务成功时的音频 URL（`SUCCESS` 时非空）。
`data.progress`	string	任务进度，如 `"50%"`、`"100%"`。
`data.data`	object	上游原始任务数据，含 `choices` 等详细字段，见下方内层字段说明。

内层（data.data，上游原始数据，SUCCESS 时有效）：

字段	类型	说明
`id`	string	任务 ID。
`created_at`	integer	任务创建时间戳（秒）。
`finished_at`	integer	任务完成时间戳（秒）。
`model`	string	使用的模型名称。
`status`	string	上游原生状态，见下方状态表。
`watermarked`	boolean	`true` 表示音频尾部含 5 秒水印。
`choices`	array	生成的歌曲列表，仅 `status` 为 `succeeded` 时有数据。

choices 数组元素：

字段	类型	说明
`id`	string	单曲 ID。
`url`	string	MP3 格式音频地址。
`wav_url`	string	WAV 格式音频地址。
`flac_url`	string	FLAC 格式音频地址。
`duration`	integer	音频时长，单位为毫秒（如 `157150` 表示 157.15 秒）。
`lyrics_sections`	array	歌词分段与逐句时间轴。

任务状态

轮询时以外层 data.status 为准（平台枚举）：

平台状态 (`data.status`)	说明
`QUEUED`	排队中
`IN_PROGRESS`	生成中
`SUCCESS`	生成成功，`data.result_url` 和 `data.data.choices` 有数据
`FAILURE`	生成失败，`data.fail_reason` 说明原因

内层 data.data.status 为上游原生枚举（preparing/queued/running/streaming/reviewing/succeeded/failed/timeouted/cancelled），可作参考但不建议用于轮询判断。

轮询建议

提交后每隔 3～5 秒查询一次，以外层 data.status 判断终态：

计费说明

按生成首数计费，价格取决于模型与功能两个维度，单位为元/首。

模型	歌词生曲	提示词生曲	背景音乐生成	其他
`mureka-8`	0.33 元/首	2.0 元/首	0.33 元/首	单轨生成 / 续写 / 混音 / 局部编辑
`mureka-9`	0.33 元/首	2.0 元/首	0.33 元/首	配乐

关于 n 参数：上游按 n 生成多首并据此计费。本平台固定按 1 首生成与计费，传入的 n 会被服务端强制钳制为 1，不会产生多首。

计费说明

按生成首数计费，价格取决于模型与功能两个维度，单位为元/首。

模型	歌词生曲	提示词生曲	背景音乐生成	其他功能
`mureka-8`	0.33 元/首	2.00 元/首	0.33 元/首	单轨生成 0.6 / 续写 0.95 / 混音 1.5 / 局部编辑 0.95
`mureka-9`	0.33 元/首	2.00 元/首	0.33 元/首	配乐 0.95

功能如何判定：系统依据请求参数自动识别本次调用的功能——

请求特征 (在 `song/generate` 端点)	判定功能	单价
带 `melody_id`	背景音乐生成	0.33 元/首
带 `lyrics`（不带 `melody_id`）	歌词生曲	0.33 元/首

「提示词生曲」对应的是上游另一个未接入本次适配器的端点（用 styles/prompt 直接生曲、无需歌词），表中列出仅供价格参照；在 song/generate 端点下无论是否带 prompt，只要带 lyrics 即按歌词生曲计费。

完整调用示例

错误处理

请求失败时返回 HTTP 400～600 状态码。错误响应有两种形态，解析时建议兼容：

形态一（鉴权、模型、参数校验类错误）：

{
  "error": {
    "code": "model_not_found",
    "message": "模型 mureka-999 不存在",
    "type": "moyu_api_error"
  }
}

形态二（上游建单失败类错误）：

{
  "code": "fail_to_fetch_task",
  "message": "具体失败原因",
  "data": null
}

状态码	说明	建议
400	请求参数不正确，或控制选项组合非法	参考本文参数表与组合规则核对
401	认证无效	检查令牌是否正确
403	无权访问该模型，或账户额度不足	检查令牌分组权限与账户余额
404	模型不存在	核对 `model` 取值是否在「支持模型」表中
429	请求频率过高	降低请求速度
500	服务端错误	稍后重试

排查问题时，可将建单响应中的 trace_id 提供给技术支持以便快速定位。

支持模型#

鉴权#

一、生成歌曲#

请求参数#

必要参数组合#

控制选项组合规则#

请求示例#

响应示例#

二、查询任务#

路径参数#

请求示例#

响应示例#

任务状态#

轮询建议#

计费说明#

计费说明#

完整调用示例#

错误处理#

支持模型

鉴权

一、生成歌曲

请求参数

必要参数组合

控制选项组合规则

请求示例

响应示例

二、查询任务

路径参数

请求示例

响应示例

任务状态

轮询建议

计费说明

计费说明

完整调用示例

错误处理