> ## 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`。
</Note>

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

## Authorizations

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 进行认证

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

  ```
  Authorization: Bearer YOUR_API_KEY
  ```
</ParamField>

## Body

<ParamField body="model" type="string" required>
  固定为 `"suno"`
</ParamField>

<ParamField body="custom" type="boolean">
  模式开关，默认 `false`

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

<ParamField body="gpt_description" type="string">
  灵感模式下的音乐描述，如 `"一首雨夜咖啡馆的 lo-fi"`.自定义模式下不用传
</ParamField>

<ParamField body="prompt" type="string">
  自定义模式下的歌词文本（支持 `[Verse]`/`[Chorus]` 结构标记）
</ParamField>

<ParamField body="title" type="string">
  歌曲标题，自定义模式生效
</ParamField>

<ParamField body="style" type="string">
  风格标签，自定义模式生效，如 `"dreamy synthwave, female vocal"`
</ParamField>

<ParamField body="negative_tags" type="string">
  需要避免的元素，自定义模式生效
</ParamField>

<ParamField body="instrumental" type="boolean">
  是否生成无人声纯音乐
</ParamField>

<ParamField body="version" type="string">
  Suno 引擎版本：`v6` / `v6-wild` / `v6-mini`
</ParamField>

<ParamField body="max_mode" type="boolean">
  Max 高质量档，按两倍计费（\$0.10/次），需 `custom` 为 `true`
</ParamField>

<ParamField body="persona_id" type="string">
  使用已创建的人声角色 ID，与 `custom_model_id` 互斥
</ParamField>

<ParamField body="custom_model_id" type="string">
  使用自定义训练模型 ID，与 `version`、`persona_id` 互斥
</ParamField>

### 可选调优参数

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

## Response

<ResponseField name="task_id" type="string">
  任务 ID(`tsk_aud_` 前缀），用于 [查询任务状态](/docs/cn/api-reference/tasks/music-status)
</ResponseField>

<ResponseField name="status" type="string">
  初始状态，`submitted` / `queued` / `in_progress`
</ResponseField>

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

<RequestExample>
  ```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());
  ```
</RequestExample>


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