Suno Music Generation

POST

tasks

curl --request POST \
  --url https://api.qingbo.ai/v1/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "action": "<string>",
  "prompt": "<string>",
  "audio_urls": [
    "<string>"
  ],
  "callback_url": "<string>",
  "ref_task_id": "<string>",
  "audio_index": 123
}
'

import requests

url = "https://api.qingbo.ai/v1/tasks"

payload = {
    "model": "<string>",
    "action": "<string>",
    "prompt": "<string>",
    "audio_urls": ["<string>"],
    "callback_url": "<string>",
    "ref_task_id": "<string>",
    "audio_index": 123
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    action: '<string>',
    prompt: '<string>',
    audio_urls: ['<string>'],
    callback_url: '<string>',
    ref_task_id: '<string>',
    audio_index: 123
  })
};

fetch('https://api.qingbo.ai/v1/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qingbo.ai/v1/tasks"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"audio_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"ref_task_id\": \"<string>\",\n  \"audio_index\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.qingbo.ai/v1/tasks")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"audio_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"ref_task_id\": \"<string>\",\n  \"audio_index\": 123\n}")
  .asString();

suno is an action-based model: the model ID is fixed and the action field decides what a call does. Start a song from scratch with generate, then keep working on the same track — extend it, cover it, split its stems, edit it, export it — across 32 actions in total. Every action is submitted through the unified task endpoint POST /v1/tasks.

Quick start

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "generate",
    "prompt": "A gentle city folk song, rainy night, female vocal, guitar and piano",
    "version": "v5.5"
  }'

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "generate",
    "custom": true,
    "prompt": "[Verse]\nStreetlights turn the rain to golden thread\nI left my umbrella with yesterday",
    "title": "Rainy Night Southside",
    "style": "indie folk, female vocal, acoustic guitar",
    "vocal_gender": "Female",
    "version": "v5.5"
  }'

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "generate",
    "prompt": "Upbeat lo-fi study background music",
    "instrumental": true
  }'

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "lyrics",
    "prompt": "A short song about lighthouses and patience"
  }'

A successful submission returns a task_id. Retrieve the result with GET /v1/tasks/{task_id}, wait inline with Prefer: wait, or configure a webhook.

Request parameters

Actions

Create from scratch — no source track involved.

Action	What it does
`generate`	A complete song: inspiration mode takes a description, custom mode takes your lyrics
`inspo`	Build a new song from a reference recording; pass 1–4 references in `audio_urls`
`lyrics`	Write lyrics only, no audio
`sounds`	Generate a sound effect, optionally with type, BPM and key
`upsample_tags`	Expand a rough style description into fuller style tags
`upload`	Import your own audio so later actions can use it as a source track

Work on an existing track — the source is given by ref_task_id.

Action	What it does
`extend`	Continue the source track from second `continue_at`
`cover`	Re-perform the song in a different style
`remaster`	Remaster for better fidelity and overall polish
`sample`	Take `start_s`–`end_s` as a sample and develop it into a new song
`replace_section`	Replace `start_s`–`end_s`, optionally with new words in `infill_lyrics`
`mashup`	Mash songs up into a new arrangement
`concat`	Join segments into one finished track
`midi`	Produce MIDI from the song

Vocals and stems

Action	What it does
`stems`	Separate one stem, chosen with `stem_type`
`stems_all`	Separate every stem at once
`add_vocals`	Add vocals to an instrumental; the source must be audio imported with `upload`
`add_instrumental`	Add instrumentation to a vocal; the source must be audio imported with `upload`
`add_stem`	Layer an extra stem onto the source track
`vox`	Extract the vocal segment between `vocal_start_s` and `vocal_end_s`
`create_voice`	Build a reusable voice from the audio at `audio_url`
`persona`	Create a singer persona, reused later through `persona_id`

Audio editing

Action	What it does
`crop`	Keep only `start_s`–`end_s`
`remove_section`	Delete `start_s`–`end_s`
`fade_in` / `fade_out`	Fade in at the start or out at the end over `duration_s` seconds
`adjust_speed`	Change speed by `speed`; `keep_pitch` preserves the original pitch

Export and analysis

Action	What it does
`wav`	Export the source track as a WAV file
`download`	Export the source track as an audio file, in the formats given by `formats`
`generate_video`	Produce a music video for the song
`aligned_lyrics`	Return line-by-line lyric timings
`bpm`	Analyse the song’s BPM

Common parameters

string

required

Always suno.

string

default:"generate"

What this call does; see Actions for the full set.

string

A content description in inspiration mode, the lyrics themselves when custom: true, and the subject to write about for lyrics and sounds.

string[]

Reference audio URLs, publicly reachable. Accepted only by the inspo action, where it is required and takes 1–4 entries.

string

Completion callback URL; see Submit Task.

Creative parameters

These apply to the creative actions: generate, inspo, extend, cover, remaster, mashup, sample, replace_section, add_vocals, add_instrumental, add_stem, sounds. Parameters with a narrower range say so in the description.

Parameter	Type	Description
`version`	string	`v3.5`, `v4`, `v4.5`, `v4.5+`, `v4.5-all`, `v5`, `v5.5`; default `v5.5`. Affects audio quality
`custom`	boolean	Default `false`, `prompt` is a description; `true` makes `prompt` the lyrics
`title`	string	Song title. Also available on `fade_in`, `fade_out`, `adjust_speed`
`style`	string	Style tags, `generate` only
`tags`	string	Style tags, for `extend`, `cover`, `inspo`, `mashup`, `sample`, `add_vocals`, `add_instrumental`, `add_stem`, `replace_section`, `upsample_tags`
`negative_tags`	string	Styles to avoid
`instrumental`	boolean	Instrumental only, no vocals. `generate`, `mashup`, `sample` only; default `false`
`gpt_description`	string	Inspiration prompt, required when `custom: false`. For `extend`, `cover`, `mashup`, `sample`, `add_vocals`, `add_instrumental`, `add_stem`
`auto_lyrics`	boolean	Let the model write the lyrics. For `generate`, `extend`, `cover`, `inspo`, `mashup`, `sample`
`persona_id`	string	Reuse a voice created by the `persona` action. For `generate`, `extend`, `cover`, `mashup`
`vocal_gender`	string	`Male` or `Female`
`style_weight`	number	`0`–`1`, style weight
`weirdness_constraint`	number	`0`–`1`, creativity
`audio_weight`	number	`0`–`1`, audio weight

style and tags are two field names for the same thing: generate uses style, every other action uses tags.

Referencing a source track

string

The task_id of the task that produced the source track.

integer

default:"1"

Which track from the source task’s result to use, starting at 1.

Two exceptions: create_voice takes a publicly reachable audio_url, and upload takes audioFilePath for the file being imported.

Action-specific parameters

Parameter	Type	Actions	Description
`continue_at`	integer	`extend`	Second of the source track to continue from. Required
`start_s` / `end_s`	number	`crop`, `remove_section`, `replace_section`, `sample`	Range start and end in seconds. Required
`duration_s`	integer	`fade_in`, `fade_out`	Fade length in seconds, minimum `1`. Required
`speed`	number	`adjust_speed`	Playback speed multiplier. Required
`keep_pitch`	boolean	`adjust_speed`	Keep the original pitch while changing speed
`stem_type`	string	`stems`	Which stem to extract; default `lead_vocal`
`infill_lyrics`	string	`replace_section`	Lyrics to fill the replaced section with
`variation_category`	string	`remaster`	Remaster variation category
`type`	string	`sounds`	Sound-effect type
`bpm`	integer	`sounds`	Target BPM
`key`	string	`sounds`	Musical key
`lyrics_model`	string	`lyrics`	Model used for lyric writing
`formats`	array	`download`	Requested download formats, e.g. `["mp3","wav"]`; allowed values `mp3` / `m4a` / `wav`, at least one item. Required
`audio_url`	string	`create_voice`	Audio URL to build the voice from. Required
`audioFilePath`	string	`upload`	Path of the audio file to import. Required
`name`	string	`persona`	Persona name. Required
`describe`	string	`persona`	Persona description
`styles`	string	`persona`	Persona styles
`vox_audio_id`	string	`persona`	Which vox track to build the persona from
`vocal_start_s` / `vocal_end_s`	integer	`vox`, `persona`	Vocal segment start and end in seconds

Parameters are validated per action: sending an action-specific parameter with a different action, or sending anything beyond the fields above, returns 400 and is not billed.

Limits

This model produces one result per task; n is not supported. The inspo action takes 1 to 4 reference audio URLs.

Action	Required parameters
`inspo`	`audio_urls`
`extend`	`continue_at`
`crop`, `remove_section`, `replace_section`, `sample`	`start_s` and `end_s`
`fade_in`, `fade_out`	`duration_s`
`adjust_speed`	`speed`
`create_voice`	`audio_url`
`upload`	`audioFilePath`
`persona`	`name`
`download`	`formats`

Pricing

Billed per call, with a different price per action. Each action has its own flat rate, and that rate does not change with version, track length or prompt length. Full-generation actions (generate, extend, cover, remaster and similar) and full stem separation (stems_all) sit at the top; light actions such as lyrics, bpm and wav cost far less. Rates are in price_config.audio_prices on GET /v1/models, keyed by action, and in the console’s Model Market. What a single call actually cost is the cost field on the task response — an integer quota at 500,000 quota = 1 USD, not dollars. Only a successful result is billed. Failed and cancelled tasks, and tasks that return nothing deliverable, are refunded in full.

Response

{
  "task_id": "task-wave1789004688b950049238",
  "model": "suno",
  "action": "generate",
  "status": "completed",
  "progress": "100%",
  "created_at": 1788768570,
  "completed_at": 1788768689,
  "result": {
    "audios": [
      {
        "expires_at": 1789089508,
        "url": ["https://cdn.example.com/result.mp3"]
      },
      {
        "expires_at": 1789089508,
        "url": ["https://cdn.example.com/result.mp3"]
      }
    ]
  },
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1789004688b950049238",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1789004688b950049238/cancel"
  },
  "billing_status": "settled",
  "cost": 28125
}

{
  "task_id": "task-wave1789004688b950049238",
  "model": "suno",
  "action": "lyrics",
  "status": "completed",
  "progress": "100%",
  "created_at": 1788769423,
  "completed_at": 1788769434,
  "result": {
    "audios": {
      "lyrics": [
        {
          "prompt": "[Verse]\nStone tower stands so tall\n...",
          "tags": "[\"acoustic, melancholic, male vocals\"]",
          "title": "The Beacon's Call"
        }
      ]
    }
  },
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1789004688b950049238",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1789004688b950049238/cancel"
  },
  "billing_status": "settled",
  "cost": 4500
}

Audio-producing actions return their output in result.audios[]: url is an array of audio links and expires_at is when those links stop working. generate returns two candidate tracks, addressed later as audio_index 1 or 2. The lyrics action returns no audio: the lyric text sits in the prompt field of each result.audios.lyrics[] entry, alongside title and tags.

Examples

To keep working on the same song, take the task_id from generate and pass it as ref_task_id to the next action. Each follow-up action produces a new task_id of its own, which can be chained further.

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "extend",
    "ref_task_id": "task-wave1789004688b950049238",
    "audio_index": 1,
    "continue_at": 118
  }'

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "cover",
    "ref_task_id": "task-wave1789004688b950049238",
    "audio_index": 1,
    "tags": "city pop, 80s synth, male vocal"
  }'

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "stems",
    "ref_task_id": "task-wave1789004688b950049238",
    "audio_index": 1,
    "stem_type": "lead_vocal"
  }'

curl -X POST https://api.qingbo.ai/v1/tasks \
  -H "Authorization: Bearer $WAVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno",
    "action": "wav",
    "ref_task_id": "task-wave1789004688b950049238",
    "audio_index": 1
  }'

Suno Music Generation

curl --request POST \
  --url https://api.qingbo.ai/v1/tasks \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "<string>",
  "action": "<string>",
  "prompt": "<string>",
  "audio_urls": [
    "<string>"
  ],
  "callback_url": "<string>",
  "ref_task_id": "<string>",
  "audio_index": 123
}
'

import requests

url = "https://api.qingbo.ai/v1/tasks"

payload = {
    "model": "<string>",
    "action": "<string>",
    "prompt": "<string>",
    "audio_urls": ["<string>"],
    "callback_url": "<string>",
    "ref_task_id": "<string>",
    "audio_index": 123
}
headers = {"Content-Type": "application/json"}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    model: '<string>',
    action: '<string>',
    prompt: '<string>',
    audio_urls: ['<string>'],
    callback_url: '<string>',
    ref_task_id: '<string>',
    audio_index: 123
  })
};

fetch('https://api.qingbo.ai/v1/tasks', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.qingbo.ai/v1/tasks"

	payload := strings.NewReader("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"audio_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"ref_task_id\": \"<string>\",\n  \"audio_index\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.qingbo.ai/v1/tasks")
  .header("Content-Type", "application/json")
  .body("{\n  \"model\": \"<string>\",\n  \"action\": \"<string>\",\n  \"prompt\": \"<string>\",\n  \"audio_urls\": [\n    \"<string>\"\n  ],\n  \"callback_url\": \"<string>\",\n  \"ref_task_id\": \"<string>\",\n  \"audio_index\": 123\n}")
  .asString();

Text Generation

Image Generation

Video Generation

Audio

Tools & Embeddings

Task Management

Account & Usage

Suno Music Generation

Quick start

Request parameters

Actions

Common parameters

Creative parameters

Referencing a source track

Action-specific parameters

Limits

Pricing

Response

Examples

​Quick start

​Request parameters

​Actions

​Common parameters

​Creative parameters

​Referencing a source track

​Action-specific parameters

​Limits

​Pricing

​Response

​Examples

​Related

Quick start

Request parameters

Actions

Common parameters

Creative parameters

Referencing a source track

Action-specific parameters

Limits

Pricing

Response

Examples

Related