> ## 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 高品質檔

* 根據文字描述或自訂歌詞生成完整歌曲(每次返回 2 個候選)
* 異步任務管理,透過任務 ID 查詢結果
* `custom` 決定 `prompt` 的語義:自訂歌詞模式 vs 靈感描述模式

## Authorizations

<ParamField header="Authorization" type="string" required>
  使用 Bearer Token 認證,取得 API Key:[API Key 管理頁面](https://toapis.com/console/token)
</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/zh-Hant/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.