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

# 音乐生成

> Suno 音乐生成,支持灵感模式与自定义歌词模式,可选 Max 高质量档

> [!NOTE]
>
> **国内用户请注意：** 中国大陆用户请使用 `https://toapis.cn` 作为接口地址（Base URL）。文档示例中的 `https://toapis.com` 请替换为 `https://toapis.cn`。

* 根据文本描述或自定义歌词生成完整歌曲（每次返回 2 个候选）
* 异步任务管理，通过任务 ID 查询结果
* `custom` 决定 `prompt` 的语义：自定义歌词模式 vs 灵感描述模式

## Authorizations

**Authorization** `string` *required*

使用 Bearer Token 进行认证

获取 API Key：访问 [API Key 管理页面](https://toapis.com/console/token)

```
Authorization: Bearer YOUR_API_KEY
```

## Body

**model** `string` *required*

固定为 `"suno"`

**custom** `boolean`

模式开关，默认 `false`

* `false`：灵感模式，`gpt_description`（或 `prompt`）描述想要的音乐
* `true`：自定义歌词模式，`prompt` 作为歌词文本，`title`/`style`/`negative_tags` 生效

**gpt\_description** `string`

灵感模式下的音乐描述，如 `"一首雨夜咖啡馆的 lo-fi"`.自定义模式下不用传

**prompt** `string`

自定义模式下的歌词文本（支持 `[Verse]`/`[Chorus]` 结构标记）

**title** `string`

歌曲标题，自定义模式生效

**style** `string`

风格标签，自定义模式生效，如 `"dreamy synthwave, female vocal"`

**negative\_tags** `string`

需要避免的元素，自定义模式生效

**instrumental** `boolean`

是否生成无人声纯音乐

**version** `string`

Suno 引擎版本：`v6` / `v6-wild` / `v6-mini`

**max\_mode** `boolean`

Max 高质量档，按两倍计费（\$0.10/次），需 `custom` 为 `true`

**persona\_id** `string`

使用已创建的人声角色 ID，与 `custom_model_id` 互斥

**custom\_model\_id** `string`

使用自定义训练模型 ID，与 `version`、`persona_id` 互斥

### 可选调优参数

`style_weight`、`weirdness`、`audio_weight`、`vocal_gender`、`auto_lyrics`、`variety` 均为可选，不传使用上游默认值。

## Response

**task\_id** `string`

任务 ID(`tsk_aud_` 前缀），用于 [查询任务状态](https://docs.toapis.com/docs/cn/api-reference/tasks/music-status.md)

**status** `string`

初始状态，`submitted` / `queued` / `in_progress`

完成后 `result.music[]` 返回 2 个候选曲目，各含 `audio_url`、`image_url`（封面）、`title`、`tags`、`lyrics`、`duration` 等字段，媒体 URL 已镜像至本站 CDN。

```bash cURL theme={null}
curl --request POST \
  --url https://toapis.com/v1/music/generations/generation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "suno",
    "gpt_description": "一首雨夜咖啡馆的 lo-fi 爵士",
    "instrumental": false,
    "version": "v6"
  }'
```

```python Python theme={null}
import requests

resp = requests.post(
    "https://toapis.com/v1/music/generations/generation",
    headers={"Authorization": "Bearer <token>"},
    json={
        "model": "suno",
        "custom": True,
        "prompt": "[Verse]\n街灯亮起来\n风吹过站台\n[Chorus]\n我们一起走过的年代",
        "title": "站台",
        "style": "chinese pop ballad",
        "max_mode": True
    }
)
print(resp.json())
```

```javascript JavaScript theme={null}
const resp = await fetch("https://toapis.com/v1/music/generations/generation", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    model: "suno",
    gpt_description: "dreamy synthwave with female vocals",
    version: "v6-wild"
  })
});
console.log(await resp.json());
```


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