Suno API Scenario Application Guide

Overview

API Version: 2025.05 suno supports new version v4.5, mv parameter is chirp-auk

Submit Endpoint: POST https://api.cometapi.com/suno/submit/music

Fetch Result: GET https://api.cometapi.com/suno/fetch/{task_id}

Basic Request Format

1. Inspiration Mode

Generate music through simple descriptions.

{
  "gpt_description_prompt": "nostalgia"
}

2. Custom Lyrics and Title

Fully customize lyrics, title, and style tags.

{
  "prompt": "[Verse]\nBusy days keep going on\nFiles piled up with no end\nHiding dreams in drawers deep\nCoffee cup has gone cold\n\n[Verse 2]\nClock in at eight in the morning\nTired eyes without spirit\nChit-chat among colleagues is boring\nJust hoping time runs faster\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true\n\n[Verse 3]\nLunch time eating a bento\nWatching sunshine bright outside\nLife is far from dreams\nOnly desks and chairs in sight\n\n[Bridge]\nBoss's footsteps like thunder\nHeartbeat speeds up with the rhythm\nPiles of documents on the desk\nComplaints gradually disappear\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true",
  "mv": "chirp-auk",
  "title": "Work",
  "tags": " edm"
}

3. Custom Instrumental

Generate instrumental music without lyrics.

{
  "prompt": "",
  "tags": "heavy metal",
  "mv": "chirp-auk",
  "title": "Beijing",
  "continue_clip_id": null,
  "continue_at": null,
  "infill_start_s": null,
  "infill_end_s": null
}

4. Instrumental Inspiration Mode

Generate instrumental music through descriptions.

{
  "gpt_description_prompt": "An anthem dance pop song about dancing all night",
  "mv": "chirp-auk",
  "prompt": "",
  "make_instrumental": true
}

5. Continue Custom Audio

A. Upload Music

First get clip_id value through upload interface

B. Extend Music (with version info)

{
  "prompt": "lyrics",
  "tags": "",
  "negative_tags": "",
  "mv": "chirp-v4",
  "title": "title",
  "continue_clip_id": "ca94a97d-d3f2-4a63-aeee-ba3a43384bcd",
  "continue_at": 10,
  "task": "upload_extend"
}

C. Extend Music (to be deprecated)

Note: Here mv is chirp-auk-upload or chirp-v4-upload

{
  "prompt": "[Verse]\nBusy days keep going on\nFiles piled up with no end\nHiding dreams in drawers deep\nCoffee cup has gone cold\n\n[Verse 2]\nClock in at eight in the morning\nTired eyes without spirit\nChit-chat among colleagues is boring\nJust hoping time runs faster\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true\n\n[Verse 3]\nLunch time eating a bento\nWatching sunshine bright outside\nLife is far from dreams\nOnly desks and chairs in sight\n\n[Bridge]\nBoss's footsteps like thunder\nHeartbeat speeds up with the rhythm\nPiles of documents on the desk\nComplaints gradually disappear\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true",
  "tags": "heavy metal",
  "mv": "chirp-auk-upload",
  "title": "Work",
  "continue_clip_id": "abcd-1234-1234-1234-abd",
  "continue_at": 30.792
}

D. Concat Complete Music

Note: is_infill is false
Cost: One song fee

Endpoint: POST https://api.cometapi.com/suno/submit/music/concat

6. Continue Music and Get Complete Music

Note: Continue official generated music, custom not available

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value

B. Extend Music

Will get 2 new clip_ids, take one of them

{
  "prompt": "[Verse]\nBusy days keep going on\nFiles piled up with no end\nHiding dreams in drawers deep\nCoffee cup has gone cold\n\n[Verse 2]\nClock in at eight in the morning\nTired eyes without spirit\nChit-chat among colleagues is boring\nJust hoping time runs faster\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true\n\n[Verse 3]\nLunch time eating a bento\nWatching sunshine bright outside\nLife is far from dreams\nOnly desks and chairs in sight\n\n[Bridge]\nBoss's footsteps like thunder\nHeartbeat speeds up with the rhythm\nPiles of documents on the desk\nComplaints gradually disappear\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true",
  "tags": "heavy metal",
  "mv": "chirp-auk",
  "title": "Work",
  "continue_clip_id": "abcd-1234-1234-1234-abd",
  "continue_at": 30,
  "task": "extend"
}

C. Concat Complete Music

Note: is_infill is false
Cost: 0.1

Endpoint: POST https://api.cometapi.com/suno/submit/music/concat

7. Cover Music: Music Remake/Style Change

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value
Can also get clip_id through upload interface, thus can cover custom audio

B. Cover Music

Note:
mv is chirp-v3-5-tau or chirp-v4-tau or chirp-auk
task is cover
Can be used cross-account, no need to worry about account offline
cover_clip_id if it's upload clip_id cannot be cross-account

{
  "prompt": "[Verse]\nBusy days keep going on\nFiles piled up with no end\nHiding dreams in drawers deep\nCoffee cup has gone cold\n\n[Verse 2]\nClock in at eight in the morning\nTired eyes without spirit\nChit-chat among colleagues is boring\nJust hoping time runs faster\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true\n\n[Verse 3]\nLunch time eating a bento\nWatching sunshine bright outside\nLife is far from dreams\nOnly desks and chairs in sight\n\n[Bridge]\nBoss's footsteps like thunder\nHeartbeat speeds up with the rhythm\nPiles of documents on the desk\nComplaints gradually disappear\n\n[Chorus]\nWork work boss is calling\nFinish finish to be safe\nOvertime overtime to earn money\nDreams dreams when will they come true",
  "generation_type": "TEXT",
  "tags": "rock, punk",
  "negative_tags": "",
  "mv": "chirp-v4-tau",
  "title": "Work (Cover)",
  "continue_clip_id": null,
  "continue_at": null,
  "continued_aligned_prompt": null,
  "infill_start_s": null,
  "infill_end_s": null,
  "task": "cover",
  "cover_clip_id": "abcd-1234-1234-1234-abd"
}

8. Replace Section: Replace Fragment

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value

B. Replace Section

Note:
task is infill
mv is chirp-v3-5-tau or chirp-v4-tau or chirp-auk
Replaced lyrics should have overlapping parts with original lyrics, best if corresponding time can match
infill_start_s start time, infill_end_s end time, infill_dur_s is infill_end_s-infill_start_s
Can be used cross-account, no need to worry about account offline
Will get 2 new clip_ids, choose one for next step

{
  "task": "infill",
  "generation_type": "TEXT",
  "title": "Degrees of Missing-replace",
  "tags": "Sorrow/Sad,Female Vocals,Mandarin",
  "mv": "chirp-auk",
  "prompt": "《Degrees of Missing》 \n \nLyrics: A Guo Yi Luo\nThe annual rings record the temperature of your running. \nEvery falling leaf is calling for you\nBut the wind blows and breaks into mist. \nOrganizing your guitar in the corner \nThe guitar case accumulates all rainy seasons, \nWetting the back of rosewood. \nIf I wind missing into new strings, \nAfraid it will break into \nThe echoes of those years. \nTime is a rewinding tape, \nThe deeper the night, the clearer your laughter comes. \nIf tears could water the time tunnel, \nI would cry my eyes into the sea. \nWhen all springs are related to you, \nI learned to breathe with wounds. \nContinue loving you, \nWith all",
  "metadata": {
    "infill_lyrics": ". \nOrganizing your guitar in the corner \nThe guitar case accumulates all rainy seasons, \nWetting the back of rosewood. \nIf I wind missing into new strings, \nAfraid it will break into \nThe echoes of those years"
  },
  "continue_clip_id": "8a858961-8831-4423-8ffb-2dec096aea0a",
  "continued_aligned_prompt": "《Degrees of Missing》 \n \nLyrics: A Guo Yi Luo\nThe annual rings record the temperature of your running. \nEvery falling leaf is calling for you\nBut the wind blows and breaks into mist. \nOrganizing your guitar in the corner \nThe guitar case accumulates all rainy seasons, \nWetting the back of rosewood. \nIf I wind missing into new strings, \nAfraid it will break into \nThe echoes of those years. \nTime is a rewinding tape, \nThe deeper the night, the clearer your laughter comes. \nIf tears could water the time tunnel, \nI would cry my eyes into the sea. \nWhen all springs are related to you, \nI learned to breathe with wounds. \nContinue loving you, \nWith all \nNo longer beating heartbeats.\nOrganizing your guitar in the corner \nThe guitar case accumulates all rainy seasons, \nWetting the back of rosewood. \nIf I wind missing into new strings, \nAfraid it will break into \nThe echoes of those years. \nWhen all springs are related to you, \nI learned to breathe with wounds. \nContinue loving you, \nWith all \nNo longer beating heartbeats.\n",
  "infill_context_start_s": 3.48,
  "infill_context_end_s": 109.96,
  "infill_start_s": 33.48,
  "infill_end_s": 79.96,
  "infill_dur_s": 46.48
}

C. Confirm Concat Complete Music

Note:
is_infill is true
Cost: 0.1

Endpoint: POST https://api.cometapi.com/suno/submit/music/concat

9. Persona: Singer Style

A. Generate Music

step1. Generate music through any of scenarios 1, 2, 3, must be version 4.5, get task id

step2. After getting task id, get corresponding clip_id value of the song as needed

B. Create New Persona

Note:
Input the corresponding clip_id into this interface, the returned id is persona_id for next step
clip_id needs to exist in the system, not uploader
Cannot be cross-account, so may not be available if account is offline
Will deduct 0.1 to prevent abuse

Endpoint: POST https://api.cometapi.com/suno/persona/create

{
  "root_clip_id": "54834687-5e79-4f08-8e14-cf188f15b598",
  "name": "Persona Title",
  "description": "Persona Description",
  "clips": ["54834687-5e79-4f08-8e14-cf188f15b598"],
  "is_public": true
}

C. Create with persona_id

Using endpoint: Create new persona Notes:**
mv is chirp-v3-5-tau or chirp-v4-tau or chirp-auk
task is artist_consistency
persona_id is the returned id from create new persona step
artist_clip_id is the clip_id from generate music step
Can be cross-account

Endpoint: POST https://api.cometapi.com/suno/submit/music

{
  "prompt": "[Verse]\nFrom dawn to dusk you're here\nAlways warm by my side dear\nWind and rain we have no fear\nHolding hands we persevere\n\n[Verse 2]\nWith you I'm never alone\nLike stars when night has shown\nRoad is long but feels like home\nBecause you're my guiding tone\n\n[Chorus]\nHusband husband I love you\nYou're the only one it's true\nNo matter where we may pursue\nOur hearts together like morning dew\n\n[Verse 3]\nYou're my safe harbor strong\nEvery night you're in my song\nEven when the path is long\nWith you everything belongs\n\n[Chorus]\nHusband husband I love you\nYou're the only one it's true\nNo matter where we may pursue\nOur hearts together like morning dew\n\n[Bridge]\nEvery moment of our life\nWith you by my side no strife\nAll tomorrows will be bright\nBecause with you I win the fight",
  "generation_type": "TEXT",
  "tags": "electronic, pop",
  "negative_tags": "",
  "mv": "chirp-v4-tau",
  "title": "Husband",
  "task": "artist_consistency",
  "persona_id": "0f6e8077-a7ba-4fc8-8f60-de02c66e56ce",
  "artist_clip_id": "a5fa604c-18b8-4e7f-8d25-9412d4ba8163"
}

10. All-Stems: Full Track Voice Separation

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value

B. Full Track Voice Separation

Note:
mv is chirp-auk
task is gen_stem
stem_task is twelve
stem_type_group_name is Twelve
continue_clip_id is the clip_id from step A
Can be cross-account
Billing: 5 times base price, price of 5 times 10 songs

Endpoint: POST https://api.cometapi.com/suno/submit/music

{
  "task": "gen_stem",
  "generation_type": "TEXT",
  "title": "Safety String",
  "mv": "chirp-auk",
  "prompt": "",
  "make_instrumental": true,
  "continue_clip_id": "4720ad51-6d31-417c-a3a7-346b0b99abbc",
  "continued_aligned_prompt": null,
  "continue_at": null,
  "stem_type_id": 91,
  "stem_type_group_name": "Twelve",
  "stem_task": "twelve"
}

C. Get Results

Returns 24 clip_ids, query using task id

Endpoint: GET https://api.cometapi.com/suno/fetch/{task_id}

11. Stems: Single Track Voice Separation

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value

B. Voice Separation

Note:
mv is chirp-auk
task is gen_stem
stem_task is two
stem_type_group_name is Two
continue_clip_id is the clip_id from step A
Can be cross-account
Billing: Five generation fees

Endpoint: POST https://api.cometapi.com/suno/submit/music

{
  "task": "gen_stem",
  "generation_type": "TEXT",
  "title": "Safety String",
  "mv": "chirp-auk",
  "prompt": "",
  "make_instrumental": true,
  "continue_clip_id": "4720ad51-6d31-417c-a3a7-346b0b99abbc",
  "continued_aligned_prompt": null,
  "continue_at": null,
  "stem_type_id": 91,
  "stem_type_group_name": "Two",
  "stem_task": "two"
}

C. Get Results

Endpoint: GET https://api.cometapi.com/suno/fetch/{task_id}

12. Timing: Lyrics and Audio Timeline

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value

B. Get Lyrics

Note: Can be cross-account

Endpoint: GET https://api.cometapi.com/suno/act/timing/{clip_id}

13. WAV: Get WAV Format File

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value as a624123d-22cc-4d4d-bf28-78d312f61597

B. Get WAV File

Note:
If response body wav_file_url is null, try getting it a few more times
Will deduct 0.1 to prevent abuse
Cannot be cross-account, cannot be called after account is offline

Endpoint: GET https://api.cometapi.com/suno/act/wav/{clip_id}

14. MP4: Generate MP4 MV Video

A. Generate Music

Can generate music through scenarios 1, 2, 3, get one song's clip_id value

B. Get MP4 File

Note:
Status needs to be complete for execution to be effective
Need to wait 30 seconds after execution for URL to be accessible
Will deduct 0.1 to prevent abuse
Cannot be cross-account, cannot be called after account is offline

Endpoint: GET https://api.cometapi.com/suno/act/mp4/{clip_id}

15. Premium Parameters

In July 2025, suno added 3 premium parameters:

weirdness_constraint

style_weight

audio_weight (only appears during cover)

Values are all between 0-1

A. Normal Generation

Endpoint: POST https://api.cometapi.com/suno/submit/music

{
  "prompt": "[Verse]\nI got a plate of dreams piled high\nA world of flavors I wanna try\nSpices dancing under the sky\nTaste buds soaring I won't deny\n\n[Chorus]\nCrunch and sizzle sweet and sour\nEvery bite holds a little power\nBite by bite I'm feeling bold\nLife's a buffet can't be controlled\n\n[Verse 2]\nFrom tacos wrapped so tight with love\nTo noodles swimming skies above\nPizza slices like a dove\nFlying straight to my tastebud glove\n\n[Bridge]\nOh the crunch of chips so loud\nPopcorn popping in a cloud\nChocolate melting makes me proud\nIn this feast I'm unbowed\n\n[Chorus]\nCrunch and sizzle sweet and sour\nEvery bite holds a little power\nBite by bite I'm feeling bold\nLife's a buffet can't be controlled\n\n[Verse 3]\nSaucy rivers on a plate\nFlavors whispering don't be late\nEvery meal's a twist of fate\nI'll devour till it's too great",
  "generation_type": "TEXT",
  "tags": "house, tight drums",
  "negative_tags": "modern",
  "mv": "chirp-auk",
  "title": "Savor the Flavor",
  "metadata": {
    "create_mode": "custom",
    "control_sliders": {
      "style_weight": 0.4,
      "weirdness_constraint": 0.7
    },
    "can_control_sliders": ["weirdness_constraint", "style_weight"]
  }
}

B. Cover Generation

During cover there will be an audio_weight parameter

Endpoint: POST https://api.cometapi.com/suno/submit/music

{
  "prompt": "[Verse]\nNew Year bells are ringing\nFireworks light up the evening\nLaughter spreads in all directions\nGood luck stays by our side\n\n[Chorus]\nHappy New Year joy abounds\nRed lanterns hanging all around\nReunion happiness blooms profound\nWishes come true blessings resound\n\n[Verse 2]\nSpring breeze gently blowing\nBringing auspicious flowers growing\nNew clothes new shoes new hoping\nDreams from now on unfolding\n\n[Chorus]\nHappy New Year joy abounds\nRed lanterns hanging all around\nReunion happiness blooms profound\nWishes come true blessings resound\n\n[Bridge]\nFirecrackers popping loud and clear\nWelcoming new chances here\nEvery household full of cheer\nNew Year spirit everywhere\n\n[Chorus]\nHappy New Year joy abounds\nRed lanterns hanging all around\nReunion happiness blooms profound\nWishes come true blessings resound",
  "generation_type": "TEXT",
  "tags": "",
  "negative_tags": "",
  "mv": "chirp-auk",
  "title": "Happy New Year (Remix)",
  "task": "cover",
  "cover_clip_id": "f31754fc-2c83-4fc1-8a07-70ae218dd0a6",
  "metadata": {
    "create_mode": "custom",
    "control_sliders": {
      "style_weight": 0.68,
      "audio_weight": 0.48,
      "weirdness_constraint": 0.37
    },
    "can_control_sliders": [
      "weirdness_constraint",
      "style_weight",
      "audio_weight"
    ],
    "is_remix": true
  }
}

Suno API Scenario Application Guide

Overview#

Basic Request Format#

1. Inspiration Mode#

2. Custom Lyrics and Title#

3. Custom Instrumental#

4. Instrumental Inspiration Mode#

5. Continue Custom Audio#

A. Upload Music#

B. Extend Music (with version info)#

C. Extend Music (to be deprecated)#

D. Concat Complete Music#

6. Continue Music and Get Complete Music#

A. Generate Music#

B. Extend Music#

C. Concat Complete Music#

7. Cover Music: Music Remake/Style Change#

A. Generate Music#

B. Cover Music#

8. Replace Section: Replace Fragment#

A. Generate Music#

B. Replace Section#

C. Confirm Concat Complete Music#

9. Persona: Singer Style#

A. Generate Music#

B. Create New Persona#

C. Create with persona_id#

10. All-Stems: Full Track Voice Separation#

A. Generate Music#

B. Full Track Voice Separation#

C. Get Results#

11. Stems: Single Track Voice Separation#

A. Generate Music#

B. Voice Separation#

C. Get Results#

12. Timing: Lyrics and Audio Timeline#

A. Generate Music#

B. Get Lyrics#

13. WAV: Get WAV Format File#

A. Generate Music#

B. Get WAV File#

14. MP4: Generate MP4 MV Video#

A. Generate Music#

B. Get MP4 File#

15. Premium Parameters#

A. Normal Generation#

B. Cover Generation#

Overview

Basic Request Format

1. Inspiration Mode

2. Custom Lyrics and Title

3. Custom Instrumental

4. Instrumental Inspiration Mode

5. Continue Custom Audio

A. Upload Music

B. Extend Music (with version info)

C. Extend Music (to be deprecated)

D. Concat Complete Music

6. Continue Music and Get Complete Music

A. Generate Music

B. Extend Music

C. Concat Complete Music

7. Cover Music: Music Remake/Style Change

A. Generate Music

B. Cover Music

8. Replace Section: Replace Fragment

A. Generate Music

B. Replace Section

C. Confirm Concat Complete Music

9. Persona: Singer Style

A. Generate Music

B. Create New Persona

C. Create with persona_id

10. All-Stems: Full Track Voice Separation

A. Generate Music

B. Full Track Voice Separation

C. Get Results

11. Stems: Single Track Voice Separation

A. Generate Music

B. Voice Separation

C. Get Results

12. Timing: Lyrics and Audio Timeline

A. Generate Music

B. Get Lyrics

13. WAV: Get WAV Format File

A. Generate Music

B. Get WAV File

14. MP4: Generate MP4 MV Video

A. Generate Music

B. Get MP4 File

15. Premium Parameters

A. Normal Generation

B. Cover Generation