Suno Audios Generation API
https://api.worldai.chat/suno/audios
Suno AI music generation API, generates 2 songs per request with extension support.
Related Products
Suno - WorldAi
Suno music generation platform, directly interfaces with this API, high-speed and stable availability.
Request Headers
acceptstring
Specify the format of the response returned by the server. If not specified, the default format is `application/json`; if `application/x-ndjson` is specified, the response will be returned in a JSON format separated by newline characters, streamed back in chunks.
Please select
authorizationstring
Bearer token
Request Body
actionstring
Music generation operation types. `generate`: generate audio based on a prompt; `extend`: continue generating based on existing audio; `concat`: stitch existing audio clips into a complete track; `cover`: replicate the musical style of an existing track and reinterpret it; `upload_cover`: create a style cover of uploaded audio; `upload_extend`: extend and continue generating uploaded audio; `artist_consistency`: sing a new song in the style of a specified singer (Persona); `artist_consistency_vox`: sing a new song in the style of a specified singer using VOX mode; `stems`: separate a song into vocal and instrumental tracks; `all_stems`: separate a song into all individual tracks (vocals, drums, bass, other instruments); `add_stem`: add a new track to existing audio, with required `audio_id` and `stem_type`, and optional `prompt`, `title`, and `style`; `extract_stem`: extract a specified track from existing audio, with required `audio_id` and `stem_type`, and optional `audio_format`; `sounds`: generate standalone sound effects, with required `sound` and `sound_type`, and optional `bpm` and `key`; `adjust_speed`: adjust the playback speed of existing audio, with required `audio_id`, `speed_multiplier`, and `title`, while `keep_pitch` is optional; `replace_section`: replace a clip within a specified time range; `underpainting`: generate and add AI accompaniment for an uploaded vocal track; `overpainting`: generate and add AI vocals for an uploaded accompaniment track; `samples`: select a start and end range from an existing audio clip for sample-based creation; `remaster`: remaster existing audio to improve sound quality; `mashup`: mix and stitch multiple songs into one track; `inspo`: Inspo inspiration creation feature, using 1 to 4 dragged or uploaded reference audio clips to inspire entirely new music creation.
promptstring
Prompt words used to generate music in inspiration mode (effective when `custom` is `false`), with a maximum length of 500 characters. For custom mode, use `lyric` and `style` instead. When `action` is `add_stem`, this field is optional and is used to describe the track to be added.
lyric_promptstring
Prompts for automatically generating lyrics, effective only when `custom` is `true` and `lyric` is empty.
modelstring
Models used to generate music. Supports `chirp-v6`, `chirp-v6-wild`, and `chirp-v6-mini`; `chirp-v6` is recommended. Legacy model names remain compatible.
max_modeboolean
Whether to enable enhanced generation mode. Only `generate` (which also requires `custom` to be `true`) and `add_stem` are supported. When enabled, 1.12 and 1.344 Credits are consumed respectively; when disabled or omitted, billing is based on normal mode. Passing this parameter for other actions will return 400.
Please select
varietystring
The diversity strength of the generated results, optional: `off`, `normal`, `high`, `extra`, `max`. Only `generate` and `add_stem` are supported; passing it to other actions will return 400.
Please select
lyricstring
Lyrics for generating music under custom mode (`custom` is `true`). `chirp-v3-5` and `chirp-v4` have a maximum of 3000 characters; `chirp-v4-5` and above (including `chirp-v5`, `chirp-v5-5`) have a maximum of 5000 characters.
customboolean
Whether to enable the custom mode flag. If `true`, the audio will be generated based on the lyrics; otherwise, it will be generated based on the prompts.
Please select
instrumentalboolean
Instrumental mode (no lyrics), defaults to `false`, also applies to inspo. When set to `true`, the lyrics filled in above will be ignored.
Please select
titlestring
Music title (custom mode). `chirp-v3-5`, `chirp-v4` support up to 80 characters; `chirp-v4-5` and above (including `chirp-v5`, `chirp-v5-5`) support up to 100 characters. Optional when `action` is `add_stem`; required when `action` is `adjust_speed`.
stylestring
Music style description. `chirp-v3-5` and `chirp-v4` support a maximum of 200 characters; `chirp-v4-5` and above (including `chirp-v5`, `chirp-v5-5`) support a maximum of 1000 characters. Optional when `action` is `add_stem`.
variation_categorystring
Remaster variation intensity, only used for `remaster`, optional values are `high`, `normal`, `subtle`.
Please select
negative_tagsstring
Style or genre descriptions that are not desired to appear in the generated music, used for custom generation, and also supports style exclusion in `replace_section`. This interface currently does not set a fixed character limit for this field; excessively long content may still be unable to be processed, so it is recommended to keep the description concise.
vocal_genderstring
Voice gender preference, optional `m` (male voice) or `f` (female voice). This is a generation preference and is not guaranteed to be strictly followed.
Please select
soundstring
The sound effect description to be generated, required when `action` is `sounds`.
audio_idstring
Source audio ID. Required for extend, upload_extend, cover, upload_cover, concat, stems, all_stems, replace_section, underpainting, overpainting, remaster, samples, add_stem, extract_stem, and adjust_speed.
stem_typestring
Track type. Required when `action` is `add_stem` or `extract_stem`; supports `vocals`, `backing_vocals`, `drums`, `bass`, `guitar`, `keyboard`, `percussion`, `strings`, `synth`, `fx`, `brass`, `woodwinds`.
Please select
audio_urlsarray
List of reference audio URLs for the Inspo inspiration creation feature. You need to provide 1 to 4 publicly accessible HTTP(S) audio URLs. This field is required when `action` is `inspo`.
persona_idstring
Specify the Persona ID for the singer style or cloned voice, not audio_id. Supports generate, cover, upload_cover, artist_consistency, artist_consistency_vox; the latter two actions must provide persona_id, and may simultaneously provide the source song's audio_id. extend and upload_extend do not use an additional persona_id. The voice capability of mashup and inspo depends on the service channel; other actions are not guaranteed to apply this field. For private voice covers, first upload the original song at /suno/upload with the same persona_id, then use the returned audio_id. All steps must use the same channel, and there is no need to additionally specify vocal_gender.
mashup_audio_idsarray
Audio ID list for mixing and mashup. This field is required when `action` is `mashup`.
bpminteger
Sound effect target speed (beats per minute), optional only when `action` is `sounds`, must be an integer from 1 to 300.
keystring
The target mood of the sound effect, optional only when `action` is `sounds`.
durationinteger
Desired song duration (seconds), must be an integer between 10 and 360. Currently, only generate uses this field; other actions do not use it. The model may weaken or ignore this generation target; the actual duration is subject to the response.
weirdnessnumber
Weirdness, ranges from 0 to 1. Higher values generally make the result more experimental; 0 will be passed as a valid value. The specific effect depends on the operation type, mode, and model.
keep_pitchboolean
Whether to maintain the original pitch when adjusting speed, defaults to `false`, only used for `adjust_speed`.
Please select
sound_typestring
Sound effect type, required when `action` is `sounds`. `one-shot` indicates a one-shot sound effect, and `loop` indicates a loopable sound effect.
Please select
continue_atnumber
Continuation boundary, in seconds, must be greater than 0, supports decimals and will not be rounded. For example, 213.5 means generating subsequent segments starting from 3 minutes and 33.5 seconds. `lyric` and `style` only guide new content after this boundary and will not replace the lyrics or singing before the boundary in the source audio; if you want the entire song to use new lyrics, please use `generate` to regenerate, or use `cover` to reinterpret it.
samples_endnumber
The sampling end time of samples (seconds), required and must be greater than the start time, and must not exceed the duration of the source audio.
audio_formatstring
Output audio format, optional only when `action` is `extract_stem` or `sounds`, currently supports `mp3`.
Please select
audio_weightnumber
Influence weight of audio or voice characteristics, ranging from 0 to 1; 0 is also a valid value. It can be used for operations such as generation, continuation, cover singing, adding audio tracks, and voice consistency; in scenarios without reference audio or voice characteristics, the model may weaken or ignore this value.
samples_startnumber
The sampling start time of samples (seconds), defaults to 0, must not be less than 0, supports decimals.
style_influencenumber
Style influence, range 0 to 1. Higher values generally make the result closer to `style`; 0 is passed as a valid value. The specific effect depends on the operation type, mode, and model.
overpainting_endnumber
Add the end time of the AI voice to the uploaded audio, which must be less than the total duration of the song.
speed_multipliernumber
Playback speed multiplier, required when `action` is `adjust_speed`, ranging from 0.25 to 4.
underpainting_endnumber
Add the end time for the AI accompaniment to the uploaded audio, which must be less than the total duration of the song.
overpainting_startnumber
Set the default start time for the AI voice of the uploaded audio to 0.
replace_section_endnumber
The end time (seconds) of `replace_section`, required and must be greater than the start time, and must not exceed the duration of the source audio.
underpainting_startnumber
Set the default start time for the AI accompaniment added to the uploaded audio, with a default value of 0.
replace_section_startnumber
The start time (seconds) of `replace_section`, required and must not be less than 0. Decimals are supported.
replace_section_result_modestring
When `action` is `replace_section`, specify the return format. `full_song` (default) will concatenate 2 candidates separately and return 2 complete songs; `candidates` will return 2 uncombined replacement segment candidates, which need to be selected before calling `concat`.
Please select
callback_urlstring
Callback URL to be called after audio generation is complete.
asyncboolean
Whether to process in asynchronous mode. When set to `true`, the interface immediately returns `task_id`, without the need to provide `callback_url`, and then the result can be obtained by polling the corresponding task query interface; if `callback_url` is also provided, the result will be pushed to that callback address.
Please select
Response
Integration guide
Kind reminder: For streaming requests, the above code may not be fully applicable. Please refer to the integration documentation for changes.
Suno Music Generation
Allow Use General Balance
When 'Allow General Balance' is enabled, the general balance is used automatically if an app's balance is insufficient.