# Mureka 音乐生成 API 对接文档

## 基础信息

- 基础域名：`https://api.apiverse.ai`
- 鉴权方式：`Authorization: Bearer <API_KEY>`
- Content-Type：`application/json`
- 路由前缀：`/api/v2/open/aigc/mureka`

所有 Mureka 接口均通过上述路由前缀访问，路径与请求体字段原样透传：**在官方 Mureka 路径前拼接路由前缀即可**（例如官方 `/v1/song/generate` → `/api/v2/open/aigc/mureka/v1/song/generate`）。请求体、查询参数按原字段转发，不裁剪可选参数；响应保持原始 JSON 结构。

> 迁移提示：若你已有 Mureka SDK / 调用代码，只需把 baseUrl 从官方地址改为 `https://api.apiverse.ai/api/v2/open/aigc/mureka`，鉴权头替换为本平台 API Key，其余路径和参数不变。

## 接口能力概览

接口分为三类，计费与查询方式不同：

- **同步接口**：请求即时返回结果，无需轮询（歌词生成、歌词续写、歌曲识别、歌曲理解、音色克隆、语音合成、播客语音）。
- **异步接口**：请求返回任务 `id`，需用对应的查询接口轮询结果（歌曲生成、纯音乐、配乐、续写、混音、局部编辑、单轨、分轨、转谱、歌词视频）。
- **上传接口**：用于上传参考音频/图片/视频等素材，返回素材 ID 供其它接口引用，免费透传。

## 快速示例

### 生成歌曲（异步）

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/mureka/v1/song/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
    "lyrics": "[Verse]\n咸咸的风 吹乱了头发\n[Chorus]\n在夏天 还是会想你",
    "model": "auto",
    "prompt": "pop, sad, summer",
    "n": 2
  }'
```

返回任务 `id`：

```json
{
  "id": "1523127798xxxxx",
  "created_at": 1785306793,
  "model": "mureka-9",
  "status": "preparing",
  "trace_id": "xxxxxxxx"
}
```

### 查询歌曲任务（轮询）

```bash
curl "https://api.apiverse.ai/api/v2/open/aigc/mureka/v1/song/query/1523127798xxxxx" \
  -H "Authorization: Bearer <API_KEY>"
```

生成完成后返回 `status: succeeded` 及结果列表：

```json
{
  "id": "1523127798xxxxx",
  "created_at": 1785306793,
  "finished_at": 1785306839,
  "model": "mureka-9",
  "status": "succeeded",
  "choices": [
    {
      "id": "1523128698xxxxx",
      "url": "https://cdn.example.com/song/xxxxx.mp3",
      "flac_url": "https://cdn.example.com/song/xxxxx.flac",
      "duration": 128000
    }
  ],
  "trace_id": "xxxxxxxx"
}
```

> ⚠️ **关于 `song_id`**：续写、混音、局部编辑、单轨、转谱等接口的 `song_id` 参数，需填查询结果 `choices[].id`（**每首歌各自的 id**），**不是**外层任务 `id`。填错会返回 `The corresponding song is not found`。

### 生成歌词（同步）

```bash
curl -X POST "https://api.apiverse.ai/api/v2/open/aigc/mureka/v1/lyrics/generate" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{ "prompt": "夏天的海边，思念一个人" }'
```

即时返回标题与歌词：

```json
{
  "title": "夏日海岸的想念",
  "lyrics": "[Verse]\n咸咸的风 吹乱了头发\n...",
  "trace_id": "xxxxxxxx"
}
```

## 接口列表

### 异步接口（需轮询查询）

| 能力       | 方法 | 路径                                                | 查询接口              |
| ---------- | ---- | --------------------------------------------------- | --------------------- |
| 歌曲生成   | POST | `/api/v2/open/aigc/mureka/v1/song/generate`         | 歌曲任务查询          |
| 一句话生成 | POST | `/api/v2/open/aigc/mureka/v1/song/easy-generate`    | 歌曲任务查询          |
| 纯音乐生成 | POST | `/api/v2/open/aigc/mureka/v1/instrumental/generate` | 纯音乐任务查询        |
| 配乐生成   | POST | `/api/v2/open/aigc/mureka/v1/soundtrack/generate`   | 歌曲任务查询          |
| 歌曲续写   | POST | `/api/v2/open/aigc/mureka/v1/song/extend`           | 歌曲任务查询          |
| 歌曲混音   | POST | `/api/v2/open/aigc/mureka/v1/song/remix`            | 歌曲任务查询          |
| 局部编辑   | POST | `/api/v2/open/aigc/mureka/v1/song/region-edit`      | 歌曲任务查询          |
| 单轨生成   | POST | `/api/v2/open/aigc/mureka/v1/track/generate`        | 歌曲任务查询          |
| 歌曲分轨   | POST | `/api/v2/open/aigc/mureka/v1/song/stem`             | 歌曲任务查询          |
| 音乐转谱   | POST | `/api/v2/open/aigc/mureka/v1/song/transcribe`       | 歌曲任务查询          |
| 歌词视频   | POST | `/api/v2/open/aigc/mureka/v1/lyrics-video/generate` | 歌曲任务查询          |

### 查询接口

| 能力         | 方法 | 路径                                                     |
| ------------ | ---- | -------------------------------------------------------- |
| 歌曲任务查询 | GET  | `/api/v2/open/aigc/mureka/v1/song/query/{task_id}`       |
| 纯音乐查询   | GET  | `/api/v2/open/aigc/mureka/v1/instrumental/query/{task_id}` |

> 歌曲类异步接口（生成/续写/混音/编辑/单轨/分轨/转谱/配乐/歌词视频）统一走「歌曲任务查询」，纯音乐接口走「纯音乐查询」。`{task_id}` 为创建接口返回的 `id`。

### 同步接口（即时返回）

| 能力       | 方法 | 路径                                             |
| ---------- | ---- | ------------------------------------------------ |
| 歌词生成   | POST | `/api/v2/open/aigc/mureka/v1/lyrics/generate`    |
| 歌词续写   | POST | `/api/v2/open/aigc/mureka/v1/lyrics/extend`      |
| 歌曲识别   | POST | `/api/v2/open/aigc/mureka/v1/song/recognize`     |
| 歌曲理解   | POST | `/api/v2/open/aigc/mureka/v1/song/describe`      |
| 音色克隆   | POST | `/api/v2/open/aigc/mureka/v1/song/vocal-clone`   |
| 语音合成   | POST | `/api/v2/open/aigc/mureka/v1/tts/generate`       |
| 播客语音   | POST | `/api/v2/open/aigc/mureka/v1/tts/podcast`        |

### 上传接口（免费透传）

| 能力         | 方法 | 路径                                               |
| ------------ | ---- | -------------------------------------------------- |
| 文件上传     | POST | `/api/v2/open/aigc/mureka/v1/files/upload`         |
| 创建分片上传 | POST | `/api/v2/open/aigc/mureka/v1/uploads/create`       |
| 追加分片     | POST | `/api/v2/open/aigc/mureka/v1/uploads/add`          |
| 完成分片上传 | POST | `/api/v2/open/aigc/mureka/v1/uploads/complete`     |

## 参数说明

### 1. 歌曲生成

**POST** `/v1/song/generate`

| 参数         | 类型    | 必填 | 说明                                                              |
| ------------ | ------- | ---- | ----------------------------------------------------------------- |
| lyrics       | string  | 是   | 歌词，支持 `[Verse]`/`[Chorus]` 等结构标记，最大 5000 字符。      |
| model        | string  | 是   | 模型：`auto` / `mureka-7.6` / `mureka-o2` / `mureka-8` / `mureka-9`。 |
| prompt       | string  | 否   | 风格提示词，如 `r&b, slow, male vocal`，最大 1024 字符。          |
| n            | integer | 否   | 生成数量，1~3，默认 2。                                           |
| gender       | string  | 否   | 人声性别倾向：`female` / `male`。                                 |
| reference_id | string  | 否   | 参考音乐 ID（文件上传 purpose=reference 获得）。                  |
| vocal_id     | string  | 否   | 音色 ID（音色克隆生成）。                                         |
| melody_id    | string  | 否   | 旋律 ID（文件上传 purpose=melody 获得）。                        |
| stream       | boolean | 否   | 开启后任务含 streaming 阶段，可边生成边听。                       |

### 2. 一句话生成

**POST** `/v1/song/easy-generate`

| 参数         | 类型    | 必填 | 说明                                          |
| ------------ | ------- | ---- | --------------------------------------------- |
| prompt       | string  | 否   | 一句话描述想要的歌曲，最大 2000 字符。        |
| model        | string  | 否   | 模型：`auto` / `mureka-7.6` / `mureka-o2` / `mureka-8` / `mureka-9`。 |
| n            | integer | 否   | 生成数量，1~3，默认 2。                       |
| styles       | array   | 否   | 风格控制，可多选（如 `pop` / `rock` / `jazz` / `r&b` / `edm`）。 |
| reference_id | string  | 否   | 参考音乐 ID。                                 |
| vocal_id     | string  | 否   | 音色 ID。                                     |
| stream       | boolean | 否   | 开启后任务含 streaming 阶段。                 |

### 3. 纯音乐生成

**POST** `/v1/instrumental/generate`

| 参数            | 类型    | 必填 | 说明                                          |
| --------------- | ------- | ---- | --------------------------------------------- |
| model           | string  | 是   | 模型：`auto` / `mureka-7.6` / `mureka-8` / `mureka-9`。 |
| prompt          | string  | 否   | 风格提示词，如 `epic orchestral, cinematic`，最大 1024 字符。 |
| n               | integer | 否   | 生成数量，1~3，默认 2。                       |
| instrumental_id | string  | 否   | 参考纯音乐 ID（文件上传 purpose=instrumental 获得）。 |
| stream          | boolean | 否   | 开启后任务含 streaming 阶段。                 |

> 纯音乐任务需用「纯音乐查询」接口轮询结果。

### 4. 配乐生成

**POST** `/v1/soundtrack/generate`

为图片或视频生成配乐。

| 参数        | 类型    | 必填 | 说明                                                     |
| ----------- | ------- | ---- | -------------------------------------------------------- |
| image_id    | string  | 条件 | 要配乐的图片 ID（与 `video_id` 二选一）。                |
| video_id    | string  | 条件 | 要配乐的视频 ID（与 `image_id` 二选一）。                |
| model       | string  | 否   | 模型：`auto` / `mureka-7.6` / `mureka-8` / `mureka-9`。  |
| prompt      | string  | 否   | 配乐场景/情绪描述，最大 1024 字符。                      |
| n           | integer | 否   | 生成数量，1~3，默认 2。                                  |
| audio_start | integer | 否   | 配乐起始时间（毫秒），片段至少 3 秒。                    |
| audio_end   | integer | 否   | 配乐结束时间（毫秒），超出总时长则生成到结尾。          |

### 5. 歌曲续写

**POST** `/v1/song/extend`

| 参数            | 类型    | 必填 | 说明                                        |
| --------------- | ------- | ---- | ------------------------------------------- |
| song_id         | string  | 条件 | 源歌曲 ID（与 `upload_audio_id` 二选一）。  |
| upload_audio_id | string  | 条件 | 上传音频 ID（与 `song_id` 二选一）。        |
| lyrics          | string  | 是   | 续写的歌词。                                |
| extend_type     | string  | 是   | 续写方向：`tail` 向后 / `head` 向前。       |
| extend_at       | integer | 否   | 续写起始时间（毫秒），head/tail 模式可省略。 |
| model           | string  | 否   | 模型：`mureka-8`。                          |

### 6. 歌曲混音

**POST** `/v1/song/remix`

| 参数            | 类型    | 必填 | 说明                                       |
| --------------- | ------- | ---- | ------------------------------------------ |
| song_id         | string  | 条件 | 源歌曲 ID（与 `upload_audio_id` 二选一）。 |
| upload_audio_id | string  | 条件 | 上传音频 ID（与 `song_id` 二选一）。       |
| lyrics          | string  | 是   | 新歌词，最大 5000 字符。                   |
| prompt          | string  | 是   | 风格提示词，最大 1024 字符。               |
| n               | integer | 否   | 生成数量，1~3，默认 2。                    |

### 7. 局部编辑

**POST** `/v1/song/region-edit`

对歌曲指定区间重写。

| 参数            | 类型    | 必填 | 说明                                       |
| --------------- | ------- | ---- | ------------------------------------------ |
| song_id         | string  | 条件 | 源歌曲 ID（与 `upload_audio_id` 二选一）。 |
| upload_audio_id | string  | 条件 | 上传音频 ID（与 `song_id` 二选一）。       |
| lyrics          | string  | 是   | 重写区间的新歌词，最大 3000 字符。         |
| edit_start      | integer | 否   | 编辑起始（毫秒），区间至少 3 秒。          |
| edit_end        | integer | 否   | 编辑结束（毫秒），区间至少 3 秒。          |

### 8. 单轨生成

**POST** `/v1/track/generate`

为歌曲生成指定类型的单轨。

| 参数            | 类型    | 必填 | 说明                                                          |
| --------------- | ------- | ---- | ------------------------------------------------------------- |
| song_id         | string  | 条件 | 源歌曲 ID（与 `upload_audio_id` 二选一）。                    |
| upload_audio_id | string  | 条件 | 上传音频 ID（与 `song_id` 二选一）。                          |
| generate_type   | string  | 是   | 轨道类型：`Vocals` / `Instrumental` / `Drums` / `Bass` / `Guitar` / `Keyboard` / `Percussion` / `Strings` / `Synth` / `FX` / `Brass` / `Woodwinds`。 |
| prompt          | string  | 是   | 风格描述，最大 1024 字符。                                    |
| lyrics          | string  | 条件 | `generate_type=Vocals` 时必填。                               |
| vocal_gender    | string  | 否   | 人声性别：`male` / `female`（仅 Vocals 生效）。              |
| generate_start  | integer | 否   | 起始时间（毫秒）。                                            |
| generate_end    | integer | 否   | 结束时间（毫秒）。                                            |

### 9. 歌曲分轨

**POST** `/v1/song/stem`

将歌曲分离为独立音轨。

| 参数  | 类型   | 必填 | 说明                                                    |
| ----- | ------ | ---- | ------------------------------------------------------- |
| url   | string | 是   | 待分轨的歌曲 URL。                                      |
| model | string | 否   | 分离模型：`audio-separation-1` / `-2` / `-3`。         |

### 10. 音乐转谱

**POST** `/v1/song/transcribe`

| 参数            | 类型   | 必填 | 说明                                          |
| --------------- | ------ | ---- | --------------------------------------------- |
| song_id         | string | 条件 | 源歌曲 ID（三选一，1 个月内有效）。           |
| upload_audio_id | string | 条件 | 上传音频 ID（三选一，文件上传 purpose=audio）。 |
| url             | string | 条件 | 待转谱的音频链接（三选一）。                  |

### 11. 歌词视频

**POST** `/v1/lyrics-video/generate`

| 参数             | 类型    | 必填 | 说明                                                     |
| ---------------- | ------- | ---- | -------------------------------------------------------- |
| song_id          | string  | 条件 | 歌曲 ID（与 `upload_audio_id` 二选一）。                 |
| upload_audio_id  | string  | 条件 | 上传音频 ID（文件上传 purpose=audio）。                  |
| background_id    | string  | 否   | 背景图片 ID（文件上传 purpose=lyrics-video）。          |
| cover            | string  | 否   | 封面链接（`.jpg`/`.jpeg`/`.png`/`.webp`）。             |
| title            | string  | 否   | 视频标题。                                               |
| aspect_ratio     | string  | 否   | 尺寸：`16:9` / `9:16` / `3:4` / `4:3`，默认 `9:16`。     |
| layout           | string  | 否   | 布局模板 `layout_1`~`layout_7`，默认 `layout_1`（该模板不支持封面）。 |
| lyrics_start_row | integer | 否   | 起始歌词行号（与 `selection_*` 互斥，纯音乐不支持）。   |
| lyrics_end_row   | integer | 否   | 结束歌词行号（与 `selection_*` 互斥，纯音乐不支持）。   |
| selection_start  | integer | 否   | 时间选区起始（毫秒，与 `lyrics_*_row` 互斥）。          |
| selection_end    | integer | 否   | 时间选区结束（毫秒，与 `lyrics_*_row` 互斥）。          |

### 12. 歌词生成（同步）

**POST** `/v1/lyrics/generate`

| 参数   | 类型   | 必填 | 说明                       |
| ------ | ------ | ---- | -------------------------- |
| prompt | string | 是   | 歌词主题、情绪或故事描述。 |

### 13. 歌词续写（同步）

**POST** `/v1/lyrics/extend`

| 参数   | 类型   | 必填 | 说明           |
| ------ | ------ | ---- | -------------- |
| lyrics | string | 是   | 待续写的歌词。 |

### 14. 歌曲识别（同步）

**POST** `/v1/song/recognize`

| 参数            | 类型   | 必填 | 说明          |
| --------------- | ------ | ---- | ------------- |
| upload_audio_id | string | 是   | 上传音频 ID。 |

### 15. 歌曲理解（同步）

**POST** `/v1/song/describe`

分析歌曲风格、情绪等信息。

| 参数 | 类型   | 必填 | 说明                          |
| ---- | ------ | ---- | ----------------------------- |
| url  | string | 是   | 歌曲 URL 或 `data:audio` base64。 |

### 16. 音色克隆（同步）

**POST** `/v1/song/vocal-clone`

上传音频进行音色克隆，返回音色 ID 供歌曲生成引用。

| 参数            | 类型   | 必填 | 说明          |
| --------------- | ------ | ---- | ------------- |
| upload_audio_id | string | 是   | 上传音频 ID。 |

### 17. 语音合成 TTS（同步）

**POST** `/v1/tts/generate`

| 参数     | 类型   | 必填 | 说明                                          |
| -------- | ------ | ---- | --------------------------------------------- |
| text     | string | 是   | 待合成文本，最大 500 字符。                   |
| voice    | string | 条件 | 说话人（与 `voice_id` 二选一）。              |
| voice_id | string | 条件 | 参考语音 ID（文件上传 purpose=voice，与 `voice` 二选一）。 |

### 18. 播客语音（同步）

**POST** `/v1/tts/podcast`

多角色对话式语音合成。

| 参数          | 类型  | 必填 | 说明                                          |
| ------------- | ----- | ---- | --------------------------------------------- |
| conversations | array | 是   | 对话数组，最多 10 条；每条含 `text`（≤400 字符）与 `voice`（说话人）。 |

请求示例：

```json
{
  "conversations": [
    { "text": "大家好，欢迎收听本期节目。", "voice": "Ethan" },
    { "text": "今天我们聊聊夏天的海边。", "voice": "Victoria" }
  ]
}
```

### 19. 素材上传

**POST** `/v1/files/upload`（`multipart/form-data`）

上传参考音频/图片/视频等素材，返回素材 ID 供其它接口通过 `reference_id` / `vocal_id` / `image_id` / `upload_audio_id` 等字段引用。大文件可使用分片上传接口（`/v1/uploads/create` → `/v1/uploads/add` → `/v1/uploads/complete`）。

## 任务状态说明

异步任务查询返回的 `status` 取值：

| status     | 说明               |
| ---------- | ------------------ |
| preparing  | 任务已创建，准备中 |
| queued     | 排队中             |
| running    | 生成中             |
| streaming  | 流式输出中         |
| succeeded  | 已完成，结果可用   |
| failed     | 生成失败           |
| timeouted  | 超时               |
| cancelled  | 已取消             |

> 任务失败（`failed` / `timeouted` / `cancelled`）时，本次调用产生的费用将自动退回。

## 轮询与处理时间建议

歌曲/纯音乐等为异步任务，建议轮询间隔：

- 前 30 秒：每 5 秒查询一次
- 30 秒 ~ 2 分钟：每 10 秒查询一次
- 2 分钟后：每 15 秒查询一次

处理时间参考：

- 歌词生成 / 续写：通常 3 ~ 10 秒（同步返回）
- 歌曲 / 纯音乐 / 配乐生成：通常 30 秒 ~ 2 分钟
- 音色克隆 / 歌曲分轨：通常 10 ~ 30 秒

## 模型说明

| 模型       | 说明                             |
| ---------- | -------------------------------- |
| auto       | 自动选择最佳模型                 |
| mureka-7.6 | 基础模型                         |
| mureka-o2  | 优化模型                         |
| mureka-8   | 进阶模型                         |
| mureka-9   | 最新模型（仅歌曲/纯音乐生成支持）|

## 错误码

| code  | 说明               |
| ----- | ------------------ |
| 0     | 成功               |
| 10002 | 参数缺失或格式错误 |
| 10005 | API Key 无效或缺失 |
| 40001 | 余额不足           |
| 90003 | 服务器内部错误     |

接口正常时响应保持上游原始 JSON 结构；网关层错误（如路径不支持、余额不足）返回统一结构：

```json
{
  "code": 40001,
  "msg": "insufficient balance",
  "data": null
}
```