> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rixapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Suno API 总览

> 调用流程、鉴权、全部接口、计费与错误处理

用接口调用 Suno：生成歌曲与歌词，改编、续写、分轨、导出，克隆音色。每个动作是一个接口 `POST /suno/v2/{动作}`，都是异步任务：提交后拿到任务 ID，再查询结果，或者提交时带上 `notify_hook` 等我们推送。

## 基础信息

| 项目 | 说明 |
| - | - |
| Base URL | `https://api.ephone.ai` |
| 鉴权 | 请求头 `Authorization: Bearer YOUR_API_KEY` |
| 请求体 | JSON，`Content-Type: application/json` |

每个接口页右侧都有调试面板：填入 API Key 和参数就能直接发请求。调试面板发出的是真实请求，会正常计费。

## 调用流程

**1. 提交任务**

调对应动作的接口，比如 [音乐生成](https://docs.rixapi.com/docs/cn/api-reference/suno/music.md)，响应里的 `data.task_id` 就是任务 ID。

**2. 取回结果**

用 [查询任务](https://docs.rixapi.com/docs/cn/api-reference/suno/fetch.md) 每 3 到 5 秒查一次，直到 `status` 变成 `SUCCESS` 或 `FAILURE`；一次查多个用 [批量查询](https://docs.rixapi.com/docs/cn/api-reference/suno/fetch-batch.md)。也可以提交时带上 `notify_hook`，任务结束后我们把和查询结果相同的内容推送过去。

**3. 接着创作**

结果里的 `music_id` 是续写、翻唱、分轨、导出等后续动作的入口，建议随任务一起存下来。

所有动作的提交响应都是同一个形状，查询响应的外层结构也相同，产物放在哪个字段见各接口页的「任务结果」。

> [!TIP]
>
> 也可以用统一任务接口 `POST /v1/task/submit` 提交：`model` 填 `suno/` 加动作名（如 `suno/music`），参数放进 `input`。两种写法效果与计费完全一样。

## 全部接口

每个动作的路径是 `POST /suno/v2/{动作}`，动作名见各表第一列。

### 生成新曲

| 接口 | 能做什么 |
| - | - |
| [音乐生成](https://docs.rixapi.com/docs/cn/api-reference/suno/music.md) `music` | 用一句话描述，或自己写歌词，生成完整歌曲，一次出两首。 |
| [歌词创作](https://docs.rixapi.com/docs/cn/api-reference/suno/lyrics.md) `lyrics` | 根据主题生成歌词，一次给两份候选。 |
| [音效生成](https://docs.rixapi.com/docs/cn/api-reference/suno/sounds.md) `sounds` | 生成单次音效或可循环音效，可指定节拍与调性。 |
| [参考音频生成](https://docs.rixapi.com/docs/cn/api-reference/suno/inspo.md) `inspo` | 以一到四段音频作为风格参考来创作。 |
| [采样再创作](https://docs.rixapi.com/docs/cn/api-reference/suno/sample.md) `sample` | 截取一段采样，以它为素材生成新曲。 |
| [双曲混合](https://docs.rixapi.com/docs/cn/api-reference/suno/mashup.md) `mashup` | 把两首曲目融合成一首新作。 |

### 改已有的曲子

| 接口 | 能做什么 |
| - | - |
| [歌曲续写](https://docs.rixapi.com/docs/cn/api-reference/suno/extend.md) `extend` | 从指定秒数继续写下去，风格与原曲保持一致。 |
| [翻唱改编](https://docs.rixapi.com/docs/cn/api-reference/suno/cover.md) `cover` | 保留旋律骨架，换一种风格重新演绎。 |
| [音质重制](https://docs.rixapi.com/docs/cn/api-reference/suno/remaster.md) `remaster` | 在保持原曲结构的前提下重新制作。 |
| [片段重写](https://docs.rixapi.com/docs/cn/api-reference/suno/replace-section.md) `replace-section` | 只重写指定的时间区间，其余部分保持不变。 |
| [为伴奏配唱](https://docs.rixapi.com/docs/cn/api-reference/suno/add-vocals.md) `add-vocals` | 给纯伴奏加上人声演唱。 |
| [为人声配乐](https://docs.rixapi.com/docs/cn/api-reference/suno/add-instrumental.md) `add-instrumental` | 给人声轨配上完整伴奏。 |
| [叠加乐器轨](https://docs.rixapi.com/docs/cn/api-reference/suno/add-stem.md) `add-stem` | 在现有曲目上再加一条乐器轨。 |

### 用你自己的音频

| 接口 | 能做什么 |
| - | - |
| [音频上传](https://docs.rixapi.com/docs/cn/api-reference/suno/upload.md) `upload` | 上传音频以供其他动作引用。 |
| [上传翻唱](https://docs.rixapi.com/docs/cn/api-reference/suno/upload-cover.md) `upload-cover` | 上传你自己的音频，换一种风格重新演绎。 |
| [上传续写](https://docs.rixapi.com/docs/cn/api-reference/suno/upload-extend.md) `upload-extend` | 上传你自己的音频，从指定位置接着写。 |

### 拆分与重组

| 接口 | 能做什么 |
| - | - |
| [人声分离](https://docs.rixapi.com/docs/cn/api-reference/suno/stems.md) `stems` | 从成曲里分离出主人声，或指定某一条乐器轨。 |
| [全轨分离](https://docs.rixapi.com/docs/cn/api-reference/suno/stems-all.md) `stems-all` | 一次拆出全部乐器与人声分轨。 |
| [分段拼接](https://docs.rixapi.com/docs/cn/api-reference/suno/concat.md) `concat` | 把续写产生的多段合并为完整曲目。 |

### 调整与导出

| 接口 | 能做什么 |
| - | - |
| [变速处理](https://docs.rixapi.com/docs/cn/api-reference/suno/adjust-speed.md) `adjust-speed` | 调整播放速度，可选择是否保持音高。 |
| [多格式导出](https://docs.rixapi.com/docs/cn/api-reference/suno/download.md) `download` | 导出 mp3、m4a 或 wav。 |
| [MIDI 导出](https://docs.rixapi.com/docs/cn/api-reference/suno/gen-midi.md) `gen-midi` | 把曲目转换成 MIDI。 |

### 音色与模型

| 接口 | 能做什么 |
| - | - |
| [音色提取](https://docs.rixapi.com/docs/cn/api-reference/suno/persona.md) `persona` | 从一首曲目提取音色，供后续创作复用。 |
| [音色克隆](https://docs.rixapi.com/docs/cn/api-reference/suno/create-voice.md) `create-voice` | 用一段音频克隆出可复用的音色。 |
| [专属模型训练](https://docs.rixapi.com/docs/cn/api-reference/suno/create-model.md) `create-model` | 用 6 到 24 段音频训练属于你的风格模型。 |

### 分析

| 接口 | 能做什么 |
| - | - |
| [歌词时间轴](https://docs.rixapi.com/docs/cn/api-reference/suno/aligned-lyrics.md) `aligned-lyrics` | 取歌词逐句的时间轴与整首的波形数据，可用于逐句高亮和绘制音轨图。 |
| [风格描述扩写](https://docs.rixapi.com/docs/cn/api-reference/suno/upsample-tags.md) `upsample-tags` | 把几个简短标签扩写成详细的风格描述。 |

### 查询

| 接口 | 能做什么 |
| - | - |
| [查询任务](https://docs.rixapi.com/docs/cn/api-reference/suno/fetch.md) `fetch/{task_id}` | GET，查询一个任务的状态与产物 |
| [批量查询](https://docs.rixapi.com/docs/cn/api-reference/suno/fetch-batch.md) `fetch` | 一次查询多个任务 |

## 计费

按次计费，与生成时长、返回条数无关：

* 一次返回多条结果的动作，如果部分失败，按实际成功的条数折算
* 开启 `max_mode` 价格翻倍，它只在自定义模式下有效
* 任务失败会退还本次费用
* 歌词时间轴（`aligned-lyrics`）不收费

各动作的单价见对应模型详情页的价格表。

## 错误处理

请求没有被受理时，返回非 2xx 状态码和 JSON 错误说明：

```json theme={null}
{ "code": "error", "message": "music_id is required" }
```

令牌无效、模型不可用这类网关层错误，说明放在 `error` 对象里：

```json theme={null}
{ "error": { "message": "Invalid Token", "type": "rix_api_error" } }
```

| 状态码 | 常见原因 |
| - | - |
| `400` | 参数缺失或取值不合法，模型不可用 |
| `401` | 令牌无效 |
| `404` | 查询的任务不存在 |
| `429` | 请求过于频繁 |
| `5xx` | 服务暂时不可用，稍后重试 |

任务已经受理、但处理失败时，查询结果的 `status` 是 `FAILURE`，原因在 `fail_reason` 里。

## 下一步

> [card] [Suno 音乐生成快速上手](https://docs.rixapi.com/docs/cn/guides/suno-quickstart.md)
>
> 生成第一首歌，选模型版本，自己写歌词

> [card] [Suno 工作流指南](https://docs.rixapi.com/docs/cn/guides/suno-workflows.md)
>
> 做完整的歌、改编、分轨、复用音色等常见流程


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.