> ## 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 音乐生成快速上手

> 五分钟生成第一首歌，并了解结果怎么取回

Suno 提供生成、续写、翻唱、混音、分轨、变速、导出与音色训练等音乐能力。本文带你跑通第一首歌。

## 生成第一首歌

最简单的用法是用一句话描述你想要什么。

```bash bash theme={null}
curl https://api.ephone.ai/suno/v2/music \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mv": "chirp-v6",
    "custom": false,
    "instrumental": false,
    "gpt_description_prompt": "轻柔的 lo-fi 钢琴，雨落在铁皮屋顶上"
  }'
```

```python music.py theme={null}
import requests

resp = requests.post(
    "https://api.ephone.ai/suno/v2/music",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "mv": "chirp-v6",
        "custom": False,
        "instrumental": False,
        "gpt_description_prompt": "轻柔的 lo-fi 钢琴，雨落在铁皮屋顶上",
    },
)
task_id = resp.json()["data"]["task_id"]
```

```javascript music.js theme={null}
const resp = await fetch("https://api.ephone.ai/suno/v2/music", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    mv: "chirp-v6",
    custom: false,
    instrumental: false,
    gpt_description_prompt: "轻柔的 lo-fi 钢琴，雨落在铁皮屋顶上",
  }),
});
const { data } = await resp.json();
```

返回一个任务 ID：

```json theme={null}
{ "code": "success", "message": "success", "data": { "task_id": "5adac6ee-..." } }
```

## 取回结果

音乐生成是异步的，用任务 ID 查询：

```bash theme={null}
curl https://api.ephone.ai/suno/v2/fetch/5adac6ee-... \
  -H "Authorization: Bearer $API_KEY"
```

完成后 `status` 变成 `SUCCESS`：

```json theme={null}
{
  "code": "success",
  "data": {
    "task_id": "5adac6ee-...",
    "action": "music",
    "status": "SUCCESS",
    "progress": "100%",
    "musics": [
      {
        "music_id": "89b20862-...",
        "title": "Rain on Tin Roof",
        "tags": "lo-fi piano",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 187.56
      }
    ]
  }
}
```

> [!NOTE]
>
> 一次生成会返回 **两个版本**，可以都听过再挑。歌词创作同样一次给两份候选。

不想轮询的话，提交时带上 `notify_hook`，任务完成后我们会把结果推送到你的地址，内容与查询响应一致。

一次要查多个任务，用批量查询：

```bash theme={null}
curl -X POST https://api.ephone.ai/suno/v2/fetch \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["5adac6ee-...", "7b1f9c22-..."]}'
```

返回的 `data` 是数组，每一项与单个查询的 `data` 结构相同。

## 记住 music\_id

结果里的 `music_id` 是后续所有操作的入口：续写、翻唱、分轨、导出都靠它定位曲目。建议随任务一起存下来。

## 两种调用方式

上面用的是直接调用。如果你已经在用统一任务接口，写法如下，效果和计费完全一样：

```bash theme={null}
curl https://api.ephone.ai/v1/task/submit \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno/music",
    "input": {
      "mv": "chirp-v6",
      "custom": false,
      "instrumental": false,
      "gpt_description_prompt": "轻柔的 lo-fi 钢琴，雨落在铁皮屋顶上"
    }
  }'
```

模型名只决定动作，模型版本放在参数里，两种写法一致。

## 自己写歌词

把 `custom` 打开，用 `prompt` 提供完整歌词。可以用 `[Verse]`、`[Chorus]` 这类标记划分段落。

```json theme={null}
{
  "mv": "chirp-v6",
  "custom": true,
  "instrumental": false,
  "title": "Tin Roof Rain",
  "tags": "indie folk, 布鲁斯口琴, 舒缓",
  "prompt": "[Verse 1]\n雨打在铁皮屋顶上\n一声一声敲着你的名字\n\n[Chorus]\n让它下吧\n今晚我们哪儿也不去"
}
```

> [!WARNING]
>
> `custom` 关闭时必须提供 `gpt_description_prompt`；打开时必须提供 `prompt`，纯伴奏除外。

## 常用参数

| 参数 | 作用 |
| - | - |
| `mv` | 模型版本，三档同价，按想要的风格取向选 |
| `duration` | 成品时长，10 到 360 秒 |
| `tags` | 想要的曲风，越具体效果越稳 |
| `negative_tags` | 不希望出现的曲风 |
| `vocal_gender` | 演唱者的嗓音性别 |
| `instrumental` | 只要伴奏，不唱歌词 |
| `max_mode` | 投入更多算力保持全曲连贯，仅自定义模式有效，**价格翻倍** |
| `audio_format` | 输出格式，默认 mp3 |

## 模型版本怎么选

| 版本 | 适合 |
| - | - |
| `chirp-v6` | 默认，均衡 |
| `chirp-v6-wild` | 风格更奔放，适合实验性的方向 |
| `chirp-v6-mini` | 更快出结果 |

三个版本价格相同，不填默认 `chirp-v6`。

## 下一步

第一首歌出来之后，通常还要接着做别的：把歌写长、换个风格、取出人声、导出成 wav。这些动作是可以串起来的，而且有先后依赖。

> [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.