AceData: All-in-One AI Creative Studio offers comprehensive AI services, including Q&A, image generation, QR codes, music, and more, along with diverse API platform integrations to meet your varied needs. New users receive free usage credits to help you create with ease!"

With the widespread application of AI, various AI programs have gradually become popular. AI has gradually penetrated all aspects of people's work and life. The industries involved in AI are also increasing, from initial writing to medical education, and now to music.

Suno is a professional high-quality AI song and music creation platform. Users only need to input simple text prompts to generate songs with vocals based on genre style and lyrics. This AI music generator is developed by team members from well-known tech companies like Meta, TikTok, Kensho, aiming to allow everyone to create beautiful music without any instrumental tools.

Suno has recently upgraded its music generation model to version V3, capable of generating 2-minute songs.

However, Suno does not officially provide an API. AceDataCloud offers a set of Suno APIs that simulate integration with Suno's official platform, allowing for easy and quick music generation.

Application and Usage

To use the Suno Audios API, first, visit the Suno Audios Generation API page and click the "Acquire" button to obtain the credentials needed for requests:

If you are not logged in or registered, you will be automatically redirected to the login page, inviting you to register and log in. After logging in or registering, you will be automatically returned to the current page.

Upon the first application, a free quota will be given, allowing free use of the API.

Basic Usage

Think of any song, you can input any text, for example, if I want to generate a song about Christmas, I can input a song for Christmas, as shown in the picture:

The generated code is as follows:

You can click the "Try" button to directly test the API, wait for 1-2 minutes, and the result is as follows:

{
  "success": true,
  "data": [
    {
      "state": "succeeded",
      "id": "2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5",
      "title": "Winter Wonderland",
      "image_url": "https://cdn1.suno.ai/image_2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5.png",
      "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",
      "audio_url": "https://cdn1.suno.ai/2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5.mp3",
      "video_url": "https://cdn1.suno.ai/2f16f7bc-4135-42c6-b3c5-6d6c49dc8cd5.mp4",
      "created_at": "2024-05-10T16:21:37.624Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "holiday"
    },
    {
      "state": "succeeded",
      "id": "5dca232b-17cc-4896-a2d1-4b59178bf410",
      "title": "Winter Wonderland",
      "image_url": "https://cdn1.suno.ai/image_5dca232b-17cc-4896-a2d1-4b59178bf410.png",
      "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",
      "audio_url": "https://cdn1.suno.ai/5dca232b-17cc-4896-a2d1-4b59178bf410.mp3",
      "video_url": "https://cdn1.suno.ai/5dca232b-17cc-4896-a2d1-4b59178bf410.mp4",
      "created_at": "2024-05-10T16:21:37.624Z",
      "model": "chirp-v3",
      "prompt": "A song for Christmas",
      "style": "holiday"
    }
  ]
}

As you can see, we have obtained the content of two songs, including the title, preview image, lyrics, audio, video, and other content.

Field descriptions are as follows:

  • success: Whether the generation was successful, if successful, it is true, otherwise it is false.
  • data: A list containing detailed information about the generated songs.
    • state: Song generation status, mainly includes four types, as follows:
    • succeeded: Generation successful
    • pending: In queue
    • running: In progress
    • error: Failed
    • id: Song ID
    • title: Song title
    • image_url: Song cover image
    • lyric: Song lyrics
    • audio_url: Song audio file, which opens as an mp3 audio.
    • video_url: Song video file, which opens as an mp4 video.
    • created_at: Creation time
    • model: Model used, generally the latest v3 model
    • style: Style

Custom Generation

If you want to customize the generation of lyrics, you can input lyrics:

At this time, the lyric field can be passed with content similar to the following:

[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

Note, the \n in the lyrics here is a newline character. If you don't know how to generate lyrics, you can use the lyrics generation API provided by AceDataCloud to generate lyrics through a prompt. The API is Suno Lyrics Generation API.

Next, we want to customize the generation of songs based on lyrics, title, and style, and you can specify the following content:

  • lyric: Lyrics text
  • custom: Set to true, representing custom generation. This parameter defaults to false, representing generation using prompt.
  • file: Song title.
  • style: Song style, optional.

Sample filling is as follows:


After completing the form, the code automatically generated is as follows:

Corresponding code:

curl -X POST 'https://api.acedata.cloud/suno/audios' \
-H 'authorization: Bearer {token}' \
-H 'accept: application/json' \
-H 'content-type: application/json' \
-d '{
"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",
"custom": true
}'

Testing is allowed, and the generated effect is similar.

Custom Singer Style Generation Function

If you want to use a singer's style to generate a song, first generate a song through the basic usage in the text above,
specific parameters are shown in the picture below:

After completing the form, the code automatically generated is as follows:

Corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/audios"

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

payload = {
    "action": "generate",
    "prompt": "A song for Christmas",
    "model": "chirp-v4"
}

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

Click run, and you will find that the result is obtained as follows:

{
  "success": true,
  "task_id": "04067c0f-6655-44b6-8c4f-f443af573ebf",
  "trace_id": "c0a574b6-d5b1-4ddc-9529-b1a3d502a7e9",
  "data": [
    {
      "id": "8bc267d2-9794-412c-a504-974ce3cba254",
      "title": "Jingle All the Way",
      "image_url": "https://cdn2.suno.ai/image_8bc267d2-9794-412c-a504-974ce3cba254.jpeg",
      "lyric": "[Verse]\nSnowflakes dancing in the street\nWarm cocoa can't be beat\nNeighbours laugh as carolers sing\nJoyful bells begin to ring\n[Verse 2]\nCandy canes and mistletoe\nSparkling lights that gleam and glow\nWrinkled paper ribbons flying\nSmiling faces never lying\n[Chorus]\nJingle all the way tonight\nStars above are shining bright\nGifts of laughter love and cheer\nMaking memories so dear\n[Verse 3]\nStockings hanging by the fire\nEvery heart is full of desire\nSilent wishes whispered low\nUnderneath the mistletoe\n[Bridge]\nChildren dreaming of delight\nSanta's sleigh takes flight tonight\nMagic sparkles in the air\nChristmas wonder everywhere\n[Verse 4]\nWrapping presents with a bow\nFeeling love in every show\nFamily gathered round the tree\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/8bc267d2-9794-412c-a504-974ce3cba254.mp3",
      "video_url": "https://cdn1.suno.ai/8bc267d2-9794-412c-a504-974ce3cba254.mp4",
      "created_at": "2025-01-04T03:26:59.710Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "pop",
      "duration": 181.56
    },
    {
      "id": "8ebdcf48-1d4d-4b8a-94bc-ec46a793f590",
      "title": "Jingle All the Way",
      "image_url": "https://cdn2.suno.ai/image_8ebdcf48-1d4d-4b8a-94bc-ec46a793f590.jpeg",
      "lyric": "[Verse]\nSnowflakes dancing in the street\nWarm cocoa can't be beat\nNeighbours laugh as carolers sing\nJoyful bells begin to ring\n[Verse 2]\nCandy canes and mistletoe\nSparkling lights that gleam and glow\nWrinkled paper ribbons flying\nSmiling faces never lying\n[Chorus]\nJingle all the way tonight\nStars above are shining bright\nGifts of laughter love and cheer\nMaking memories so dear\n[Verse 3]\nStockings hanging by the fire\nEvery heart is full of desire\nSilent wishes whispered low\nUnderneath the mistletoe\n[Bridge]\nChildren dreaming of delight\nSanta's sleigh takes flight tonight\nMagic sparkles in the air\nChristmas wonder everywhere\n[Verse 4]\nWrapping presents with a bow\nFeeling love in every show\nFamily gathered round the tree\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/8ebdcf48-1d4d-4b8a-94bc-ec46a793f590.mp3",
      "video_url": "https://cdn1.suno.ai/8ebdcf48-1d4d-4b8a-94bc-ec46a793f590.mp4",
      "created_at": "2025-01-04T03:26:59.710Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "prompt": "A song for Christmas",
      "style": "pop",
      "duration": 203.8
    }
  ]
}

Finally, the song needs to be set to the singer's style, and then you need to enter the Suno Persona API to generate an ID parameter persona_id for a singer's style according to the official generated music ID audio_id. Specific parameters are shown in the picture below:

After completing the form, the code automatically generated is as follows:

Corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/persona"

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

payload = {
    "name": "Christmas",
    "audio_id": "8bc267d2-9794-412c-a504-974ce3cba254"
}

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

Click run, and you will find that the result is obtained as follows:

{
  "success": true,
  "task_id": "807dde07-ca91-4a51-ba45-d3b3f12f6a54",
  "data": {
    "persona_id": "194a0114-3705-4bd2-b975-abc20fec77f3"
  }
}

We use the above audio_id and persona_id as 8bc267d2-9794-412c-a504-974ce3cba254, 194a0114-3705-4bd2-b975-abc20fec77f3 as the sample data. Then you can set the parameter action to artist_consistency, and input the ID you need to continue generating songs and the singer style ID, fill in the sample as follows:

After filling it out, the code is automatically generated as follows:

Corresponding Python code:

import requests

url = "https://api.acedata.cloud/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",
    "custom": True,
    "audio_id": "8bc267d2-9794-412c-a504-974ce3cba254",
    "persona_id": "194a0114-3705-4bd2-b975-abc20fec77f3",
    "lyric": "[Verse]\\nSnowflakes dancing in the street\\nWarm cocoa can't be beat\\nNeighbours laugh as carolers sing\\nJoyful bells begin to ring\\n[Verse 2]\\nCandy canes and mistletoe\\nSparkling lights that gleam and glow\\nWrinkled paper ribbons flying\\nSmiling faces never lying\\n[Chorus]\\nJingle all the way tonight\\nStars above are shining bright\\nGifts of laughter love and cheer\\nMaking memories so dear\\n[Verse 3]\\nStockings hanging by the fire\\nEvery heart is full of desire\\nSilent wishes whispered low\\nUnderneath the mistletoe\\n[Bridge]\\nChildren dreaming of delight\\nSanta's sleigh takes flight tonight\\nMagic sparkles in the air\\nChristmas wonder everywhere\\n[Verse 4]\\nWrapping presents with a bow\\nFeeling love in every show\\nFamily gathered round the tree\\nHoliday spirit wild and free"
}

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

Clicking run, you can see a result like this:

{
  "success": true,
  "task_id": "77fd7f95-9f75-4f5f-8c7a-4d78d284ef54",
  "trace_id": "f34b8b11-2839-48ea-b4e6-5525cb74d72f",
  "data": [
    {
      "id": "8b730866-dc0b-436e-aeee-d703a46c8187",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_8b730866-dc0b-436e-aeee-d703a46c8187.jpeg",
      "lyric": "[Verse]\\nSnowflakes dancing in the street\\nWarm cocoa can't be beat\\nNeighbours laugh as carolers sing\\nJoyful bells begin to ring\\n[Verse 2]\\nCandy canes and mistletoe\\nSparkling lights that gleam and glow\\nWrinkled paper ribbons flying\\nSmiling faces never lying\\n[Chorus]\\nJingle all the way tonight\\nStars above are shining bright\\nGifts of laughter love and cheer\\nMaking memories so dear\\n[Verse 3]\\nStockings hanging by the fire\\nEvery heart is full of desire\\nSilent wishes whispered low\\nUnderneath the mistletoe\\n[Bridge]\\nChildren dreaming of delight\\nSanta's sleigh takes flight tonight\\nMagic sparkles in the air\\nChristmas wonder everywhere\\n[Verse 4]\\nWrapping presents with a bow\\nFeeling love in every show\\nFamily gathered round the tree\\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/8b730866-dc0b-436e-aeee-d703a46c8187.mp3",
      "video_url": "https://cdn1.suno.ai/8b730866-dc0b-436e-aeee-d703a46c8187.mp4",
      "created_at": "2025-01-04T03:54:22.060Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 120.28
    },
    {
      "id": "13cff259-a8f2-4729-ba1b-3dc48e92f18a",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_13cff259-a8f2-4729-ba1b-3dc48e92f18a.jpeg",
      "lyric": "[Verse]\\nSnowflakes dancing in the street\\nWarm cocoa can't be beat\\nNeighbours laugh as carolers sing\\nJoyful bells begin to ring\\n[Verse 2]\\nCandy canes and mistletoe\\nSparkling lights that gleam and glow\\nWrinkled paper ribbons flying\\nSmiling faces never lying\\n[Chorus]\\nJingle all the way tonight\\nStars above are shining bright\\nGifts of laughter love and cheer\\nMaking memories so dear\\n[Verse 3]\\nStockings hanging by the fire\\nEvery heart is full of desire\\nSilent wishes whispered low\\nUnderneath the mistletoe\\n[Bridge]\\nChildren dreaming of delight\\nSanta's sleigh takes flight tonight\\nMagic sparkles in the air\\nChristmas wonder everywhere\\n[Verse 4]\\nWrapping presents with a bow\\nFeeling love in every show\\nFamily gathered round the tree\\nHoliday spirit wild and free",
      "audio_url": "https://cdn1.suno.ai/13cff259-a8f2-4729-ba1b-3dc48e92f18a.mp3",
      "video_url": "https://cdn1.suno.ai/13cff259-a8f2-4729-ba1b-3dc48e92f18a.mp4",
      "created_at": "2025-01-04T03:54:22.060Z",
      "model": "chirp-v4",
      "state": "succeeded",
      "style": "",
      "duration": 120.44
    }
  ]
}

It can be seen that the result content is consistent with the above, which also achieves the function of generating songs using the singer's style.

Continue Generation Function

If you want to continue generating the already generated Suno song, you can set the parameter action to extend, and input the ID of the song you want to continue generating. The song ID is obtained based on basic usage, as shown in the image below:

At this time, you can see the song ID is:

"id": "b9e9fa11-0bf3-47cd-a3d7-85735aee3e07"

Note, the id in the lyrics here is the ID of the generated song. If you don't know how to generate a song, you can refer to the basic usage above to generate a song.

If you want to continue generating your uploaded song, you can set the parameter action to upload_extend, and input the ID of the custom uploaded song you want to continue generating. The song ID is obtained using the Suno Upload Generation API, as shown in the image below:

Next, we must fill in the lyrics and style to customize the song generation, and you can specify the following content:

  • lyric: Lyrics text
  • custom: Fill in true, representing custom generation, this parameter defaults to false, representing generation using prompt.
  • style: The style of the song, optional.
  • continue_at: Continue the existing audio time in seconds. For example, 213.5 means continuing to 3 minutes and 33.5 seconds.

Sample filling is as follows:

After filling it out, the code is automatically generated as follows:

The corresponding Python code:

import requests

url = "https://api.acedata.cloud/suno/audios"

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

payload = {
    "action": "extend",
    "prompt": "A song for Christmas",
    "audio_id": "b9e9fa11-0bf3-47cd-a3d7-85735aee3e07",
    "continue_at": 10,
    "style": "cute",
    "lyric": "la la la"
}

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

Clicking run, you will find a result, as follows:

{
  "success": true,
  "task_id": "baf55c32-1207-4bdf-bd00-32a864f0474d",
  "data": [
    {
      "id": "5a3d0054-a6c5-43a9-a348-eae22d1f0efe",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_5a3d0054-a6c5-43a9-a348-eae22d1f0efe.jpeg",
      "lyric": "la la la",
      "audio_url": "https://cdn1.suno.ai/5a3d0054-a6c5-43a9-a348-eae22d1f0efe.mp3",
      "video_url": "https://cdn1.suno.ai/5a3d0054-a6c5-43a9-a348-eae22d1f0efe.mp4",
      "created_at": "2024-07-25T11:15:49.320Z",
      "model": "chirp-v3.5",
      "prompt": null,
      "style": "cute",
      "duration": 7.96
    },
    {
      "id": "9ae90c96-adcf-4aad-a591-361485168f13",
      "title": "",
      "image_url": "https://cdn2.suno.ai/image_9ae90c96-adcf-4aad-a591-361485168f13.jpeg",
      "lyric": "la la la",
      "audio_url": "https://cdn1.suno.ai/9ae90c96-adcf-4aad-a591-361485168f13.mp3",
      "video_url": "https://cdn1.suno.ai/9ae90c96-adcf-4aad-a591-361485168f13.mp4",
      "created_at": "2024-07-25T11:15:49.321Z",
      "model": "chirp-v3.5",
      "prompt": null,
      "style": "cute",
      "duration": 4.2
    }
  ]
}

It can be seen that the content of the result is consistent with the above, which also realizes the song continuation function.

Getting the Complete Song

When you continue to generate a song based on the existing song, the returned song does not contain the original song content. To get the complete song content, you need to use the concatenation feature, where you can specify the following:

  • action: content is concat.
  • audio_id: the ID of the last segment.

For example, if the extended song ID is: 0550d2ea-1e2e-4800-a163-60f172c0b51e, then you can set the parameters as follows:

{
  "action": "concat",
  "audio_id": "0550d2ea-1e2e-4800-a163-60f172c0b51e"
}

Other parameters remain unchanged, and the result returned is a complete song, which is the concatenation of all song segments, but the result is only one song, as below:

{
  "success": true,
  "data": [
    {
      "state": "succeeded",
      "id": "b7cc1054-4ecf-4fb3-a711-ec25f8878ac7",
      "title": "Piggy Dreams",
      "image_url": "https://cdn2.suno.ai/image_0550d2ea-1e2e-4800-a163-60f172c0b51e.jpeg",
      "lyric": "[Verse]\nSaw a pig with dreams today\nDancing in the mud and hay\nSnorting tunes in his own way\nLiving large in piggy sway\n\n[Verse 2]\nOinking songs from dawn to dusk\nRolling round in rustic musk\nDreaming big without no fuss\nPiggy life’s a simple trust\n\n[Chorus]\nPiggy dreams you can’t suppress\nDancing round in muddy dress\nLiving life without the stress\nIn their world they’re truly blessed\n\n[Verse 3]\nApple cores and pumpkin pie\nPigs don’t need a reason why\nEvery day just to defy\nAny doubt that they can\"t fly\n\n[Bridge]\nThrough the fields they trotter free\nUnderneath the apple tree\nDreamin\" of what they could be\nPiggy dreams wild and carefree\n\n[Chorus]\nPiggy dreams you can’t suppress\nDancing round in muddy dress\nLiving life without the stress\nIn their world they’re truly blessed",
      "audio_url": "https://cdn1.suno.ai/b7cc1054-4ecf-4fb3-a711-ec25f8878ac7.mp3",
      "video_url": "https://cdn1.suno.ai/b7cc1054-4ecf-4fb3-a711-ec25f8878ac7.mp4",
      "created_at": "2024-12-08T15:50:00.105Z",
      "model": null,
      "prompt": null,
      "style": null,
      "duration": 259
    }
  ],
  "task_id": "394f3ff7-d952-4dbc-901e-9248d4d5ecf5"
}

Music Remake

When you continue to generate a song based on the existing one, the style of the returned song may not be quite suitable. If you want to remake the previously generated song (this also supports custom uploaded music), you need to use the music remake method, where you can specify the following:

  • action: content is cover, when performing a remake operation on custom uploaded music the content must be specified as: upload_cover.
  • audio_id: the ID of the previously generated song.

For instance, if the previously generated song ID is: e0347cce-97f7-4a1c-84c4-d59246428241, then you can set the parameters as follows:

{
  "action": "cover",
  "lyric":"girl girl girl",
  "style": "rock, punk",
  "model": "chirp-v4-tau",
  "audio_id": "e0347cce-97f7-4a1c-84c4-d59246428241"
}

Other parameters remain the same, and the result returned is a remade version of the song, which is the result of the original song being remade, as shown below:

{
    "success": true,
    "task_id": "87d0de46-8976-4e26-a28d-4d83211f8e26",
    "trace_id": "b0375262-5c96-4b13-b80a-df5dc5f16ad2",
    "data": [
        {
            "id": "d1df73a1-38f3-4405-bbdc-f0a433c19dc7",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_d1df73a1-38f3-4405-bbdc-f0a433c19dc7.jpeg",
            "lyric": "girl girl girl",
            "audio_url": "https://cdn1.suno.ai/d1df73a1-38f3-4405-bbdc-f0a433c19dc7.mp3",
            "video_url": "https://cdn1.suno.ai/d1df73a1-38f3-4405-bbdc-f0a433c19dc7.mp4",
            "created_at": "2024-12-22T03:50:50.822Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "rock, punk",
            "duration": 161.68
        },
        {
            "id": "2c45f5ba-6af7-40a6-b62f-9ced54548b12",
            "title": "",
            "image_url": "https://cdn2.suno.ai/image_2c45f5ba-6af7-40a6-b62f-9ced54548b12.jpeg",
            "lyric": "girl girl girl",
            "audio_url": "https://cdn1.suno.ai/2c45f5ba-6af7-40a6-b62f-9ced54548b12.mp3",
            "video_url": "https://cdn1.suno.ai/2c45f5ba-6af7-40a6-b62f-9ced54548b12.mp4",
            "created_at": "2024-12-22T03:50:50.822Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "rock, punk",
            "duration": 170.28
        }
    ]
}

The generated result is similar to the above, completing the process of creating a cover version of the originally generated song.

Replace Section

When a song is generated and you need to perform a separate operation of replacing a song section for secondary creation, you can replace a specific section of the song. You can specify the following content:

  • action: Content is replace_section.
  • audio_id: The ID of the previously generated song.
  • model: Song generation model,
  • lyric: The complete lyrics after replacement (only needs to have overlap with the prompt, not the full lyrics),
  • prompt: The part of the lyrics that needs to be replaced.
  • style: The style of the song, optional.
  • replace_section_start: The start time of the lyric on the lyrics timeline.
  • replace_section_end: The end time of the lyric on the lyrics timeline.

For example, if the ID of the originally generated song is: ade7241b-0357-4a5e-9b3d-4ec4f4b3a0c0, you can set the parameters as follows:

{
  "action": "replace_section",
  "lyric": "[Chorus]\nHappy New Year Everyone sings joyfully\nBlessings spread to every corner\nHappy New Year Many fireworks in the heart\nWishes come true, life is like golden waves\n[Verse 2]\nPlum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth",
  "prompt": "Plum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth",
  "replace_section_start": 28.94100580270793,
  "replace_section_end": 85.39410058027079,
  "model": "chirp-v4",
  "audio_id": "ade7241b-0357-4a5e-9b3d-4ec4f4b3a0c0",
  "custom": false,
  "instrumental": false
}

Other parameters remain unchanged, and the returned result is a song with the replaced section, which is the result after replacing a section of the originally generated song, as shown in the example below:

{
    "success": true,
    "task_id": "7a37c35d-7081-413d-908d-ab2d3f8139bf",
    "trace_id": "1ed92d6e-9a19-48f7-ab34-68c82c792303",
    "data": [
        {
            "id": "2a1467dc-51a4-4872-9ccc-ccd96e4fbbb6",
            "title": "Happy New Year",
            "image_url": "https://cdn2.suno.ai/image_dc1b5edc-fbae-44a3-8962-d596dbd2b0d7.jpeg",
            "lyric": "[Chorus]\nHappy New Year Everyone sings joyfully\nBlessings spread to every corner\nHappy New Year Many fireworks in the heart\nWishes come true, life is like golden waves\n[Verse 2]\nPlum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth",
            "audio_url": "https://cdn1.suno.ai/2a1467dc-51a4-4872-9ccc-ccd96e4fbbb6.mp3",
            "video_url": "",
            "created_at": "2025-04-18T01:55:02.930Z",
            "model": "chirp-v4",
            "state": "succeeded",
            "style": "traditional influences, female vocals",
            "duration": 202.52,
            "concat_history": [
                {
                    "id": "ade7241b-0357-4a5e-9b3d-4ec4f4b3a0c0",
                    "type": "gen",
                    "source": "ios",
                    "infill_start_s": 28.94100580270793,
                    "infill_end_s": 85.39410058027079,
                    "infill_dur_s": 56.45309477756285,
                    "infill_context_start_s": 0,
                    "infill_context_end_s": 115.39410058027079,
                    "include_future_s": 2,
                    "include_history_s": 2,
                    "infill": true,
                    "infill_lyrics": "Plum blossoms bloom, spring is full of the earth\nPlum blossoms bloom, spring is full of the earth"
                },
                {
                    "id": "dc1b5edc-fbae-44a3-8962-d596dbd2b0d7"
                }
            ]
        }
    ]
}

The generated result is similar to the above, completing the process of replacing a section of the originally generated song.

Vocal and Instrumental Separation

When a song is generated and you need to perform separate operations for accompaniment and vocals for secondary creation, you can separate pure music accompaniment and a cappella vocals. You can specify the following content:

  • action: Content is stems.
  • audio_id: The ID of the previously generated song.

For example, if the ID of the originally generated song is: ec13e502-d043-4eb2-92ee-e900c6da69d1, you can set the parameters as follows:

{
  "audio_id": "ec13e502-d043-4eb2-92ee-e900c6da69d1"
}

Other parameters remain unchanged, and the output is simply a revamped version of the song—it's the result of remixing the originally generated song. Sample:

{
  "success": true,
  "task_id": "4050affc-f8a6-4cba-a86c-bf201eed053d",
  "trace_id": "5107ee58-687d-422f-9195-fa0e82e1fcc8",
  "data": [
    {
      "id": "e3de0928-085a-42c4-b982-3b24738d1989",
      "title": "Deck the Sky - Vocals",
      "image_url": "https://cdn2.suno.ai/image_e3de0928-085a-42c4-b982-3b24738d1989.jpeg",
      "lyric": "[Verse]\nSnowflakes dance on rooftops high\nChildren's laughter fills the sky\nCarols ring from church bells loud\nHolidays a joyful crowd\n[Verse 2]\nCandy canes and cocoa warm\nWrapped up tight in our own storm\nStockings hung with dreams and cheer\nMagic growing every year\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright\n[Verse 3]\nFireside tales of long ago\nReindeer prance in icy glow\nEvergreen and tinsel’s gleam\nChristmas time a lovely dream\n[Bridge]\nHearts are full with friends and kin\nMistletoe for love to win\nGifts of love and hope we share\nChristmas spirit everywhere\n[Chorus]\nDeck the sky with twinkling stars\nHoliday joy feels ours and ours\nSing the songs of love and light\nChristmas glows so pure and bright",
      "audio_url": "https://cdn1.suno.ai/e3de0928-085a-42c4-b982-3b24738d1989.mp3",
      "video_url": "https://cdn1.suno.ai/e3de0928-085a-42c4-b982-3b24738d1989.mp4",
      "created_at": "2025-01-05T07:49:16.881Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    },
    {
      "id": "ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb",
      "title": "Deck the Sky - Instrumental",
      "image_url": "https://cdn2.suno.ai/image_ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb.jpeg",
      "lyric": "",
      "audio_url": "https://cdn1.suno.ai/ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb.mp3",
      "video_url": "https://cdn1.suno.ai/ad5d7c89-709c-4eb4-a5a6-72f9f5e57fdb.mp4",
      "created_at": "2025-01-05T07:49:16.892Z",
      "model": "",
      "state": "succeeded",
      "style": "holiday, jolly",
      "duration": 174.16
    }
  ]
}

The generated result is similar to the text above, completing the process of sound and track separation for the originally created song.

Asynchronous Callback

Since Suno's music generation takes relatively a longer time, around 1-2 minutes, if the API doesn't respond for a long time, the HTTP request remains connected, leading to extra consumption of system resources. Therefore, this API also provides asynchronous callback support.

The overall flow is: when the client makes a request, it additionally specifies a callback_url field. After the client initiates an API request, the API immediately returns a result containing a task_id field, representing the current task ID. Once the task is complete, the generated music result will be sent to the client-specified callback_url in POST JSON format, which also includes the task_id field, allowing the task result to be linked through the ID.

Below is an example to illustrate how to operate.

First, the Webhook callback is a service that can receive HTTP requests, and developers should replace it with the URL of their own HTTP server. For demonstration purposes here, we use a public Webhook sample at https://webhook.site/. Visiting this site provides a Webhook URL, as shown below:

Copy this URL, and it can be used as a Webhook. In this example, it's https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2.

Next, we can set the field callback_url to the Webhook URL above and fill in prompt, as shown below:

Click run, and we can immediately get a result like this:

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

After waiting for a moment, we can observe the generated song result at https://webhook.site/03e60575-3d96-4132-b681-b713d78116e2, as shown:

The content is as follows:

{
  "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"
    }
  ]
}

You can see that the result contains a task_id field, and other fields are similar to the above text, through which the task can be associated.

Error Handling

If an error occurs, you will receive an error message similar to the following:

{
  "success": false,
  "error": {
    "code": "forbidden",
    "message": "Song Description contained artist name: eminem"
  },
  "trace_id": "9bb7c2f4-3b7b-4965-b50a-f663874b1b6f",
  "task_id": "9bb3a2a6-c438-436d-a9f3-fa466abc077c"
}

Below is a list of HTTP Status Code, error.code, error.message:

Status Code error.code error.message
400 bad_request instrumental must be a boolean
400 bad_request style must be less than or equal 120
400 bad_request custom must be a boolean
400 bad_request audio_id is required when extend audio
400 bad_request continue_at is required when extend audio
400 bad_request continue_at must be a number greater than 0
400 bad_request lyric is required when extend audio and instrumental is false
400 bad_request prompt is required when generate audio
400 bad_request lyric is required when generate custom audio
403 forbidden Prompt likely malformed
403 forbidden Prompt likely copyrighted
403 forbidden Prompt contained inappropriate material
403 forbidden Song Description flagged for moderation
403 forbidden Song Description contained artist name
403 forbidden Song Description contained producer tag
500 api_error Unable to generate lyrics from song description
500 api_error job failed with unknown error
500 api_error no available worker in system
500 api_error service under maintenance, generation paused
504 timeout timeout while waiting for audio generation