Suno · Music

Add Vocals

📌 What is this：Add sung vocals to a chosen instrumental section.

💡 When to use：Use when you have an instrumental and want singing added.

Endpoints

Usage	Method	Path
Submit task	POST	/api/cqt/generator/suno
Query Result	GET	/api/cqt/info/suno?id={taskId}

Request Parameters

Param	Type	Required	Description
task	string	Required	Fixed value: add_vocals
model	string	Required	Model version
clipId	string	Required	Source clip ID
rangeStartS	number	Required	Start second of the section
rangeEndS	number	Required	End second of the section

Request Example

curl -X POST https://api.cqtai.com/api/cqt/generator/suno \
  -H 'Authorization: Bearer <API_KEY>' \
  -H 'Content-Type: application/json' \
  -d '{ "task":"add_vocals", "model":"v55", "clipId":"5751729f-66f7-493c-bf22-4c4cda6cb0bd", "rangeStartS":0, "rangeEndS":30 }'
# -> { "code":200, "data":"<taskId>" }

Response Example

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "f7c0c894eb1442b39892bb12cb032eb5",
    "taskType": "add_vocals",
    "status": "succeeded",
    "errorMsg": "",
    "param": {
      "task": "add_vocals",
      "model": "chirp-v55",
      "clipId": "5751729f-66f7-493c-bf22-4c4cda6cb0bd",
      "rangeStartS": 0,
      "rangeEndS": 30
    },
    "result": [
      {
        "id": "e625cfb7-5b01-4333-b2f3-65ff8ecac8da",
        "title": "",
        "handle": "roselinhobbui3xs",
        "status": "complete",
        "user_id": "643d21e5-da6b-421c-ad4c-fa10b8bfdc90",
        "metadata": {
          "tags": "",
          "task": "overpainting",
          "type": "gen",
          "prompt": "",
          "avg_bpm": 115.23,
          "max_bpm": 136.36,
          "min_bpm": 66.67,
          "duration": 240,
          "is_remix": true,
          "make_instrumental": false,
          "uses_latest_model": true,
          "overpainting_clip_id": "5751729f-66f7-493c-bf22-4c4cda6cb0bd"
        },
        "audio_url": "https://cdn1.suno.ai/e625cfb7-5b01-4333-b2f3-65ff8ecac8da.mp3",
        "image_url": "https://cdn2.suno.ai/image_e625cfb7-5b01-4333-b2f3-65ff8ecac8da.jpeg",
        "image_large_url": "https://cdn2.suno.ai/image_large_e625cfb7-5b01-4333-b2f3-65ff8ecac8da.jpeg",
        "video_url": "",
        "clip_roots": {
          "clips": [
            {
              "id": "5751729f-66f7-493c-bf22-4c4cda6cb0bd",
              "title": "Emanuel filho amado",
              "image_url": "https://cdn2.suno.ai/image_5751729f-66f7-493c-bf22-4c4cda6cb0bd.jpeg",
              "user_handle": "roselinhobbui3xs",
              "user_display_name": "roselinhobbui3xs"
            }
          ],
          "clip_attribution_type": "remix"
        },
        "media_urls": [
          { "url": "https://d2lwuy8qc234o3.cloudfront.net/1/clip/e625cfb7-5b01-4333-b2f3-65ff8ecac8da.m4a", "delivery": "progressive", "content_type": "m4a-opus" },
          { "url": "https://cdn1.suno.ai/e625cfb7-5b01-4333-b2f3-65ff8ecac8da.mp3", "delivery": "progressive", "content_type": "mp3" }
        ],
        "model_name": "chirp-fenix",
        "batch_index": 0,
        "created_at": "2026-07-09T01:34:15.890Z",
        "major_model_version": "v5.5"
      },
      {
        "id": "854277e7-b41b-4ff0-8cf8-b9887c5b05f8",
        "title": "",
        "status": "complete",
        "metadata": {
          "task": "overpainting",
          "type": "gen",
          "avg_bpm": 132.13,
          "duration": 186.84,
          "is_remix": true,
          "overpainting_clip_id": "5751729f-66f7-493c-bf22-4c4cda6cb0bd"
        },
        "audio_url": "https://cdn1.suno.ai/854277e7-b41b-4ff0-8cf8-b9887c5b05f8.mp3",
        "image_url": "https://cdn2.suno.ai/image_854277e7-b41b-4ff0-8cf8-b9887c5b05f8.jpeg",
        "batch_index": 1,
        "major_model_version": "v5.5"
      }
    ],
    "createTime": "2026-07-09 09:34:10",
    "completeTime": "2026-07-09 09:37:20"
  }
}

Response Fields

Field	Type	Description
code	number	Status code; 200 = success
msg	string	Message
data.id	string	Task ID (the taskId returned on submit; used to poll)
data.taskType	string	Task type; matches the submitted task
data.status	string	Status: pending / succeeded / failed
data.errorMsg	string	Failure reason; empty on success
data.param	object	Echo of the request params you submitted
data.result	array	Results; returns 2 candidate clips
data.result[].id	string	The generated clipId; reusable for further extend / cover, etc.
data.result[].audio_url	string	Audio file URL (mp3)
data.result[].video_url	string	Video file URL (mp4); may be empty, re-query later
data.result[].image_url	string	Cover image URL (image_large_url is the large one)
data.result[].title	string	Song title
data.result[].status	string	Clip status; "complete" = ready to download
data.result[].metadata.duration	number	Total audio duration (seconds)
data.result[].metadata.tags	string	Style tags
data.result[].metadata.task	string	For add_vocals, the clip metadata.task shows "overpainting"
data.result[].metadata.overpainting_clip_id	string	Source clip ID the vocals were added to (= the clipId you passed)
data.result[].metadata.avg_bpm	number	Average tempo in BPM (also max_bpm/min_bpm)
data.result[].metadata.is_remix	bool	Whether it is a remix; always true for add_vocals
data.result[].clip_roots	object	Source (parent) clip info: title / cover / author
data.result[].media_urls	array	Multi-format audio URLs (m4a-opus / mp3)
data.result[].batch_index	number	Candidate index (0, 1)
data.result[].major_model_version	string	Model version used, e.g. v4.5 / v5.5
data.createTime / completeTime	string	Task submit time / completion time
其它字段	—	action_config / model_badges / secondary_badges / ownership / avatar_image_url, etc. are for Suno UI and can be ignored

Billing & Credits

30 credits (x your user rate). Auto-refunded on failure.