docs.sunoapi.org
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
language
language
  • 🇺🇸 English
  • 🇨🇳 Chinese
Support
Suno API
Common APIFile Upload API
Suno API
Common APIFile Upload API
  1. Generate Music
  • Suno API Documentation
  • Suno API Quick Start
  • Generate Music
    • Music Generation Callbacks
    • Music Extension Callbacks
    • Upload and Cover Audio Callbacks
    • Upload and Extend Audio Callbacks
    • Add Instrumental Callbacks
    • Add Vocals Callbacks
    • Music Cover Generation Callbacks
    • Replace Music Section Callbacks
    • Generate Music
      POST
    • Extend Music
      POST
    • Upload And Cover Audio
      POST
    • Upload And Extend Audio
      POST
    • Add Instrumental
      POST
    • Add Vocals
      POST
    • Get Music Generation Details
      GET
    • Recovery Audio
      POST
    • Get Recovery Audio Details
      GET
    • Get Timestamped Lyrics
      POST
    • Boost Music Style
      POST
    • Generate Music Cover
      POST
    • Replace Music Section
      POST
    • Get Music Cover Details
      GET
    • Generate Persona
      POST
    • Generate Mashup
      POST
  • Suno Voice
    • Suno Voice Validation Phrase Callbacks
    • Suno Voice Generation Callbacks
    • Suno Voice Regenerate Phrase Callbacks
    • Suno Voice Generate Verification Phrase
      POST
    • Suno Voice Get Verification Phrase
      GET
    • Suno Voice Create Custom Voice
      POST
    • Suno Voice Get Custom Voice Record
      GET
    • Suno Voice Regenerate Verification Phrase
      POST
    • Suno Voice Check Availability
      POST
  • Generate Lyrics
    • Lyrics Generation Callbacks
    • Generate Lyrics
    • Get Lyrics Generation Details
  • Generate Sounds
    • Generate Sounds
  • WAV Conversion
    • WAV Format Conversion Callbacks
    • Convert to WAV Format
    • Get WAV Conversion Details
  • Vocal Removal
    • Audio Separation Callbacks
    • MIDI Generation Callbacks
    • Vocal & Instrument Stem Separation
    • Get Audio Separation Details
    • Generate MIDI from Audio
    • Get MIDI Generation Details
  • Music Video Generation
    • Music Video Generation Callbacks
    • Create Music Video
    • Get Music Video Details
  • Generate Speech
    • Generate Speech
  1. Generate Music

Add Vocals

POST
/api/v1/generate/add-vocals
This endpoint layers AI-generated vocals on top of an existing instrumental. Given a prompt (e.g., lyrical concept or musical mood) and optional audio, it produces vocal output harmonized with the provided track.

Model Versions#

Current models: V6 (default), V6_WILD, V6_MINI
Deprecated models: V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, V4
Deprecated values remain available only for backward compatibility. New integrations should use a V6-series model.

Key Capabilities#

Accepts an existing instrumental via uploadUrl, with optional prompt-based stylistic input.
Supports control parameters including:
lyrics, prompt, style, tags, negativeTags (define lyrical content and vocal style)
vocalGender, styleWeight, weirdnessConstraint, audioWeight, variety, callBackUrl.
Returns a taskId, supports the same 14-day retention and three-stage callback model as the instrumental endpoint  .

Typical Use Cases#

Music platforms or tools enabling topline creation and rapid prototyping of lyrical ideas.
Collaborative songwriting or co-creation workflows, where lyrics or vocal styles are iteratively tested over instrumental drafts.

Parameter Details#

A source audio (uploadUrl) is enough to start generation together with the required fields below. Remaining fields are optional.
Required fields: uploadUrl, callBackUrl, title, negativeTags, style
Upload URL: Must be a valid, publicly accessible audio file URL
Style: Describes the overall genre and vocal approach (Jazz, Classical, Electronic, Pop)
Negative Tags: Music styles or vocal traits to exclude from generation
Title: Used as the title for the generated vocal track

Optional parameters#

The following fields are optional controls available for this endpoint:
lyrics (string): Lyrics content. Optional. V6 series maximum 5000 characters. Takes priority over prompt as lyrics.
prompt (string): Lyrics content. Optional. Used as lyrics when lyrics is not provided. V6 series maximum 5000 characters.
vocalGender (string): Preferred vocal gender. Allowed values: m (male), f (female)
styleWeight (number): Style adherence weight in range 0–1 (recommended two decimals)
weirdnessConstraint (number): Creativity/novelty constraint in range 0–1 (recommended two decimals)
audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
variety (number): Diversity of generated results. Integer from 0–4, default 1. 0 off, 1 normal (default), 2 high, 3 extra, 4 max.
model (string): Model version used for generation. Current values: V6 (default), V6_WILD, V6_MINI. Deprecated: V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, V4.

Developer Notes#

Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)
In some cases, text and first stages may be skipped, directly returning complete
See Add Vocals Callbacks for detailed callback format
Monitor task progress using Get Music Generation Details

Callbacks

vocalsAdded

Request

Authorization
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Request successful
Bodyapplication/json

🔴500Server Error
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://apibox.erweima.ai/api/v1/generate/add-vocals' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "prompt": "A calm and relaxing piano track with soothing vocals",
    "lyrics": "[Verse] Night city lights shining bright",
    "title": "Relaxing Piano with Vocals",
    "negativeTags": "Heavy Metal, Aggressive Vocals",
    "style": "Jazz",
    "vocalGender": "m",
    "styleWeight": 0.61,
    "weirdnessConstraint": 0.72,
    "audioWeight": 0.65,
    "variety": 1,
    "uploadUrl": "https://example.com/instrumental.mp3",
    "callBackUrl": "https://api.example.com/callback",
    "model": "V6"
}'
Response Response Example
{
    "code": 200,
    "msg": "success",
    "data": {
        "taskId": "5c79****be8e"
    }
}
Previous
Add Instrumental
Next
Get Music Generation Details
Built with