Suno 歌曲生成 API 对接说明

基本使用

想些什么歌曲，可以任意输入一段文字，比如我想生成一个关于新年快乐的歌曲，就可以输入 新年快乐，下面使用apifox进行发送请求，具体的参数如图所示：

如果你想体验Suno最新模型4.5或者Stems、Wav功能需要使用Pro池来生成，与普通池的区别就是将参数is_pro设置为true,该值默认是false，Pro池要比普通池要贵哦，可以自己通过is_pro控制，具体的参数如图所示：

可以点击发送按钮直接测试 API，稍等 1-2 分钟，结果如下：

{
    "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烟花飞 夜空美到心头\n[Verse 2]\n舞龙起 红色翻跃天空\n狮鼓敲 热闹暖暖人心中\n笑开怀 送祝福到意浓\n团圆饭 温热全家梦\n[Chorus]\n新年快乐 心愿齐欢歌\n祝福今天照亮每一刻\n梦想点燃 像烟花的火\n新年到来 快乐你和我\n[Verse 3]\n瑞雪飘 给岁月涂上白\n花儿开 宛如新的期待\n手牵手 不论东西南北\n我们一起 把幸福年代彩排\n[Bridge]\n一年忙碌 此刻都抛开\n让喜悦在心中蔓延发芽开\n拥抱未来 我们种下爱\n新的一年 全世界盛开\n[Chorus]\n新年快乐 心愿齐欢歌\n祝福今天照亮每一刻\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鞭炮响 震散旧年的哀愁\n烟花飞 夜空美到心头\n[Verse 2]\n舞龙起 红色翻跃天空\n狮鼓敲 热闹暖暖人心中\n笑开怀 送祝福到意浓\n团圆饭 温热全家梦\n[Chorus]\n新年快乐 心愿齐欢歌\n祝福今天照亮每一刻\n梦想点燃 像烟花的火\n新年到来 快乐你和我\n[Verse 3]\n瑞雪飘 给岁月涂上白\n花儿开 宛如新的期待\n手牵手 不论东西南北\n我们一起 把幸福年代彩排\n[Bridge]\n一年忙碌 此刻都抛开\n让喜悦在心中蔓延发芽开\n拥抱未来 我们种下爱\n新的一年 全世界盛开\n[Chorus]\n新年快乐 心愿齐欢歌\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
        }
    ]
}

可以看到这时候我们就得到了两首歌的内容，包括标题、预览图、歌词、音频、视频等内容。

字段说明如下：

• success：生成是否成功，如果成功则为 true，否则为 false
• data：是一个列表，包含了生成的歌曲的详细信息。
  • state： 歌曲生成状态，主要包含四种，具体的如下：
    • succeeded：生成成功
    • pending：队列中
    • running：执行中
    • error：失败
  • id：歌曲 ID
  • title：歌曲的标题
  • image_url：歌曲的封面图片
  • lyric：歌曲的歌词
  • audio_url：歌曲的音频文件，打开就是一个 mp3 音频。
  • video_url：歌曲的视频文件，打开就是一个 mp4 视频。
  • created_at：创建的时间
  • model：使用的模型，一般是最新的 v3 模型
  • style：风格

自定义生成

如果想自定义生成歌词，可以输入歌词：

这时候 lyric 字段可以传入类似如下内容：

[Verse]\nSnowflakes falling all around\nGlistening white\nCovering the ground\nChildren laughing\nFull of delight\nIn this winter wonderland tonight\nSanta's sleigh\nUp in the sky\nRudolph's nose shining bright\nOh my\nHear the jingle bells\nRinging so clear\nBringing joy and holiday cheer\n[Verse 2]\nRoasting chestnuts by the fire's glow\nChristmas lights\nThey twinkle and show\nFamilies gathering with love and cheer\nSpreading warmth to everyone near

注意，这里的歌词中 \n 是换行符，如果你不知道如何生成歌词，可以使用 SunoHub 提供的歌词生成 API 来通过 prompt 生成歌词。

接下来我们要根据歌词、标题、风格自定义生成歌曲，就可以指定如下内容：

• lyric：歌词文本
• custom：填写为 true，代表自定义生成，该参数默认为 false，代表使用 prompt 生成。
• title：歌曲的标题。
• style：歌曲的风格，选填。

填写样例如下：

最后发送请求，生成的效果是类似的。

继续生成功能

如果想对已经生成的Suno歌曲进行继续生成的话，可以将参数 action 设置为 extend ，并且输入需要继续生成歌曲的 ID，歌曲 ID 的获取是根据基本使用来获取，如下图所示：

这时候可以看到歌曲的 ID 为：

"id": "7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4"

注意，这里的歌词中 id 是生成后歌曲的 ID，如果你不知道如何生成歌曲，可以参考上文的基本使用来生成歌曲。

接下来我们要必须填歌词、风格自定义生成歌曲，就可以指定如下内容：

• lyric：歌词文本
• custom：填写为 true，代表自定义生成，该参数默认为 false，代表使用 prompt 生成。
• style：歌曲的风格，选填。
• continue_at：以秒为单位继续现有音频的时间。例如，213.5 表示继续到 3 分 33.5 秒。

填写样例如下：

点击发送，可以发现会得到一个结果，如下：

{
    "success": true,
    "task_id": "d2a78118-6631-4c2d-97f6-9b95cb9624ca",
    "trace_id": "2549ebb7-1d90-4f3c-9bd4-c8b2954fd830",
    "data": [
        {
            "id": "19ba4bb9-c90a-41ba-874d-40e5942e7d26",
            "title": "唱的更愉快一点",
            "image_url": "https://cdn2.suno.ai/image_19ba4bb9-c90a-41ba-874d-40e5942e7d26.jpeg",
            "lyric": "[Verse]\n天空飘着快乐的云彩\n脚下踩着跳跃的节拍\n阳光洒满大街每个角落\n心中冒出几朵好颜色\n[Verse 2]\n微风吹来像糖的味道\n每个人的脸上挂着微笑\n你伸出手牵着欢乐跑\n烦恼全都甩到很远的桥\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿\n让每个瞬间都值千金\n快乐无敌 没有原因\n[Verse 3]\n日子像串糖葫芦那么甜\n迷路也能变成探险\n光影在手腕上画旋转\n每一个动作都像跳舞般\n[Bridge]\n闭上眼让音乐直入心灵\n转圈圈看世界悄悄微倾\n星星眨眼悄悄为你打气\n这感觉让人不愿暂停\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿\n拥抱未来没有不可能\n快乐传染 一起狂奔",
            "audio_url": "https://cdn1.suno.ai/19ba4bb9-c90a-41ba-874d-40e5942e7d26.mp3",
            "video_url": "",
            "created_at": "2025-04-11T04:52:44.490Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "prompt": "唱的更愉快一点，更高兴一点",
            "style": "playful, chinese lyrics, pop",
            "duration": 120
        },
        {
            "id": "fa2273c4-894f-4445-be27-4a908a513ec5",
            "title": "唱的更愉快一点",
            "image_url": "https://cdn2.suno.ai/image_fa2273c4-894f-4445-be27-4a908a513ec5.jpeg",
            "lyric": "[Verse]\n天空飘着快乐的云彩\n脚下踩着跳跃的节拍\n阳光洒满大街每个角落\n心中冒出几朵好颜色\n[Verse 2]\n微风吹来像糖的味道\n每个人的脸上挂着微笑\n你伸出手牵着欢乐跑\n烦恼全都甩到很远的桥\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿\n让每个瞬间都值千金\n快乐无敌 没有原因\n[Verse 3]\n日子像串糖葫芦那么甜\n迷路也能变成探险\n光影在手腕上画旋转\n每一个动作都像跳舞般\n[Bridge]\n闭上眼让音乐直入心灵\n转圈圈看世界悄悄微倾\n星星眨眼悄悄为你打气\n这感觉让人不愿暂停\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿\n拥抱未来没有不可能\n快乐传染 一起狂奔",
            "audio_url": "https://cdn1.suno.ai/fa2273c4-894f-4445-be27-4a908a513ec5.mp3",
            "video_url": "",
            "created_at": "2025-04-11T04:52:44.490Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "prompt": "唱的更愉快一点，更高兴一点",
            "style": "playful, chinese lyrics, pop",
            "duration": 120
        }
    ]
}

可以看出，结果内容与上文的是一致的，这也就实现歌曲的继续生成功能，但如果想获取继续生成的完整歌曲还需要使用下面的拼接功能来获取。

获取完整歌曲

当基于原有的歌曲继续生成歌曲之后，返回的歌曲并不包含原来的歌曲内容。如果要获得完整的歌曲内容，需要使用拼接功能，就可以指定如下内容：

• action：内容为 concat。
• audio_id：最后一个片段的 ID。

比如扩展后的歌曲 ID 是：19ba4bb9-c90a-41ba-874d-40e5942e7d26，那么可以设置参数如下：

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

其他参数不变，返回的就是一首完整的歌曲，就是所有歌曲片段的拼接结果，但结果只有一首歌，样例如下：

{
    "success": true,
    "task_id": "ff73ed83-26d3-47bb-9793-825ac1172abc",
    "trace_id": "98315862-fa60-4fa7-b4b8-788ce99fca26",
    "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鞭炮响 震散旧年的哀愁\n烟花飞 夜空美到心头\n[Verse 2]\n舞龙起 红色翻跃天空\n狮鼓敲 热闹暖暖人心中\n笑开怀 送祝福到意浓\n团圆饭 温热全家梦\n[Chorus]\n新年快乐 心愿齐欢歌\n祝福今天照亮每一刻\n梦想点燃 像烟花的火\n新年到来 快乐你和我\n[Verse 3]\n瑞雪飘 给岁月涂上白\n花儿开 宛如新的期待\n手牵手 不论东西南北\n我们一起 把幸福年代彩排\n[Bridge]\n一年忙碌 此刻都抛开\n让喜悦在心中蔓延发芽开\n拥抱未来 我们种下爱\n新的一年 全世界盛开\n[Chorus]\n新年快乐 心愿齐欢歌\n祝福今天照亮每一刻\n梦想点燃 像烟花的火\n新年到来 快乐你和我\n[Verse]\n天空飘着快乐的云彩\n脚下踩着跳跃的节拍\n阳光洒满大街每个角落\n心中冒出几朵好颜色\n[Verse 2]\n微风吹来像糖的味道\n每个人的脸上挂着微笑\n你伸出手牵着欢乐跑\n烦恼全都甩到很远的桥\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿\n让每个瞬间都值千金\n快乐无敌 没有原因\n[Verse 3]\n日子像串糖葫芦那么甜\n迷路也能变成探险\n光影在手腕上画旋转\n每一个动作都像跳舞般\n[Bridge]\n闭上眼让音乐直入心灵\n转圈圈看世界悄悄微倾\n星星眨眼悄悄为你打气\n这感觉让人不愿暂停\n[Chorus]\n唱的更愉快一点 啦啦啦\n跳的更开心一点 嘿嘿嘿\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池生成歌曲之后，我们需要对歌曲进行人声分离操作，需要使用人声分离功能，就可以指定如下内容：

• action：内容为 stems。
• audio_id：需要人声分离的歌曲ID。

比如基于Pro池生成后的歌曲 ID 是：4d6ddd0b-067a-4aa2-bb7d-1a720a3a0291，注意必须是Pro池生成的歌曲！！！那么可以设置参数如下：

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

其他参数不变，返回的就是一个人声分离的结果，主要包含人声和伴奏，样例如下：

{
    "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孩子们笑声传远方小巷\n满街祝福汇成了歌的海洋\n[Chorus]\n新年快乐 大声说出口\n幸福环绕 从心底流走\n家人团圆 举杯见长久\n愿望满怀 照亮每个角\n[Verse 2]\n春风轻轻唤醒沉睡的河\n希望像种子发芽在心窝\n新衣穿上走进红火街头\n贴心话语满天都洒不够\n[Chorus]\n新年快乐 大声说出口\n幸福环绕 从心底流走\n家人团圆 举杯见长久\n愿望满怀 照亮每个角\n[Bridge]\n时间流转却带不走的情\n万家灯火温暖如初的心\n岁月的礼物默默为我铺垫\n数不尽的美好将绢春年\n[Chorus]\n新年快乐 大声说出口\n幸福环绕 从心底流走\n家人团圆 举杯见长久\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
        }
    ]
}

自定义上传歌曲生成功能

如果想对自己上传的音乐进行生成的话，我们将上传歌曲与对上传扩展生成合并在一起了，因此需要将参数 action 设置为 upload_generate ，并且输入需要自己上传的音乐链接，接下来我们要必须填歌词、风格自定义生成歌曲，就可以指定如下内容：

• lyric：歌词文本
• custom：填写为 true，代表自定义生成，该参数默认为 false，代表使用 prompt 生成。
• style：歌曲的风格，选填。
• audio_url：自定义上传的歌曲链接，必填。
• prompt：生成的提示词。
• continue_at：表示从上传的音乐哪个时长开始生成，必须要大于0，必填。

注意，我们也提供了单独上传自定义歌曲的接口，Upload接口只需要传入audio_url这个参数即可得到上传后的歌曲ID，但是此时想要续写的话就必须将action 设置为 upload_extend，同时audio_url不是必传参数，而audio_id变成了必传参数，其他的参数保持不变。

填写样例如下：

点击发送，可以发现会得到一个结果，如下：

{
    "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\nSearching for answers in the light of day\nGot a pocket full of dreams I refuse to lose\nLife’s a wild card and I gotta choose\n[Verse 2]\nSneakers hitting pavement like a heartbeat’s drum\nChasing down a vision where the wild ones run\nThe world’s a broken mirror but I see it clear\nI’m a storm in a bottle got nothing to fear\n[Chorus]\nLost and found I’m spinning around\nPicking up pieces from the ground\nHold your breath as the thunder pounds\nI’m the boy who’ll never back down\n[Verse 3]\nThe stars in the sky they whisper to me\nThey say you’re more than what they let you see\nI’m a rebel searching for where I belong\nChaos in my veins it fuels my song\n[Bridge]\nI’m a spark in the night a beacon of fire\nA dreamer with wings climbing higher and higher\nThey can try to cage me but I'm breaking free\nI’m the boy in the mirror the fighter in me\n[Chorus]\nLost and found I’m spinning around\nPicking up pieces from the ground\nHold your breath as the thunder pounds\nI’m the boy who’ll never back down",
            "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\nSearching for answers in the light of day\nGot a pocket full of dreams I refuse to lose\nLife’s a wild card and I gotta choose\n[Verse 2]\nSneakers hitting pavement like a heartbeat’s drum\nChasing down a vision where the wild ones run\nThe world’s a broken mirror but I see it clear\nI’m a storm in a bottle got nothing to fear\n[Chorus]\nLost and found I’m spinning around\nPicking up pieces from the ground\nHold your breath as the thunder pounds\nI’m the boy who’ll never back down\n[Verse 3]\nThe stars in the sky they whisper to me\nThey say you’re more than what they let you see\nI’m a rebel searching for where I belong\nChaos in my veins it fuels my song\n[Bridge]\nI’m a spark in the night a beacon of fire\nA dreamer with wings climbing higher and higher\nThey can try to cage me but I'm breaking free\nI’m the boy in the mirror the fighter in me\n[Chorus]\nLost and found I’m spinning around\nPicking up pieces from the ground\nHold your breath as the thunder pounds\nI’m the boy who’ll never back down",
            "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
        }
    ]
}

可以看出，结果内容与上文的是一致的，这也就实现自定义歌曲的生成功能。

音乐翻唱

当基于原有的歌曲继续生成歌曲之后，返回的歌曲的风格可能不太合适。如果要对原先生成的歌曲(若是自定义上传的音乐也支持)进行翻版，需要使用音乐翻版方法，就可以指定如下内容：

• action：内容为 cover。
• audio_id：需要翻唱的歌曲ID。
• is_pro：是否采用专业池，翻唱功能必须使用专业池，这里必须填true。

比如生成后的歌曲 ID 是：84ad2f40-4cae-42fa-8a74-8117edbfd6fc，那么可以设置参数如下：

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

其他参数不变，返回的就是一首翻版后的歌曲，就是对原先生成的歌曲进行翻版后的结果，样例如下：

{
    "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\nA hurricane born of a reckless child\nEvery step she takes the ground shakes\nGirl girl girl she burns the stakes\n[Chorus]\nGirl girl girl she's a lightning storm\nDancing on the edge where chaos is born\nNo rules no chains she's her own world\nGirl girl girl oh she’s my pearl\n[Verse 2]\nShe laughs like thunder cracks the sky\nA fearless wave that’s flying high\nEvery whisper’s got an electric thrill\nGirl girl girl bending the will\n[Bridge]\nShe’s a wildfire out of control\nConsumes the night makes broken souls whole\nA diamond spinning under neon light\nGirl girl girl stealing the night\n[Chorus]\nGirl girl girl she's a lightning storm\nDancing on the edge where chaos is born\nNo rules no chains she's her own world\nGirl girl girl oh she’s my pearl\n[Outro]\nGirl girl girl she's the sun at dawn\nBlazing bright until the darkness is gone\nUnstoppable raw she's the center of it all\nGirl girl girl I’ll answer her call",
            "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\nA hurricane born of a reckless child\nEvery step she takes the ground shakes\nGirl girl girl she burns the stakes\n[Chorus]\nGirl girl girl she's a lightning storm\nDancing on the edge where chaos is born\nNo rules no chains she's her own world\nGirl girl girl oh she’s my pearl\n[Verse 2]\nShe laughs like thunder cracks the sky\nA fearless wave that’s flying high\nEvery whisper’s got an electric thrill\nGirl girl girl bending the will\n[Bridge]\nShe’s a wildfire out of control\nConsumes the night makes broken souls whole\nA diamond spinning under neon light\nGirl girl girl stealing the night\n[Chorus]\nGirl girl girl she's a lightning storm\nDancing on the edge where chaos is born\nNo rules no chains she's her own world\nGirl girl girl oh she’s my pearl\n[Outro]\nGirl girl girl she's the sun at dawn\nBlazing bright until the darkness is gone\nUnstoppable raw she's the center of it all\nGirl girl girl I’ll answer her call",
            "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
        }
    ]
}

替换片段

当生成歌曲之后需要进行替换歌曲片段单独操作的二次创作时，可以对歌曲的某个片段进行替换操作。就可以指定如下内容：

• action：内容为 replace_section。
• audio_id：之前生成歌曲的 ID。
• model: 歌曲生成模型，
• prompt：用户需要替换后的歌词（需要将替换的歌词也填入进去，这个歌词的片段时间对应下面的replace_section_start和replace_section_end）。
• lyric：用户需要替换的歌词。
• style：歌曲的风格，选填。
• replace_section_start：替换片段的起始时间，可以通过本网站的Timing接口进行获取歌词时间轴信息来确定起始时间。
• replace_section_end：替换片段的终点时间，可以通过本网站的Timing接口进行获取歌词时间轴信息来确定终点时间。

比如原先生成后的歌曲 ID 是：54c07904-dd3b-469f-b5d5-47cbcf1e506e，我们可以先通过Timing接口获取歌词的信息，下面给出一个请求Timing接口的示例代码，只需要输入歌曲ID，具体的如下图所示：

import requests

url = "https://api.sunohub.cn/suno/timing"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "audio_id": "7b0df74e-09c6-4a84-845b-9a2cf2cbfbd4"
}

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

运行后可以得到歌曲的歌词时间轴信息：

{
  "success": true,
  "task_id": "d76a3a9e-dea8-4537-86e0-bba071458668",
  "trace_id": "009a4066-522e-4ca4-aa77-3850be8722e1",
  "data": {
    "aligned_words": [
      {
        "word": "[Verse]\n窗外鞭炮声震天响\n",
        "success": true,
        "start_s": 7.340425531914894,
        "end_s": 10.691489361702128,
        "p_align": 0.99
      },
      {
        "word": "红灯笼挂满了各家巷\n",
        "success": true,
        "start_s": 10.851063829787234,
        "end_s": 14.441489361702128,
        "p_align": 0.99
      },
      {
        "word": "新衣服带着福气登场\n",
        "success": true,
        "start_s": 14.601063829787234,
        "end_s": 18.03191489361702,
        "p_align": 0.99
      },
      {
        "word": "笑声绕满了欢乐厅堂\n\n",
        "success": true,
        "start_s": 18.19148936170213,
        "end_s": 23.31963249516441,
        "p_align": 0.99
      },
      {
        "word": "[Chorus]\n新年快乐大家喜洋洋\n",
        "success": true,
        "start_s": 23.341392649903288,
        "end_s": 26.96808510638298,
        "p_align": 0.99
      },
      {
        "word": "好运满满心中全是光\n",
        "success": true,
        "start_s": 27.127659574468087,
        "end_s": 30.638297872340427,
        "p_align": 0.99
      },
      {
        "word": "团圆饭香飘四周飘荡\n",
        "success": true,
        "start_s": 30.79787234042553,
        "end_s": 34.22872340425532,
        "p_align": 0.99
      },
      {
        "word": "愿望成真心花绽满芳\n\n",
        "success": true,
        "start_s": 34.388297872340424,
        "end_s": 52.9188829787234,
        "p_align": 0.99
      },
      {
        "word": "[Verse 2]\n饺子蒸熟传递手中热\n",
        "success": true,
        "start_s": 52.93882978723404,
        "end_s": 56.48936170212766,
        "p_align": 0.99
      },
      {
        "word": "春联贴好字字祝福多\n",
        "success": true,
        "start_s": 56.648936170212764,
        "end_s": 60.159574468085104,
        "p_align": 0.99
      },
      {
        "word": "小孩红包数得手发酸\n",
        "success": true,
        "start_s": 60.319148936170215,
        "end_s": 63.590425531914896,
        "p_align": 0.99
      },
      {
        "word": "嘴角的笑如金阳灿烂\n\n",
        "success": true,
        "start_s": 63.75,
        "end_s": 67.60154738878143,
        "p_align": 0.99
      },
      {
        "word": "[Chorus]\n新年快乐大家喜洋洋\n",
        "success": true,
        "start_s": 67.62330754352031,
        "end_s": 71.17021276595744,
        "p_align": 0.99
      },
      {
        "word": "好运满满心中全是光\n",
        "success": true,
        "start_s": 71.32978723404256,
        "end_s": 74.84042553191489,
        "p_align": 0.99
      },
      {
        "word": "团圆饭香飘四周飘荡\n",
        "success": true,
        "start_s": 75,
        "end_s": 78.27127659574468,
        "p_align": 0.99
      },
      {
        "word": "愿望成真心花绽满芳\n\n",
        "success": true,
        "start_s": 78.43085106382979,
        "end_s": 81.96143617021276,
        "p_align": 0.99
      },
      {
        "word": "[Verse 2]\n饺子蒸熟传递手中热\n",
        "success": true,
        "start_s": 81.9813829787234,
        "end_s": 85.53191489361703,
        "p_align": 0.99
      },
      {
        "word": "春联贴好字字祝福多\n",
        "success": true,
        "start_s": 85.69148936170212,
        "end_s": 89.28191489361703,
        "p_align": 0.99
      },
      {
        "word": "小孩红包数得手发酸\n",
        "success": true,
        "start_s": 89.44148936170212,
        "end_s": 92.87234042553192,
        "p_align": 0.99
      },
      {
        "word": "嘴角的笑如金阳灿烂\n\n",
        "success": true,
        "start_s": 93.03191489361703,
        "end_s": 97.0357833655706,
        "p_align": 0.99
      },
      {
        "word": "[Chorus]\n新年快乐大家喜洋洋\n",
        "success": true,
        "start_s": 97.05029013539652,
        "end_s": 100.29255319148936,
        "p_align": 0.99
      },
      {
        "word": "好运满满心中全是光\n",
        "success": true,
        "start_s": 100.45212765957447,
        "end_s": 103.9627659574468,
        "p_align": 0.99
      },
      {
        "word": "团圆饭香飘四周飘荡\n",
        "success": true,
        "start_s": 104.12234042553192,
        "end_s": 107.63297872340425,
        "p_align": 0.99
      },
      {
        "word": "愿望成真心花绽满芳\n\n",
        "success": true,
        "start_s": 107.79255319148936,
        "end_s": 111.31769825918762,
        "p_align": 0.99
      },
      {
        "word": "[Bridge]\n火花满天各地月同圆\n",
        "success": true,
        "start_s": 111.33220502901355,
        "end_s": 114.8936170212766,
        "p_align": 0.99
      },
      {
        "word": "希望包裹在祝福之涧\n",
        "success": true,
        "start_s": 115.05319148936171,
        "end_s": 118.56382978723404,
        "p_align": 0.99
      },
      {
        "word": "一年努力终有成果现\n",
        "success": true,
        "start_s": 118.72340425531915,
        "end_s": 122.23404255319149,
        "p_align": 0.99
      },
      {
        "word": "只愿开心幸福无尽延\n\n",
        "success": true,
        "start_s": 122.3936170212766,
        "end_s": 125.92601547388782,
        "p_align": 0.99
      },
      {
        "word": "[Chorus]\n新年快乐大家喜洋洋\n",
        "success": true,
        "start_s": 125.94777562862669,
        "end_s": 129.5744680851064,
        "p_align": 0.99
      },
      {
        "word": "好运满满心中全是光\n",
        "success": true,
        "start_s": 129.7340425531915,
        "end_s": 133.24468085106383,
        "p_align": 0.99
      },
      {
        "word": "团圆饭香飘四周飘荡\n",
        "success": true,
        "start_s": 133.40425531914894,
        "end_s": 136.91489361702128,
        "p_align": 0.99
      },
      {
        "word": "愿望成真心花绽满芳\n\n",
        "success": true,
        "start_s": 137.0744680851064,
        "end_s": 139.70744680851064,
        "p_align": 0.99
      }
    ],
    "waveform_data": [
      0.00001,
      0.00001,
      0.11009,
      0.1292,
      0.11504,
      ...
    ],
    "hoot_cer": 0.7123287671232876,
    "is_streamed": false
  }
}

假设我们要替换后的完整歌词片段为："[Verse]\n窗外鞭炮声震天响\n红灯笼挂满了各家巷\n新衣服带着福气登场\n笑声绕满了欢乐厅堂\n[Chorus]\n新年快乐大家喜洋洋\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n" 这个就是对应参数 prompt的值，需要替换的歌词信息为："桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n"，实际上就是把歌曲原来的好运满满心中全是光\n团圆饭香飘四周飘荡\n愿望成真心花绽满芳\n\n换成了桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n，因此这个值就是参数 lyric的值，从上面的歌词时间轴结果信息可知，替换片段的起始时间和终点时间分别为：7.340425531914894、52.9188829787234，时间可以不用很准确，大概差不多就行了，那么可以设置参数如下：

{
  "action": "replace_section",
  "lyric": "[Verse]\n窗外鞭炮声震天响\n红灯笼挂满了各家巷\n新衣服带着福气登场\n笑声绕满了欢乐厅堂\n[Chorus]\n新年快乐大家喜洋洋\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n",
  "prompt": "桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n",
  "replace_section_start": 7.340425531914894,
  "replace_section_end": 52.9188829787234,
  "model": "chirp-v4",
  "audio_id": "54c07904-dd3b-469f-b5d5-47cbcf1e506e",
  "custom": false,
  "instrumental": false
}

如果还有不理解的话可以看看下面的示例：

我们有一首歌曲，它的原来的歌词是：

[Verse]
11111
11111
11111
11111
[Verse 2]
22222
22222
22222
22222
[Chorus]
33333
33333
33333
33333

现在我们需要将Verse 2的歌词进行替换的话，假设我们替换后的歌词是：

[Verse]
11111
11111
11111
11111
[Verse 2]
55555
55555
55555
55555
[Chorus]
33333
33333
33333
33333

上面就是我们要上传的lyric参数值，但是实际上不需要传很多歌词，下面可以对lyric缩减一点为：

[Verse]
11111
11111
11111
11111
[Verse 2]
55555
55555
55555
55555

现在我们还剩一个prompt参数，这个参数就是我们替换上去的Verse 2歌词部分，具体的为：

[Verse 2]
55555
55555
55555
55555

总而言之，prompt必须要与lyric有重复部分，lyric不需要上传很多歌词内容，只要包含了prompt的内容即可，还有俩个关键的参数replace_section_start和replace_section_end，这个必须要和lyric的歌词时间轴对上，时间间隔也不能太大，不能超过1分钟，否则官方那边会报错。

其他参数不变，返回的就是俩首替换后的片段歌曲，就是对原先生成的歌曲进行替换片段后的结果，但得到的结果只是一个片段歌曲，如果想得到完整的歌曲还需要执行上文的获取完整歌曲的内容，这样就可以获得完整的替换片段后的歌曲。结果如下：

{
    "success": true,
    "task_id": "668d5067-1a70-41c2-a42e-96525e329d9a",
    "trace_id": "840ceea9-f769-4802-a22c-acd5cb5b9462",
    "data": [
        {
            "id": "6546e8af-dd53-4882-811d-c421ff3e6e0e",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_6546e8af-dd53-4882-811d-c421ff3e6e0e.jpeg",
            "lyric": "[Verse]\n窗外鞭炮声震天响\n红灯笼挂满了各家巷\n新衣服带着福气登场\n笑声绕满了欢乐厅堂\n[Chorus]\n新年快乐大家喜洋洋\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏",
            "audio_url": "https://cdn1.suno.ai/6546e8af-dd53-4882-811d-c421ff3e6e0e.mp3",
            "video_url": "",
            "created_at": "2025-04-16T08:21:59.298Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "",
            "duration": 124
        },
        {
            "id": "8e6dd1b8-8b5e-4c00-a8ac-8417d916cbcd",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_8e6dd1b8-8b5e-4c00-a8ac-8417d916cbcd.jpeg",
            "lyric": "[Verse]\n窗外鞭炮声震天响\n红灯笼挂满了各家巷\n新衣服带着福气登场\n笑声绕满了欢乐厅堂\n[Chorus]\n新年快乐大家喜洋洋\n桃花潭水深千尺藏\n桃花潭水深千尺藏\n桃花潭水深千尺藏",
            "audio_url": "https://cdn1.suno.ai/8e6dd1b8-8b5e-4c00-a8ac-8417d916cbcd.mp3",
            "video_url": "",
            "created_at": "2025-04-16T08:21:59.298Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "",
            "duration": 124
        }
    ]
}

生成的结果与上文类似，这就完成了对原先生成的歌曲进行替换片段的过程，现在的结果只是片段的歌曲，如果需要完整的歌曲还需要执行上文的拼接（concat）功能。

自定义歌手风格生成功能

如果想使用歌手风格来生成歌曲的话，首先通过上文的基本使用生成一首歌曲，这里生成的歌曲必须是专业池里面生成的，然后将该歌曲的ID在Persona接口进行上传得到persona_id,下面讲解如何获取persona_id,根据专业池生成的音乐ID audio_id 来生成一个歌手风格的id参数 persona_id，具体的参数如下图所示：

{
    "name": "新年快乐",
    "description": "新年快乐",
    "audio_id": "04734644-d4c8-4d1e-ac53-be95289c5b6b"
}

对应的 Python 代码：

import requests

url = "https://api.sunohub.cn/suno/persona"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "name": "新年快乐",
    "description": "新年快乐",
    "audio_id": "04734644-d4c8-4d1e-ac53-be95289c5b6b"
}

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

点击运行，可以发现会得到一个结果，如下：

{
    "success": true,
    "task_id": "7a603203-918a-4ce7-8d7c-5e772a62861b",
    "data": {
        "persona_id": "89f20346-51f0-4b35-a88e-ed8fa5bb5cac",
        "name": "新年快乐",
        "description": "新年快乐"
    }
}

我们以上面的 audio_id 和 persona_id 分别为 04734644-d4c8-4d1e-ac53-be95289c5b6b、89f20346-51f0-4b35-a88e-ed8fa5bb5cac 为此次的示例数据。使用自定义歌手风格生成必须在专业池里面进行，专业池使用只需要加一个is_pro参数即可，否则会失效， 然后可以将参数 action 设置为 artist_consistency ，并且输入需要继续生成歌曲的 ID 、 歌手风格ID，填写样例如下：

{
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "custom": false,
    "instrumental": false,
    "is_pro": true,
    "audio_id": "04734644-d4c8-4d1e-ac53-be95289c5b6b",
    "persona_id": "89f20346-51f0-4b35-a88e-ed8fa5bb5cac"
}

对应的 Python 代码：

import requests

url = "https://api.sunohub.cn/suno/audios"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "action": "artist_consistency",
    "prompt": "A song for Christmas",
    "model": "chirp-v4-5",
    "custom": false,
    "instrumental": false,
    "is_pro": true,
    "audio_id": "04734644-d4c8-4d1e-ac53-be95289c5b6b",
    "persona_id": "89f20346-51f0-4b35-a88e-ed8fa5bb5cac"
}

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

点击运行，可以发现会得到一个结果，如下：

{
    "success": true,
    "task_id": "b5862984-47c2-4fd9-acb1-583ccb7b2634",
    "trace_id": "7ba1154f-fccf-4f0c-a585-fd3abf5629e6",
    "data": [
        {
            "id": "ca029c03-299a-4c4a-a0ee-64350ffbaf30",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_ca029c03-299a-4c4a-a0ee-64350ffbaf30.jpeg",
            "lyric": "",
            "audio_url": "https://cdn1.suno.ai/ca029c03-299a-4c4a-a0ee-64350ffbaf30.mp3",
            "video_url": "",
            "created_at": "2025-05-10T07:45:27.655Z",
            "model": "chirp-auk",
            "state": "succeeded",
            "style": "",
            "duration": 311.84
        },
        {
            "id": "520d4b26-045f-4eab-a22e-2113200c8109",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_520d4b26-045f-4eab-a22e-2113200c8109.jpeg",
            "lyric": "",
            "audio_url": "https://cdn1.suno.ai/520d4b26-045f-4eab-a22e-2113200c8109.mp3",
            "video_url": "",
            "created_at": "2025-05-10T07:45:27.655Z",
            "model": "chirp-auk",
            "state": "succeeded",
            "style": "",
            "duration": 164.8
        }
    ]
}

可以看出，结果内容与上文的是一致的，这也就实现使用歌手风格来生成歌曲的功能。

异步回调

由于 Suno 生成音乐的时间相对较长，大约需要 1-2 分钟，如果 API 长时间无响应，HTTP 请求会一直保持连接，导致额外的系统资源消耗，所以本 API 也提供了异步回调的支持。

整体流程是：客户端发起请求的时候，额外指定一个 callback_url 字段，客户端发起 API 请求之后，API 会立马返回一个结果，包含一个 task_id 的字段信息，代表当前的任务 ID。当任务完成之后，生成音乐的结果会通过 POST JSON 的形式发送到客户端指定的 callback_url，其中也包括了 task_id 字段，这样任务结果就可以通过 ID 关联起来了。

下面我们通过示例来了解下具体怎样操作。

首先，Webhook 回调是一个可以接收 HTTP 请求的服务，开发者应该替换为自己搭建的 HTTP 服务器的 URL。此处为了方便演示，使用一个公开的 Webhook 样例网站 https://webhook.site/，打开该网站即可得到一个 Webhook URL，如图所示：

将此 URL 复制下来，就可以作为 Webhook 来使用，此处的样例为 https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2。

接下来，我们可以设置字段 callback_url 为上述 Webhook URL，同时填入 prompt，如图所示：

点击运行，可以发现会立即得到一个结果，如下：

{
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60"
}

稍等片刻，我们可以在 https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2 上观察到生成歌曲的结果，如图所示：

内容如下：

{
  "success": true,
  "task_id": "44472ab8-783b-4054-b861-5bf14e462f60",
  "data": [
    {
      "id": "da4324e5-84b2-484b-b0e9-dd261381c594",
      "title": "Winter Whispers",
      "image_url": "https://cdn1.suno.ai/image_da4324e5-84b2-484b-b0e9-dd261381c594.png",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn1.suno.ai/da4324e5-84b2-484b-b0e9-dd261381c594.mp3",
      "video_url": "https://cdn1.suno.ai/da4324e5-84b2-484b-b0e9-dd261381c594.mp4",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    },
    {
      "id": "b878a87b-a0db-4046-8ccd-ecd2fb3d4372",
      "title": "Winter Whispers",
      "image_url": "https://cdn1.suno.ai/image_b878a87b-a0db-4046-8ccd-ecd2fb3d4372.png",
      "lyric": "[Verse]\nSnow falling gently from the sky\nChildren giggling as they pass by\nFire crackling\nCozy and warm\nChristmas spirit begins to swarm\n[Verse 2]\nTwinkling lights\nA sight to behold\nStockings hung\nWaiting to be filled with gold\nGifts wrapped with love\nPiled high\nExcitement in the air\nYou can't deny\n[Chorus]\nWinter whispers in the wind\nJoy and love it brings\nLet's celebrate this season\nWith the ones we're missing",
      "audio_url": "https://cdn1.suno.ai/b878a87b-a0db-4046-8ccd-ecd2fb3d4372.mp3",
      "video_url": "https://cdn1.suno.ai/b878a87b-a0db-4046-8ccd-ecd2fb3d4372.mp4",
      "created_at": "2024-05-11T07:33:05.430Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "pop"
    }
  ]
}

可以看到结果中有一个 task_id 字段，其他的字段都和上文类似，通过该字段即可实现任务的关联。