Suno 音频任务

用于提交 Suno 歌曲生成、续写、拼接、翻唱、分轨、片段替换、混曲、采样和声音生成等音频任务。

接口地址

http

POST /suno/audios

通用说明

所有请求都需要通过 X-API-Key 鉴权。
默认 async_mode 为 false。异步模式下会返回任务 ID，调用方可通过任务查询接口获取结果。
当 async_mode 为 false 时，请求会等待生成结果后返回，响应时间通常更长。
请求体中的 action 必须是本文档列出的可选值。

通用参数

参数	类型	必填	默认值	说明
`async_mode`	boolean	否	`false`	是否使用异步模式
`action`	string	是	-	任务动作，见下方 action 说明
`prompt`	string	视 action 而定	-	歌曲、翻唱、替换、采样或声音提示词，字符长度不得超过 1000
`model`	string	视 action 而定	-	Suno 模型
`custom`	boolean	否	-	是否使用自定义模式
`instrumental`	boolean	否	-	是否生成纯音乐
`title`	string	否	-	自定义模式下的歌曲标题
`style`	string	否	-	音乐风格，长度限制见下方参数长度限制
`lyric`	string	否	-	自定义歌词，长度限制见下方参数长度限制
`origin_lyric`	string	否	-	续写时原歌曲在 `0` 到 `continue_at` 片段内的歌词；片段替换时也可用于提供原歌词
`full_lyric`	string	否	-	续写或拼接时补充完整歌词
`audio_id`	string	视 action 而定	-	已生成或已上传的音频 ID
`audio_url`	string	视 action 而定	-	上传类动作使用的音频 URL
`continue_at`	integer	否	-	续写、上传续写、拼接时的起始秒数
`persona_id`	string	否	-	Persona ID，用于 Persona 生成、翻唱或续写
`persona_type`	string	否	-	Persona 类型，例如 `vox`
`persona_root_id`	string	否	-	创建 Persona 时的歌曲 ID
`style_negative`	string	否	-	需要排除的风格
`style_influence`	number	否	-	风格影响参数
`weirdness`	number	否	-	创意随机参数
`audio_influence`	number	否	-	音频影响参数
`vocal_gender`	string	否	-	人声性别，`m` 或 `f`
`replace_section_start`	integer	否	-	替换片段起始秒数
`replace_section_end`	integer	否	-	替换片段结束秒数
`overpainting_start`	integer	否	-	人声重绘起始秒数
`overpainting_end`	integer	否	-	人声重绘结束秒数
`underpainting_start`	integer	否	-	伴奏重绘起始秒数
`underpainting_end`	integer	否	-	伴奏重绘结束秒数
`mashup_audio_ids`	string[]	否	-	混曲使用的多个音频 ID
`variation_category`	string	否	-	Remaster 变体强度
`sample_start`	string	否	-	采样起始时间
`sample_end`	string	否	-	采样结束时间
`sound`	object	否	-	`sounds` 动作的声音生成参数

action 可选值

text

generate, extend, upload_generate, concat, replace_section,
upload_extend, stems, artist_consistency, cover, all_stems,
add_vocals, add_instrumental, upload_cover, mashup, remaster,
sample, inspiration, sounds

未在上方列出的 action 暂不支持调用。

model 可选值

text

chirp-v4-5, chirp-v3-5, chirp-v4, chirp-v4-5-plus,
chirp-v4-5-lite, chirp-v5, chirp-v5-5

参数长度限制

prompt 参数字符长度不得超过 1000。style 和 lyric 的长度限制与模型有关：

模型	`style` 长度限制	`lyric` 长度限制
`chirp-v3-5`	不得超过 200 字符	不得超过 1250 字符
`chirp-v4`	不得超过 200 字符	不得超过 3000 字符
`chirp-v4-5`, `chirp-v4-5-plus`, `chirp-v4-5-lite`, `chirp-v5`, `chirp-v5-5`	不得超过 1000 字符	不得超过 5000 字符

action 使用说明

action	用途	常用必填参数
`generate`	文本生成歌曲或自定义歌词生成歌曲	`prompt`, `model`；自定义模式通常还需要 `custom`, `style`, `lyric`, `title`
`extend`	基于已有歌曲继续生成	`audio_id`, `continue_at`, `model`；自定义续写通常还需要 `custom`, `lyric`, `origin_lyric`, `style`
`upload_generate`	通过外部音频 URL 上传后生成	`audio_url`, `model`, `custom`, `style`, `lyric`, `title`
`concat`	拼接续写片段，生成完整歌曲	`audio_id`, `continue_at`
`replace_section`	替换歌曲中的指定片段	`audio_id`, `prompt`, `replace_section_start`, `replace_section_end`
`upload_extend`	上传音频后续写	`audio_id`, `continue_at`, `model`
`stems`	获取人声/伴奏双音轨分离	`audio_id`
`all_stems`	获取更完整的分轨结果	`audio_id`
`artist_consistency`	基于 Persona 或指定音频生成一致风格歌曲	`lyric`, `style`, `model`，可搭配 `persona_id`
`cover`	基于已有歌曲生成翻唱	`audio_id`, `model`, `custom`, `lyric`, `style`，可搭配 `persona_id`
`add_vocals`	给纯音乐添加人声	`audio_id`, `lyric`, `style`, `model`, `custom`
`add_instrumental`	给人声添加伴奏	`audio_id`, `lyric`, `style`, `model`, `custom`
`upload_cover`	上传外部音频后生成翻唱	`audio_url`, `model`
`mashup`	多首歌曲混曲	`mashup_audio_ids`
`remaster`	对已有歌曲重新生成或增强	`audio_id`, `model`
`sample`	从已有音频中采样生成变体	`audio_id`, `sample_start`, `sample_end`
`inspiration`	基于已有歌曲生成灵感参考版本	`audio_id`, `model`
`sounds`	生成短声音、loop 或 one-shot	`sound`

以上为常用参数组合。不同模型或账号能力可能对参数有额外要求，具体以接口实际返回为准。

常见请求示例

灵感生成歌曲

根据用户输入的prompt进行歌曲生成，需要注意的是，若prompt有明确的说明需要纯音乐歌曲，那么instrumental参数可能不起作用

json

{
  "action": "generate",
  "prompt": "A bright pop song about city lights and summer rain",
  "model": "chirp-v4",
  "custom": false,
  "instrumental": false,
  "async_mode": false
}

自定义歌词生曲

json

{
  "action": "generate",
  "model": "chirp-v4",
  "custom": true,
  "instrumental": false,
  "title": "Summer Rain",
  "style": "bright city pop, warm synths, female vocal",
  "lyric": "[Verse]\nNeon lights are waking slowly\n[Chorus]\nWe dance into the summer rain",
  "async_mode": false
}

续写歌曲

如果要对已经生成的 Suno 歌曲继续生成，将 action 设置为 extend，并把需要续写的歌曲 ID 填入 audio_id。

歌曲 ID 可以从歌曲生成接口的响应中获取，对应字段为 data[].id：

json

{
  "data": [
    {
      "id": "7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4",
      "title": "新年快乐",
      "audio_url": "https://cdn1.suno.ai/7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4.mp3"
    }
  ]
}

续写时常用字段如下：

参数	说明
`action`	固定为 `extend`
`audio_id`	需要续写的歌曲 ID，可以是生成歌曲 ID，也可以是上传后得到的歌曲 ID
`continue_at`	从原歌曲第几秒开始续写，例如 `149` 表示从第 149 秒开始续写
`model`	使用的模型
`custom`	是否使用自定义续写；仅允许填写 `true`
`lyric`	续写部分的歌词文本
`origin_lyric`	原歌曲在 `0` 到 `continue_at` 片段内的歌词，用于帮助续写内容衔接原歌词,可以使用timing接口获取时间信息
`style`	歌曲风格，选填
`title`	歌曲标题，选填
`instrumental`	是否生成纯音乐
`persona_root_id`	创建 Persona 时的源歌曲 ID
`persona_id`	已创建的 Persona ID

如果想在续写的基础上使用歌手风格进行续写，通常需要同时传入 persona_root_id 和 persona_id，注意此时只允许使用自定义生成歌曲。

continue_at 的单位是秒。建议不要把续写起点设置得过于靠后，通常不要超过原歌曲时长的 70%，否则可能出现续写片段较短或衔接不理想的情况。

json

{
  "action": "extend",
  "instrumental": false,
  "custom": true,
  "model": "chirp-v4-5-plus",
  "lyric": "(Verse)\nThe weight of the world drifts off like a sigh\nI feel my spirit lift and start to fly\n\n(Chorus)\nBeneath the orange sky\nI let it all go",
  "origin_lyric": "[Verse]\nThere's a bird on a wire just watching the day\nClouds drift like ships\nThey're sailing away\n\n[Chorus]\nBeneath the orange sky\nI let it all go",
  "title": "Roots in the Sky",
  "style": "warm soul pop, gentle 72 BPM groove, intimate vocal, soft electric guitar",
  "audio_id": "707a09fc-8789-4087-b915-4493e86d8c59",
  "continue_at": 149,
  "async_mode": false
}

获取完整歌曲

基于原歌曲续写之后，返回的歌曲通常只包含续写片段，不包含原歌曲内容。如果需要获得完整歌曲，需要使用拼接功能，将 action 设置为 concat。

常用字段如下：

参数	说明
`action`	固定为 `concat`
`audio_id`	最后一个续写片段的歌曲 ID

例如最后一个续写片段的歌曲 ID 为 19ba4bb9-c90a-41ba-874d-40e5942e7d26，可以这样请求：

json

{
  "action": "concat",
  "audio_id": "19ba4bb9-c90a-41ba-874d-40e5942e7d26",
  "async_mode": false
}

返回结果是一首完整歌曲，也就是原歌曲和续写片段的拼接结果。示例如下：

json

{
  "success": true,
  "task_id": "ff73ed83-26d3-47bb-9793-825ac1172abc",
  "trace_id": "98315862-fa60-4fa4-99c7-e1e15e6e542c",
  "data": [
    {
      "id": "3e78b952-075a-46e8-a9ef-01193a7942b6",
      "title": "新年快乐",
      "image_url": "https://cdn2.suno.ai/image_19ba4bb9-c90a-41ba-874d-40e5942e7d26.jpeg",
      "lyric": "[Verse]\n挂灯笼 照亮每个街头\n...\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿",
      "audio_url": "https://cdn1.suno.ai/3e78b952-075a-46e8-a9ef-01193a7942b6.mp3",
      "video_url": "",
      "created_at": "2025-04-11T04:56:41.409Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "male vocals, chinese",
      "duration": 120.99997916666666,
      "concat_history": [
        {
          "id": "7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4",
          "continue_at": 1,
          "type": "gen",
          "source": "ios",
          "infill": false
        },
        {
          "id": "19ba4bb9-c90a-41ba-874d-40e5942e7d26"
        }
      ]
    }
  ]
}

获取人声分离

基于Pro池或者v4及以上模型的歌曲

当歌曲支持分轨能力时，可以使用 stems 获取人声和伴奏分离结果。该动作通常用于将一首歌曲拆分为 Vocals 和 Instrumental 两条音频。

常用字段如下：

参数	说明
`action`	固定为 `stems`
`audio_id`	需要分离的歌曲 ID

请求示例：

json

{
  "action": "stems",
  "audio_id": "4d6ddd0b-067a-4aa2-bb7d-1a720a3a0291",
  "async_mode": false
}

返回结果通常包含人声和伴奏两条音频。示例如下：

json

{
  "success": true,
  "task_id": "2bf3fb16-e11e-4b6c-988d-52d26937ade0",
  "trace_id": "aedcbc1d-7ae2-40c1-8e85-c6385ae17c69",
  "data": [
    {
      "id": "9e554197-385e-4d04-8d0b-9fd241e9c9b8",
      "title": "新年快乐 - Vocals",
      "image_url": "https://cdn2.suno.ai/image_9e554197-385e-4d04-8d0b-9fd241e9c9b8.jpeg",
      "lyric": "[Verse]\n灯笼挂满了窗外的枝头\n...\n[Chorus]\n新年快乐 大声说出口",
      "audio_url": "https://cdn1.suno.ai/9e554197-385e-4d04-8d0b-9fd241e9c9b8.mp3",
      "video_url": "",
      "created_at": "2025-05-06T15:40:44.238Z",
      "model": "",
      "state": "succeeded",
      "prompt": null,
      "style": "traditional influences, male and female vocals",
      "duration": 182.32
    },
    {
      "id": "89ddf096-c25a-45ba-bc46-771d6e374b7f",
      "title": "新年快乐 - Instrumental",
      "image_url": "https://cdn2.suno.ai/image_89ddf096-c25a-45ba-bc46-771d6e374b7f.jpeg",
      "lyric": "",
      "audio_url": "https://cdn1.suno.ai/89ddf096-c25a-45ba-bc46-771d6e374b7f.mp3",
      "video_url": "",
      "created_at": "2025-05-06T15:40:44.249Z",
      "model": "",
      "state": "succeeded",
      "prompt": null,
      "style": "traditional influences, male and female vocals",
      "duration": 182.32
    }
  ]
}

获取全音轨分离

如果需要更细粒度的分轨结果，可以使用 all_stems 获取全音轨分离。返回结果最多可能包含人声、和声、鼓、贝斯、吉他、键盘、打击乐、弦乐、合成器、FX、铜管、木管等音轨。

常用字段如下：

参数	说明
`action`	固定为 `all_stems`
`audio_id`	需要全音轨分离的歌曲 ID

请求示例：

json

{
  "action": "all_stems",
  "audio_id": "46e802a0-5b3c-4826-9994-91a4b3293ca9",
  "async_mode": false
}

返回结果示例如下：

json

{
  "success": true,
  "task_id": "25e89821-24a6-4244-a849-79fd338f9e98",
  "trace_id": "c1e582d0-d5e2-4ffb-aeb4-093039e0720a",
  "data": [
    {
      "id": "ddf370fe-2b31-4d6a-8bf7-1db594c17c20",
      "title": " (Vocals)",
      "image_url": "https://cdn2.suno.ai/image_ddf370fe-2b31-4d6a-8bf7-1db594c17c20.jpeg",
      "lyric": "[Verse]\nThe clock is ticking loud and clear\n...",
      "audio_url": "https://cdn1.suno.ai/ddf370fe-2b31-4d6a-8bf7-1db594c17c20.mp3",
      "video_url": "",
      "created_at": "2025-09-04T03:54:51.697Z",
      "model": "chirp-ahi",
      "state": "succeeded",
      "style": "",
      "metadata": {
        "stem_type_group_name": "Vocals",
        "stem_from_id": "46e802a0-5b3c-4826-9994-91a4b3293ca9",
        "stem_task": "twelve"
      },
      "duration": 177.64
    },
    {
      "id": "958e9060-40a3-4bf7-a7c1-30f77f300fc9",
      "title": " (Drums)",
      "image_url": "https://cdn2.suno.ai/image_958e9060-40a3-4bf7-a7c1-30f77f300fc9.jpeg",
      "lyric": "",
      "audio_url": "https://cdn1.suno.ai/958e9060-40a3-4bf7-a7c1-30f77f300fc9.mp3",
      "video_url": "",
      "created_at": "2025-09-04T03:54:51.697Z",
      "model": "chirp-ahi",
      "state": "succeeded",
      "style": "",
      "metadata": {
        "stem_type_group_name": "Drums",
        "stem_from_id": "46e802a0-5b3c-4826-9994-91a4b3293ca9",
        "stem_task": "twelve"
      },
      "duration": 177.64
    }
  ]
}

metadata.stem_type_group_name 表示当前音轨类型，例如 Vocals、Drums、Bass、Guitar 等。实际返回的音轨数量以接口结果为准。

音频上传

音频上传拆分为独立的自定义歌曲上传板块。请点击跳转查看 POST /suno/upload 的请求参数、示例和响应说明。

自定义上传歌曲生成

如果要基于自己上传的音乐继续生成或扩展歌曲，可以使用 upload_generate。该动作会读取你提供的音频 URL，并结合歌词和风格生成新的歌曲。

常用字段如下：

参数	说明
`action`	固定为 `upload_generate`
`audio_url`	自定义上传歌曲的音频链接，必填
`model`	使用的模型
`custom`	是否使用自定义生成；仅允许填写 `true`
`lyric`	歌词文本
`title`	歌曲标题
`style`	歌曲风格，选填
`continue_at`	从上传音频第几秒开始生成，单位为秒
`instrumental`	是否生成纯音乐

continue_at 必须大于 0。通常不要超过原音频时长的 70%，否则可能出现生成片段较短或衔接不理想的情况。

如果先使用上面的音频上传接口获取了歌曲 ID，此时如果要继续生成，应使用 upload_extend，并传入 audio_id，而不是继续传 audio_url。

upload_generate 请求示例：

json

{
  "action": "upload_generate",
  "custom": true,
  "instrumental": false,
  "audio_url": "https://example.com/test.mp3",
  "title": "Lost and Found",
  "style": "warm pop, male vocal, bright guitars",
  "lyric": "[Verse]\nRunning down the alley where the shadows play\n[Chorus]\nLost and found I'm spinning around",
  "continue_at": 70,
  "model": "chirp-v4",
  "async_mode": false
}

upload_extend 请求示例：

json

{
  "action": "upload_extend",
  "custom": true,
  "instrumental": false,
  "audio_id": "uploaded-audio-id",
  "title": "Lost and Found",
  "style": "warm pop, male vocal, bright guitars",
  "lyric": "[Verse]\nRunning down the alley where the shadows play\n[Chorus]\nLost and found I'm spinning around",
  "continue_at": 70,
  "model": "chirp-v4",
  "async_mode": false
}

响应示例：

json

{
  "success": true,
  "task_id": "20735a95-90aa-497f-ba7d-f53cb870f19d",
  "trace_id": "e4a085dd-e029-48f8-b182-04ad5c32962a",
  "data": [
    {
      "id": "ab735d10-2708-4d5e-a8e9-61e14f1c5b12",
      "title": "Lost and Found",
      "image_url": "https://cdn2.suno.ai/image_ab735d10-2708-4d5e-a8e9-61e14f1c5b12.jpeg",
      "lyric": "[Verse]\nRunning down the alley where the shadows play\n...\n[Chorus]\nLost and found I'm spinning around",
      "audio_url": "https://cdn1.suno.ai/ab735d10-2708-4d5e-a8e9-61e14f1c5b12.mp3",
      "video_url": "",
      "created_at": "2025-04-12T10:38:32.131Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "boy",
      "style": "male vocals, pop",
      "duration": 200.16
    },
    {
      "id": "7a61a147-0715-4cdd-b68e-cfd047e45251",
      "title": "Lost and Found",
      "image_url": "https://cdn2.suno.ai/image_7a61a147-0715-4cdd-b68e-cfd047e45251.jpeg",
      "lyric": "[Verse]\nRunning down the alley where the shadows play\n...",
      "audio_url": "https://cdn1.suno.ai/7a61a147-0715-4cdd-b68e-cfd047e45251.mp3",
      "video_url": "",
      "created_at": "2025-04-12T10:38:32.131Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "boy",
      "style": "male vocals, pop",
      "duration": 172.4
    }
  ]
}

音乐翻唱

如果要对已经生成的歌曲进行翻唱，可以使用 cover。翻唱会基于原歌曲生成新的演唱版本，适用于原歌曲风格不合适、想更换演唱风格或结合 Persona 声音风格的场景。

常用字段如下：

参数	说明
`action`	固定为 `cover`
`audio_id`	需要翻唱的歌曲 ID
`model`	使用的模型
`custom`	是否使用自定义生成；仅允许填写 `true`
`lyric`	翻唱使用的歌词
`style`	翻唱后的歌曲风格
`persona_root_id`	创建 Persona 时的源歌曲 ID
`persona_id`	已创建的 Persona ID

如果要在翻唱时使用歌手风格，通常需要同时传入 persona_root_id 和 persona_id。

请求示例：

json

{
  "action": "cover",
  "custom": true,
  "lyric": "girl girl girl",
  "style": "rock, punk",
  "model": "chirp-v4-5",
  "audio_id": "84ad2f40-4cae-42fa-8a74-8117edbfd6fc",
  "async_mode": false
}

响应示例：

json

{
  "success": true,
  "task_id": "6dc758f8-d574-4fb4-bc10-439fefb25e6c",
  "trace_id": "a9d007ef-6a62-4709-bfe2-4ba7837d5476",
  "data": [
    {
      "id": "61d120bf-4249-425a-9526-adb561767a79",
      "title": "Girl Girl Girl",
      "image_url": "https://cdn2.suno.ai/image_61d120bf-4249-425a-9526-adb561767a79.jpeg",
      "lyric": "[Verse]\nShe's got fire in her eyes so wild\n...\n[Chorus]\nGirl girl girl she's a lightning storm",
      "audio_url": "https://cdn1.suno.ai/61d120bf-4249-425a-9526-adb561767a79.mp3",
      "video_url": "",
      "created_at": "2025-05-13T08:52:44.828Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "girl girl girl",
      "style": "pop, female vocals",
      "duration": 162.56
    },
    {
      "id": "c0c147cc-0304-4aac-b212-bb9de869400e",
      "title": "Girl Girl Girl",
      "image_url": "https://cdn2.suno.ai/image_c0c147cc-0304-4aac-b212-bb9de869400e.jpeg",
      "lyric": "[Verse]\nShe's got fire in her eyes so wild\n...",
      "audio_url": "https://cdn1.suno.ai/c0c147cc-0304-4aac-b212-bb9de869400e.mp3",
      "video_url": "",
      "created_at": "2025-05-13T08:52:44.828Z",
      "model": "chirp-auk",
      "state": "succeeded",
      "prompt": "girl girl girl",
      "style": "pop, female vocals",
      "duration": 189.08
    }
  ]
}

片段替换

当生成歌曲后，需要对某个片段单独替换或二次创作时，可以使用 replace_section。该动作会针对指定时间范围生成替换片段。

常用字段如下：

参数	说明
`action`	固定为 `replace_section`
`audio_id`	需要替换片段的歌曲 ID
`model`	使用的模型
`prompt`	要替换后的歌词或修改提示，需要与 `lyric` 中的内容有重叠
`lyric`	替换后的上下文歌词，包含 `prompt` 对应的歌词内容
`full_lyric`	替换后的完整歌词；如果未改动其他歌词，保留原完整歌词并替换目标片段即可
`style`	歌曲风格，选填
`custom`	是否使用自定义生成；仅允许填写 `true`
`replace_section_start`	替换片段起始时间，单位为秒
`replace_section_end`	替换片段结束时间，单位为秒

建议先通过歌词时间轴接口获取歌词对应的时间信息，再确定 replace_section_start 和 replace_section_end。替换片段时长建议不小于 2.5 秒，最长不超过 120 秒；时间范围需要与 lyric 中被替换的歌词片段对应，间隔过大可能导致替换效果不理想或请求失败。

prompt 是 lyric 的子集，通常只填写需要修改后的核心歌词；lyric 则填写替换片段的上下文歌词，不需要很长，但需要包含 prompt 内容。

请求示例：

json

{
  "action": "replace_section",
  "instrumental": false,
  "custom": true,
  "prompt": "（Chorus）向光而行！",
  "model": "chirp-v4-5-plus",
  "lyric": "【Pre-Chorus】（Warm Group Vocals）\r\n霓虹把雨点照亮\r\n脚步穿过长街回响\r\n我把犹豫放进风里\r\n（Chorus）向光而行！\r\n穿过云层和夜色的缝隙\r\n让心跳追上黎明\r\n",
  "title": "《城市夜航》",
  "style": "Mandopop Rock, Synthwave, Hopeful Anthem",
  "audio_id": "9f4a6d21-8c73-4f1b-9a62-3d6f0c8e1257",
  "persona_id": "",
  "continue_at": 0,
  "style_negative": null,
  "audio_url": "",
  "persona_root_id": null,
  "full_lyric": "窗外的雨落在高架桥\r\n车灯像河流慢慢燃烧\r\n我听见远处的风在叫\r\n提醒我别停靠\r\n【Pre-Chorus】（Warm Group Vocals）\r\n霓虹把雨点照亮\r\n脚步穿过长街回响\r\n我把犹豫放进风里\r\n（Chorus）向光而行！\r\n穿过云层和夜色的缝隙\r\n让心跳追上黎明\r\n【Outro】\r\n城市还醒着\r\n我也继续向前走",
  "replace_section_start": 74.25,
  "replace_section_end": 78.9,
  "vocal_gender": null,
  "async_mode": false
}

响应返回的是替换后的片段歌曲，通常不是完整歌曲。如果需要得到完整替换后的歌曲，可以再使用上文的获取完整歌曲方式进行拼接。

响应示例：

json

{
  "success": true,
  "task_id": "6fb1713d-a4d1-476a-9791-66750dbc9695",
  "trace_id": "22d6bcb0-b823-45bd-8e50-3b4b1cf22016",
  "data": [
    {
      "id": "ec286375-2b34-445d-a485-60c08d31693b",
      "title": "《乌蒙好汉》",
      "image_url": "https://cdn2.suno.ai/image_ec286375-2b34-445d-a485-60c08d31693b.jpeg",
      "lyric": "【Verse 2】（Group Vocals + Suona Lead）\r\n战鼓擂起来（喝）\r\n...\r\n（Chorus）就是干！",
      "audio_url": "https://cdn1.suno.ai/ec286375-2b34-445d-a485-60c08d31693b.mp3",
      "video_url": "",
      "created_at": "2025-09-30T03:50:41.678Z",
      "model": "chirp-bluejay",
      "state": "succeeded",
      "style": "Folk Rock，Ethnic Fusion，Heroic Anthem",
      "duration": 6.96
    },
    {
      "id": "00dc0e5e-9657-4718-971c-95c9ec505e92",
      "title": "《乌蒙好汉》",
      "image_url": "https://cdn2.suno.ai/image_00dc0e5e-9657-4718-971c-95c9ec505e92.jpeg",
      "lyric": "【Verse 2】（Group Vocals + Suona Lead）\r\n战鼓擂起来（喝）\r\n...\r\n（Chorus）就是干！",
      "audio_url": "https://cdn1.suno.ai/00dc0e5e-9657-4718-971c-95c9ec505e92.mp3",
      "video_url": "",
      "created_at": "2025-09-30T03:50:41.678Z",
      "model": "chirp-bluejay",
      "state": "succeeded",
      "style": "Folk Rock，Ethnic Fusion，Heroic Anthem",
      "duration": 6.96
    }
  ]
}

自定义歌曲添加人声

如果已有一首自定义上传或生成的纯音乐歌曲，可以使用 add_vocals 为歌曲添加人声。该动作需要传入歌曲 ID，并提供要加入的人声歌词内容。

常用字段如下：

参数	说明
`action`	固定为 `add_vocals`
`audio_id`	需要添加人声的歌曲 ID
`model`	使用的模型
`lyric`	需要添加的人声歌词
`custom`	是否使用自定义模式；仅允许填写 `true`
`style`	人声或歌曲风格
`weirdness`	创意随机参数
`audio_influence`	音频影响参数；需要在已有歌曲基础上使用
`style_influence`	风格影响参数
`overpainting_start`	添加人声片段的起始时间，单位为秒
`overpainting_end`	添加人声片段的结束时间，单位为秒
`vocal_gender`	人声性别，`m` 表示男声，`f` 表示女声

chirp-v4-5 及以上模型支持同时传入 weirdness、audio_influence、style_influence、vocal_gender 等高级参数。audio_influence 通常需要基于已有歌曲生成时才会生效。

请求示例：

json

{
  "action": "add_vocals",
  "model": "chirp-v4-5",
  "audio_id": "9d54b289-0c45-477e-a8b3-5e77498c65e7",
  "lyric": "[Verse 1]\nKini ku telah bebas\nDosa telah dipatahkan\nYesus hidup Dia menang",
  "custom": true,
  "style": "male vocal, gospel pop, warm choir",
  "weirdness": 0.3,
  "audio_influence": 0.3,
  "style_influence": 0.3,
  "overpainting_start": 0,
  "overpainting_end": 10,
  "vocal_gender": "m",
  "async_mode": false
}

自定义歌曲添加伴奏

如果已有一首自定义上传或生成的人声歌曲，可以使用 add_instrumental 为歌曲添加伴奏。该动作需要传入歌曲 ID，并通过风格和高级参数控制伴奏生成效果。

常用字段如下：

参数	说明
`action`	固定为 `add_instrumental`
`audio_id`	需要添加伴奏的歌曲 ID
`model`	使用的模型
`lyric`	原歌曲歌词或人声对应歌词
`custom`	是否使用自定义模式；仅允许填写 `true`
`style`	伴奏或歌曲风格
`weirdness`	创意随机参数
`audio_influence`	音频影响参数；需要在已有歌曲基础上使用
`style_influence`	风格影响参数
`underpainting_start`	添加伴奏片段的起始时间，单位为秒
`underpainting_end`	添加伴奏片段的结束时间，单位为秒

chirp-v4-5 及以上模型支持同时传入 weirdness、audio_influence、style_influence 等高级参数。可以通过 style_influence 控制伴奏风格贴合程度，通过 audio_influence 控制对原音频的参考程度。

请求示例：

json

{
  "action": "add_instrumental",
  "model": "chirp-v4-5",
  "audio_id": "9d54b289-0c45-477e-a8b3-5e77498c65e7",
  "lyric": "[Verse 1]\nKini ku telah bebas\nDosa telah dipatahkan\nYesus hidup Dia menang",
  "custom": true,
  "style": "uplifting gospel pop, piano, warm drums, choir atmosphere",
  "weirdness": 0.3,
  "audio_influence": 0.3,
  "style_influence": 0.3,
  "underpainting_start": 0,
  "underpainting_end": 10,
  "async_mode": false
}

自定义混曲生成

如果要将两首歌曲进行混合生成，可以使用 mashup。该动作需要传入两首歌曲的 ID，并通过自定义模式填写混合后的歌词与风格。

混合歌词可以先通过歌词生成接口获取，再作为 lyric 传入。

常用字段如下：

参数	说明
`action`	固定为 `mashup`
`mashup_audio_ids`	需要混合的歌曲 ID 列表，通常传入两首歌曲
`model`	使用的模型
`custom`	是否使用自定义模式；仅允许填写 `true`
`lyric`	混合生成使用的歌词
`title`	歌曲标题
`style`	混合后的歌曲风格
`instrumental`	是否生成纯音乐

请求示例：

json

{
  "action": "mashup",
  "instrumental": false,
  "custom": true,
  "model": "chirp-v4-5",
  "lyric": "(Intro) Flicker lights on a midnight screen\nThe weight of the world fades into the bassline",
  "title": "Family Legacy",
  "style": "Reggae Groove in E minor, skanking guitar, soulful bass",
  "mashup_audio_ids": [
    "7a7e73d1-963f-4249-ac22-30ef60cb26ba",
    "e8403a40-d2ff-4bce-a7c5-178249ff663b"
  ],
  "async_mode": false
}

Remaster 生成

如果要对已有歌曲进行重新生成或增强，可以使用 remaster。该动作适合在保留原歌曲基础的同时调整清晰度、质感或整体表现。

常用字段如下：

参数	说明
`action`	固定为 `remaster`
`audio_id`	需要重新生成的歌曲 ID
`model`	使用的模型；常用 `chirp-v4-5-plus` 或 `chirp-v5`
`variation_category`	变体强度，常见值为 `subtle`、`normal`、`high`；通常在 `model` 为 `chirp-v5` 时使用

请求示例：

json

{
  "action": "remaster",
  "model": "chirp-v5",
  "variation_category": "subtle",
  "audio_id": "85a4bb34-9218-46c8-818e-90443713363b",
  "async_mode": false
}

自定义采样歌曲生成

如果要根据已有歌曲中的某个片段进行采样生成，可以使用 sample。该动作需要传入采样歌曲 ID，以及采样起止时间。

常用字段如下：

参数	说明
`action`	固定为 `sample`
`audio_id`	被采样的歌曲 ID
`sample_start`	采样起始时间，单位为秒
`sample_end`	采样结束时间，单位为秒
`model`	使用的模型
`custom`	是否使用自定义模式；仅允许填写 `true`
`lyric`	采样生成使用的歌词
`title`	歌曲标题
`style`	歌曲风格
`instrumental`	是否生成纯音乐

请求示例：

json

{
  "model": "chirp-v5",
  "action": "sample",
  "lyric": "(Verse)\nThe weight of the world drifts off like a sigh\nI feel my spirit lift and start to fly",
  "title": "Roots in the Sky",
  "style": "A gently breathing 72 BPM pulse, intimate golden-hour warmth",
  "custom": true,
  "instrumental": false,
  "sample_start": 50,
  "sample_end": 60,
  "audio_id": "7e01b40b-2a00-48d9-a0c2-f74407dd902d",
  "async_mode": false
}

自定义 Inspiration 生成

如果要基于一首歌曲生成灵感参考版本，可以使用 inspiration。该动作可用于生成 Persona 备选方案，或参考已有歌曲的人声与风格进行新的创作。

常用字段如下：

参数	说明
`action`	固定为 `inspiration`
`audio_id`	参考歌曲 ID，也可以是上传后得到的歌曲 ID
`model`	使用的模型
`custom`	是否使用自定义模式；仅允许填写 `true`
`lyric`	生成使用的歌词
`title`	歌曲标题
`style`	歌曲风格
`instrumental`	是否生成纯音乐

请求示例：

json

{
  "model": "chirp-v4",
  "action": "inspiration",
  "lyric": "(Verse)\nThe weight of the world drifts off like a sigh\nI feel my spirit lift and start to fly",
  "title": "Roots in the Sky",
  "style": "warm soul pop, gentle 72 BPM groove, intimate vocal",
  "custom": true,
  "instrumental": false,
  "audio_id": "e9da41f8-61f8-4244-9283-e2f5d85a1b04",
  "async_mode": false
}

自定义歌手风格生成

如果要使用已创建的 Persona 歌手风格生成歌曲，可以使用 artist_consistency。使用前请先在 Persona 创建页面创建 Persona，并保存返回的 persona_id 和 audio_id。

常用字段如下：

参数	说明
`action`	固定为 `artist_consistency`
`audio_id`	Persona 来源歌曲 ID，通常使用创建 Persona 时返回或使用的歌曲 ID
`persona_id`	已创建的 Persona ID
`persona_root_id`	Persona 来源歌曲 ID，通常与 `audio_id` 保持一致
`model`	使用的模型
`lyric`	生成歌曲使用的歌词
`title`	歌曲标题
`style`	歌曲风格
`custom`	是否使用自定义模式；仅允许填写 `true`
`instrumental`	是否生成纯音乐
`persona_type`	Persona 类型；真人 Voice 或 Vox Persona 通常传 `vox`

普通 Persona 请求示例：

json

{
  "action": "artist_consistency",
  "model": "chirp-v4-5",
  "custom": true,
  "instrumental": false,
  "title": "新年快乐",
  "style": "Chinese pop, festive, warm group vocals",
  "lyric": "[Verse]\n灯火照亮回家的路\n[Chorus]\n新年快乐 一起唱到天明",
  "audio_id": "04734644-d4c8-4d1e-ac53-be95289c5b6b",
  "persona_root_id": "04734644-d4c8-4d1e-ac53-be95289c5b6b",
  "persona_id": "89f20346-51f0-4b35-a88e-ed8fa5bb5cac",
  "async_mode": false
}

Vox Persona 或真人 Voice 请求示例：

json

{
  "action": "artist_consistency",
  "model": "chirp-v5-5",
  "custom": true,
  "instrumental": false,
  "title": "Voice in the Morning",
  "style": "Acoustic pop, intimate vocal, soft piano",
  "lyric": "[Verse]\nMorning light is touching my window\n[Chorus]\nI hear your voice and start again",
  "audio_id": "aca20afa-0e70-4428-b54d-d138f70fb238",
  "persona_id": "b224d9c9-d23d-4425-803b-9af41f94d3e1",
  "persona_type": "vox",
  "async_mode": false
}

自定义创建 Sounds

如果要创建短音效、loop 或 one-shot 声音素材，可以使用 sounds。该动作通过 sound 对象描述要生成的声音，不用于完整歌曲生成。

常用字段如下：

参数	说明
`action`	固定为 `sounds`
`sound`	声音生成参数对象
`model`	使用的模型

请求示例：

json

{
  "action": "sounds",
  "sound": {
    "description": "A deep bass drop with warm analog texture",
    "type": "one_shot",
    "key": "F#",
    "bpm": 120
  },
  "model": "chirp-v5",
  "async_mode": false
}

Sound 参数说明

参数	类型	必填	说明	示例
`sound.description`	string	是	描述你想要的音频，是声音生成的核心输入，也会作为标题来源；如果太长可能会被截断	`A deep bass drop with warm analog texture`
`sound.type`	string	否	音频类型，默认 `one_shot`；可选值：`one_shot`、`loop`	`one_shot`
`sound.key`	string	否	音乐调性，不填时默认为 `Any`；可填写如 `C`、`C maj`、`C min`、`F#`、`A min` 等	`F#`
`sound.bpm`	number	否	BPM / 节奏速度；不填时默认自动选择，取值范围 1 到 300，常见音乐 BPM 在 60 到 200 之间	`120`

Python 示例

python

import requests

url = "https://your-domain.com/suno/audios"
headers = {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "action": "generate",
    "prompt": "A bright pop song about city lights and summer rain",
    "model": "chirp-v4",
    "async_mode": False,
}

response = requests.post(url, headers=headers, json=payload)
print(response.status_code)
print(response.text)

响应说明

异步模式下通常会返回 task_id，拿到后可通过任务查询获取结果。

同步模式或部分动作可能直接返回结果。常见字段包括：

字段	说明
`success`	请求是否成功受理
`task_id`	异步任务 ID
`trace_id`	请求追踪 ID，排查问题时可一并提供
`data`	生成歌曲列表，包含歌曲详情
`data[].state`	歌曲生成状态，常见值见下方状态说明
`data[].id`	歌曲 ID，可用于续写、翻唱、分轨、视频、WAV、SRT 等后续接口
`data[].title`	歌曲标题
`data[].image_url`	歌曲封面图片 URL
`data[].lyric`	歌词
`data[].audio_url`	歌曲音频文件 URL，通常为 MP3
`data[].video_url`	歌曲视频文件 URL，通常为 MP4；为空表示当前未生成视频
`data[].created_at`	创建时间
`data[].model`	使用的模型
`data[].prompt`	生成提示词
`data[].style`	歌曲风格
`data[].duration`	歌曲时长，单位为秒

state 常见取值：

状态	说明
`succeeded`	生成成功
`pending`	队列中
`running`	执行中
`error`	生成失败

最终响应内容以接口实际返回为准。

响应示例

json

{
  "success": true,
  "task_id": "4226ba3a-c168-464e-b2db-18b32b17335a",
  "trace_id": "cb108c23-1b32-4fa4-99c7-e1e15e6e542c",
  "data": [
    {
      "id": "7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4",
      "title": "新年快乐",
      "image_url": "https://cdn2.suno.ai/image_7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4.jpeg",
      "lyric": "[Verse]\n挂灯笼 照亮每个街头\n福字倒 福气满到家门口\n...\n[Chorus]\n新年快乐 心愿齐欢歌\n祝福今天照亮每一刻",
      "audio_url": "https://cdn1.suno.ai/7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4.mp3",
      "video_url": "",
      "created_at": "2025-04-11T04:47:14.486Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "新年快乐",
      "style": "male vocals, chinese",
      "duration": 134.8
    },
    {
      "id": "b423fb9a-99e0-4e1b-97cd-54c62e5041bc",
      "title": "新年快乐",
      "image_url": "https://cdn2.suno.ai/image_b423fb9a-99e0-4e1b-97cd-54c62e5041bc.jpeg",
      "lyric": "[Verse]\n挂灯笼 照亮每个街头\n福字倒 福气满到家门口\n...",
      "audio_url": "https://cdn1.suno.ai/b423fb9a-99e0-4e1b-97cd-54c62e5041bc.mp3",
      "video_url": "",
      "created_at": "2025-04-11T04:47:14.486Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "新年快乐",
      "style": "male vocals, chinese",
      "duration": 148.96
    }
  ]
}

扣费说明

计费项	参考积分
歌曲生成	10

Suno 音频任务 ​

接口地址 ​

通用说明 ​

通用参数 ​

action 可选值 ​

model 可选值 ​

参数长度限制 ​

action 使用说明 ​

常见请求示例 ​

灵感生成歌曲 ​

自定义歌词生曲 ​

续写歌曲 ​

获取完整歌曲 ​

获取人声分离 ​

获取全音轨分离 ​

音频上传 ​

自定义上传歌曲生成 ​

音乐翻唱 ​

片段替换 ​

自定义歌曲添加人声 ​

自定义歌曲添加伴奏 ​

自定义混曲生成 ​

Remaster 生成 ​

自定义采样歌曲生成 ​

自定义 Inspiration 生成 ​

自定义歌手风格生成 ​

自定义创建 Sounds ​

Sound 参数说明 ​

Python 示例 ​

响应说明 ​

响应示例 ​

扣费说明 ​

Suno 音频任务

接口地址

通用说明

通用参数

action 可选值

model 可选值

参数长度限制

action 使用说明

常见请求示例

灵感生成歌曲

自定义歌词生曲

续写歌曲

获取完整歌曲

获取人声分离

获取全音轨分离

音频上传

自定义上传歌曲生成

音乐翻唱

片段替换

自定义歌曲添加人声

自定义歌曲添加伴奏

自定义混曲生成

Remaster 生成

自定义采样歌曲生成

自定义 Inspiration 生成

自定义歌手风格生成

自定义创建 Sounds

Sound 参数说明

Python 示例

响应说明

响应示例

扣费说明