Add vocals

First use Upload reference audio to obtain a track ID, then supply it as music_id. A track ID returned by Generate music is not supported for this operation.

When custom=true, prompt contains the lyrics or vocal prompt. After a successful submission, save data.jobId, then use Retrieve a task to wait for the result. status: SUCCESS in the submission response does not mean audio generation is complete.

POST/suno/mj/submit/add-vocals

Authorization

bearerAuth

AuthorizationBearer <token>

Authenticate with Authorization: Bearer your-api-key.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

music_id*string

Track ID obtained by uploading reference audio. Track IDs returned by Generate music are not supported for this operation.

custom*boolean

Whether to use custom mode. The request is rejected if this field is omitted.

mv?string

Music model version. Defaults to chirp-v5 when omitted.

Default"chirp-v5"

Value in

"chirp-v5-5"
"chirp-v5"
"chirp-v4-5+"
"chirp-v4-5"
"chirp-v4-5-all"
"chirp-v4"
"chirp-v3-5"
"chirp-v3-0"

gpt_description_prompt?string

Required when custom=false; maximum length is 500 characters.

Lengthlength <= 500

prompt?string

Required when custom=true; used as lyrics or a vocal prompt.

title?string

Title, with a maximum length of 80 characters.

Lengthlength <= 80

tags?string

Music style.

negative_tags?string

Negative tags.

style_weight?number

Each value ranges from 0 to 1.

Range0 <= value <= 1

weirdness_constraint?number

Each value ranges from 0 to 1.

Range0 <= value <= 1

audio_weight?number

Each value ranges from 0 to 1.

Range0 <= value <= 1

vocal_gender?string

Supports only Male or Female.

Value in

"Male"
"Female"

isStorage?boolean

Whether to save a copy.

hookUrl?string

Optional user callback URL. Only ports 80, 443, 8080, and 8443 are supported. When provided, the platform forwards notifications to it.

Response Body

`application/json`

curl --request POST 'https://api.agtcloud.cn/suno/mj/submit/add-vocals' \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
  "music_id": "MUSIC_ID",
  "custom": true,
  "mv": "chirp-v5",
  "prompt": "Add warm female-vocal verses and a chorus to this melody",
  "title": "Voice Layer",
  "tags": "mandopop, female vocal",
  "vocal_gender": "Female"
}'

{
  "status": "SUCCESS",
  "message": "success",
  "data": {
    "jobId": "JOB_ID"
  }
}

Authorization

Request Body

Response Body

200application/json

400application/json

`application/json`

`application/json`