Music GenerationtaskType: add_vocals30 Credits / Task

Add Vocals to Music

Generate AI-synthesized vocal singing on top of an existing backing instrumental track. Customize lyrical storytelling, singing style, vocal gender, and tone characteristics while keeping the underlying musical arrangement intact.

POST/api/v1/createTask

Test in Playground

Usage Guide & Overview

Four Mandatory Parameters: You must provide upload_url, title, style, and negative_tags.
Source Audio Input: upload_url must point directly to a publicly accessible instrumental audio file (MP3/WAV).
Custom Lyrics Priority: If lyrics is supplied, it takes priority over prompt for vocal synthesis.
Vocal Customization: Fine-tune performance with vocal_gender ("m" | "f"), style_weight, and audio_weight.
Asset Storage: Generated audio files are retained on CDN for 14 days. Ensure you archive finished outputs promptly.

Supported AI Models

Multiple Generations

V6DEFAULT

Natural vocal harmonics, higher intelligibility, and nuanced phrasing.

V6_MINI

Optimized for speed and high throughput synthesis workflows.

V6_WILD

Unconventional styles, avant-garde delivery, and bold vocal timbres.

Validation Rules & Constraints

Required Input Parameters

upload_url: Must be a reachable URL returning a valid audio stream or file.
title: Required, up to 100 characters.
style: Required musical/vocal style description (up to 1,000 characters).
negative_tags: Required exclusion tags to eliminate unwanted traits.

Lyrics Limits & Formatting

Maximum 5,000 characters for lyrics on V6, V6_MINI, and V6_WILD.
Standard song structure tags like [Verse], [Chorus], [Bridge], and [Outro] are recommended for optimal phrasing.
If lyrics is omitted, prompt is used as lyrics fallback.

Acoustic Balance & Fine-Tuning

audio_weight: Controls how closely the model preserves the original instrumental groove (0.0 ~ 1.0).
style_weight: Regulates how strongly the vocal performance reflects the style tag (0.0 ~ 1.0).
variety: Integer range 0 to 4 (0: strict exact style, 1: balanced default, 4: max variation).

Authentication & Headers

Header	Requirement	Description
Authorization	required	Bearer YOUR_API_KEY Secret Key generated from dashboard
Content-Type	required	application/json Request payload format

Header

Requirement

Description

Authorization

required

Bearer YOUR_API_KEY

Secret Key generated from dashboard

Content-Type

required

application/json

Request payload format

Request Body Schema

14 fields

upload_urlstringrequired

Publicly accessible direct URL of the source instrumental audio file (MP3, WAV) onto which vocals will be synthesized.

titlestringrequired

Title for the generated vocal track (max 100 characters). Displayed in player interfaces and filenames.

stylestringrequired

Musical genre, style tags, and vocal delivery mood (e.g. "Jazz, Soulful, Smooth Ballad"). Max 1,000 characters.

negative_tagsstringrequired

Genres, instruments, or acoustic qualities to exclude (e.g. "heavy metal, strong drum beats, distorted screaming").

taskTypestringoptional

default:add_vocals

Task routing identifier. Explicitly set to "add_vocals" (or "add-vocals").

modelstringoptional

default:V6

AI generation model. Supported: "V6" (Default, refined & expressive vocals), "V6_MINI" (Fast & lightweight), "V6_WILD" (Experimental ideas), "V4_5PLUS".

lyricsstringoptional

Custom lyrics for the synthesized singing voice (verses, chorus, bridge). Takes precedence over "prompt". Max 5,000 characters on V6.

promptstringoptional

Description of the desired vocal singing style or lyrics when "lyrics" is omitted. Max 5,000 characters.

callBackUrlstringoptional

Public Webhook URL to receive asynchronous completion notifications when vocal generation completes.

vocal_genderstringoptional

Vocal gender preference: "m" (male) or "f" (female). Probabilistically guides vocal timbre.

Allowed options:

"m""f"

style_weightnumberoptional

default:0.65

Adherence strength to specified style tags (range 0.0 to 1.0, up to 2 decimal places).

weirdness_constraintnumberoptional

default:0.65

Creative/experimental deviation control (range 0.0 to 1.0, up to 2 decimal places).

audio_weightnumberoptional

default:0.65

Relative weight of source audio backing track vs newly synthesized vocals (range 0.0 to 1.0).

varietynumberoptional

default:1

Diversity and stylistic variation: 0 (exact match), 1 (normal / balanced, default), 2 (high), 3 (extra), 4 (max variation).

Request Sample

curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "add_vocals",
    "upload_url": "https://example.com/audio/backing_track.mp3",
    "title": "Midnight Reflections",
    "style": "R&B, Soulful, Smooth Piano",
    "negative_tags": "heavy metal, autotune, distortion, aggressive rap",
    "model": "V6",
    "vocal_gender": "f",
    "lyrics": "[Verse 1]\nUnder the starlit sky so deep,\nmemories I promised to keep.\n[Chorus]\nSinging through the quiet night,\nwaiting for the morning light.",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'

Response Body(200 status)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79be8e9f72"
  }
}

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

Text/Lyrics parsing completed (callbackType: "text")
First vocal mix variation completed (callbackType: "first")
All completed audio tracks with vocals generated (callbackType: "complete")
Vocal synthesis task failed or timed out (code: 400, 408, 500, 501)

Webhook Payload Format

Response Body(200 status)

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "4e81fe32b910",
    "data": [
      {
        "id": "a123bcde-5678-4901-abcd-ef0123456789",
        "audio_url": "https://cdn.example.com/audio/vocal_mix_1.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/vocal_stream_1.m3u8",
        "image_url": "https://cdn.example.com/cover/vocal_cover_1.jpeg",
        "prompt": "[Verse 1] Under the starlit sky so deep...",
        "model_name": "chirp-v4-5",
        "title": "Midnight Reflections",
        "createTime": 1786343609818,
        "duration": 185.2,
        "tags": "r&b, soulful, smooth piano",
        "source_audio_url": "https://example.com/audio/backing_track.mp3",
        "source_image_url": "https://cdn.example.com/cover/backing_cover.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/backing_stream"
      },
      {
        "id": "b234cdef-6789-5012-bcde-f0123456789a",
        "audio_url": "https://cdn.example.com/audio/vocal_mix_2.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/vocal_stream_2.m3u8",
        "image_url": "https://cdn.example.com/cover/vocal_cover_2.jpeg",
        "prompt": "[Verse 1] Under the starlit sky so deep...",
        "model_name": "chirp-v4-5",
        "title": "Midnight Reflections",
        "createTime": 1786343609818,
        "duration": 185.2,
        "tags": "r&b, soulful, smooth piano",
        "source_audio_url": "https://example.com/audio/backing_track.mp3",
        "source_image_url": "https://cdn.example.com/cover/backing_cover.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/backing_stream"
      }
    ]
  }
}

Callback Payload Fields

Field	Type	Description
`code`	integer	Callback status code (200: Success, 400: Invalid params, 408: Timeout, 500: Server error, 501: Task failed)
`msg`	string	Execution status message or error cause details
`data.task_id`	string	Task ID matching the taskId returned from the initial createTask submission
`data.callbackType`	string	Event stage: "text" (lyrics parsed), "first" (first mix variation ready), or "complete" (all variations generated)
`data.data[]`	array	Array of completed audio tracks with synthesized vocal singing layered over the backing track
`data.data[].source_audio_url`	string	Original backing instrumental audio URL uploaded by the user

Receiver Implementation Example

Webhook Receiver

// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if (code === 200 && data) {
    const { callbackType, task_id, data: tracks } = data;
    console.log(`Received ${callbackType} callback for add-vocals task ${task_id}`);

    if (callbackType === 'complete' && Array.isArray(tracks)) {
      tracks.forEach((track) => {
        console.log(`Vocal Audio URL: ${track.audio_url}`);
        console.log(`Duration: ${track.duration}s, Backing Track: ${track.source_audio_url}`);
        // Save synthesized vocal track to database...
      });
    }
  } else {
    console.error(`Vocal synthesis failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Previous EndpointExtend Music Next EndpointAdd Instrumental to Music

Ready to integrate Add Vocals to Music?

Create your free account, obtain your Secret Key, and get 100 free generation credits.

Generate Secret Key