AI Music API
Home
Home
  1. suno
  • Introduction
  • Credits Usage Guide
  • Error handling
  • Webhook Integration Guide
  • suno
    • Suno Instructions
    • create music (custom mode)
      POST
    • create music (no-custom mode)
      POST
    • create music (Control singer gender)
      POST
    • create music (auto lyrics mode)
      POST
    • extend music
      POST
    • concat music
      POST
    • cover music
      POST
    • remaster
      POST
    • add vocal
      POST
    • add instrumental
      POST
    • stems basic
      POST
    • stems full
      POST
    • create persona
      POST
    • create music with persona
      POST
    • upload music
      POST
    • get wav
      POST
    • get midi
      POST
    • get music
      GET
  • riffusion(Deprecated)
    • Riffusion instructions
    • create music (with lyrics)
      POST
    • create music (with description)
      POST
    • cover music
      POST
    • extend music
      POST
    • replace music section
      POST
    • swap music sound
      POST
    • swap music vocals
      POST
    • upload
      POST
    • get music
      GET
  • producer
    • Producer Instructions
    • Complete Request Example
    • create music
    • upload
    • download
    • get music
  • nuro
    • Nuro Instruction
    • Error handling
    • create vocal music
    • create instrument music
    • get music
  • lyrics generation
    • Make Lyrics
  • get-credits
    GET
  1. suno

Suno Instructions

Key Field Usage#

1. Custom Mode: custom_mode = true#

In this mode, you can customize the song's title, style, and lyrics, corresponding to the fields:
title
tags
prompt

2. Non-Custom Mode: custom_mode = false#

In this mode, you only need the gpt_description_prompt field to describe the music.

3. Instrumental Control#

Use the make_instrumental field to control whether to generate instrumental-only music.

Field Details#

custom_mode:
A boolean switch for enabling custom mode.
Required
When enabled, it allows you to control the song's title, style, and lyrics.
prompt:
The song's lyrics.
Required if custom mode is enabled.
for v4.5+ and v4.5-plus and v5, Should generally not exceed 5000 characters
for v4 and below, Should generally not exceed 3000 characters
title:
The song's title.
Optional
Should generally not exceed 80 characters.
tags:
The song's style or genre.
Optional
for v4.5+ and v4.5-plus and v5, Should generally not exceed 1000 characters
for v4 and below, Should generally not exceed 200 characters
mv:
The model version for generation.
Required
Can be either chirp-v3-5 or chirp-v4 or chirp-v4-5 or chirp-v4-5-plusor chirp-v5.
make_instrumental:
Controls whether to generate instrumental-only music.
Optional
gpt_description_prompt:
A description of the song.
Required if custom mode is disabled.
Should generally not exceed 400 characters.
task_type:
Specifies the type of task to perform.
Required
Allowed values: create_music, extend_music, concat_music, cover_music,cover_upload_music, extend_upload_music, persona_music, remaster, add_instrumental, add_vocals.
persona_id:
The ID of a persona created via the "create persona" API.
Optional
This ID can be used to generate music based on the specified persona.
style_weight:
The weight of the tags field (style).
Optional
Range: >= 0 <= 1
weirdness_constraint:
The randomness or weirdness of the song.
Optional
Range: >= 0 <= 1
negative_tags:
Elements you want to avoid in your songs.
Optional
vocal_gender:
"f"(Female) or "m"(Male). control the vocal of gender,
support chirp-v4-5, chirp-v4-5-plus,chirp-v5
Optional
auto_lyrics:
weather auto generate lyrics and style,Must be used with custom_mode:true
Optional
variation_category:
Controls the variation intensity for remaster tasks.
Optional (only for task_type = remaster with mv = chirp-v5)
Allowed values: subtle, normal, high
Only supported when using the chirp-v5 model
audio_weight:
The weight of the original audio.
Optional (for task_type = add_instrumental or add_vocals or cover/cover_upload_music)
Range: >= 0 <= 1
overpainting_start_s:
The start time (in seconds) for adding vocals/instrumental to uploaded music.
Optional (for task_type = add_instrumental or add_vocals)
Default: 0
overpainting_end_s:
The end time (in seconds) for adding vocals/instrumental to uploaded music.
Optional (for task_type = add_instrumental or add_vocals)
Must be less than the total duration of the song

New Task Types#

1. Remaster Music (task_type = remaster)#

Remaster an existing music track with a different model version.
Required Fields:
continue_clip_id: The ID of the music to remaster
mv: Model version (chirp-v4-5-plus, chirp-v4, or chirp-v5)
Optional Fields:
variation_category: Variation intensity (only for chirp-v5)
subtle: Minor changes
normal: Moderate changes
high: Significant changes
Credits Cost: 10 credits

2. Add Instrumental (task_type = add_instrumental)#

Add instrumental backing to uploaded music. Suno will process the original audio, and the lyrics in the original audio may be altered. If you provide prompt, it will generate according to your desired lyrics.
Required Fields:
continue_clip_id: The ID of the uploaded music
mv: Model version (chirp-v4-5-plus or chirp-v5)
Optional Fields:
prompt: Desired lyrics (if provided, will generate according to these lyrics)
tags: Style tags
title: Track title
negative_tags: Elements to avoid
style_weight: Weight of the style (0-1)
weirdness_constraint: Randomness level (0-1)
audio_weight: Weight of the original audio (0-1)
overpainting_start_s: Start time in seconds
overpainting_end_s: End time in seconds
Credits Cost: 10 credits

3. Add Vocals (task_type = add_vocals)#

Add vocals to uploaded instrumental music.
Required Fields:
continue_clip_id: The ID of the uploaded music
mv: Model version (chirp-v4-5-plus or chirp-v5)
prompt: Lyrics (required)
Optional Fields:
tags: Style tags
title: Track title
negative_tags: Elements to avoid
style_weight: Weight of the style (0-1)
weirdness_constraint: Randomness level (0-1)
audio_weight: Weight of the original audio (0-1)
vocal_gender: Gender of vocals (f for female, m for male)
overpainting_start_s: Start time in seconds
overpainting_end_s: End time in seconds
Credits Cost: 10 credits

Note#

When use your own uploaded music, you need to use the upload task type.
For add_instrumental, and add_vocals tasks, the continue_clip_id must be from your own uploaded music.
Modified at 2025-11-10 12:46:43
Previous
Webhook Integration Guide
Next
create music (custom mode)
Built with