Skip to main content
POST
/
api
/
v1
/
generate
/
add-vocals
Add Vocals
curl --request POST \
  --url https://api.sunoapi.org/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",
  "title": "Relaxing Piano with Vocals",
  "negativeTags": "Heavy Metal, Aggressive Vocals",
  "style": "Jazz",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "uploadUrl": "https://example.com/instrumental.mp3",
  "callBackUrl": "https://api.example.com/callback"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
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.

​
Perfect For

  • Instrumental Tracks: Add professional vocals to existing instrumentals
  • Complete Songs: Transform instrumental demos into full songs
  • Vocal Harmonies: Layer additional vocal parts over existing vocals
  • Style Exploration: Experiment with different vocal styles on your tracks

​
Required Parameters

All of these fields are mandatory for generating vocal tracks:
  • Upload URL: Your instrumental audio file (MP3, WAV, etc.)
  • Prompt: Detailed description of desired vocal content and style
  • Title: Name for the generated vocal track
  • Style: Overall genre and vocal approach (e.g., “Jazz”, “Pop”, “Classical”)
  • Negative Tags: Vocal styles to avoid (e.g., “Heavy Metal, Aggressive Vocals”)
  • Callback URL: Where to receive completion notifications

​
Vocal Generation Process

  1. Upload Instrumental: Provide your backing track
  2. Define Vocal Style: Specify prompt, genre, and vocal characteristics
  3. AI Analysis: System analyzes musical key, tempo, and chord progressions
  4. Vocal Creation: Generates lyrics and vocal performance that fits harmonically
  5. Final Mix: Delivers professionally mixed vocal + instrumental combination

​
Vocal Control Options

Fine-tune your vocal generation with these optional parameters:

​
Gender Selection

  • Male (m): Generates male vocal characteristics
  • Female (f): Generates female vocal characteristics
  • Auto: Let AI choose the most appropriate gender for your style

​
Creative Controls

  • Style Weight (0-1): How closely to follow your specified style
  • Weirdness Constraint (0-1): Balance between conventional and experimental vocals
  • Audio Weight (0-1): Influence of the instrumental track on vocal creation

​
Callback Stages

The vocal generation process includes multiple callback notifications:
  • Text: Lyric generation and vocal planning complete
  • First: Initial vocal recording ready for review
  • Complete: Final polished vocal track with full mix
Note: Some stages may be skipped for faster delivery

​
Best Practices

​
For Best Results

  • High-Quality Instrumentals: Use clear, well-mixed backing tracks
  • Detailed Prompts: Be specific about mood, energy, and vocal style
  • Appropriate Style Tags: Match the vocal style to your instrumental genre
  • Clear Negative Tags: Specify exactly what vocal styles to avoid

​
Common Use Cases

  • Singer-Songwriter: Add vocals to acoustic guitar or piano tracks
  • Electronic Music: Layer vocals over synthesized instrumentals
  • Jazz Standards: Create vocal versions of instrumental jazz pieces
  • Pop Production: Transform beats and melodies into complete songs
Transform your instrumental tracks into complete vocal performances with AI-powered singing that matches your musical vision!

Authorizations

​
Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

Authorization: Bearer YOUR_API_KEY

⚠️ Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately from the management page

Body

application/json
​
prompt
string
required

Description of the audio content to generate vocals for. Required. Provides context about the desired vocal style and content. The more detailed your prompt, the better the vocal generation will match your vision.

Example:

"A calm and relaxing piano track with soothing vocals"

​
title
string
required

The title of the music track. Required. This will be used as the title for the generated vocal track.

Example:

"Relaxing Piano with Vocals"

​
negativeTags
string
required

Music styles or vocal traits to exclude from the generated track. Required. Use to avoid specific vocal styles or characteristics.

Example:

"Heavy Metal, Aggressive Vocals"

​
style
string
required

The music and vocal style. Required. Examples: Jazz, Classical, Electronic, Pop. Describes the overall genre and vocal approach.

Example:

"Jazz"

​
uploadUrl
string<uri>
required

The URL of the uploaded audio file to add vocals to. Required. Must be a valid audio file URL accessible by the system. The uploaded audio should be in a supported format (MP3, WAV, etc.).

Example:

"https://example.com/instrumental.mp3"

​
callBackUrl
string<uri>
required

The URL to receive task completion notifications when vocal generation is complete. The callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete). Note: In some cases, text and first stages may be skipped, directly returning complete. For detailed callback format and implementation guide, see Add Vocals Callbacks. Alternatively, you can use the Get Music Generation Details interface to poll task status.

Example:

"https://api.example.com/callback"

​
vocalGender
enum<string>

Preferred vocal gender. Optional. Allowed values: 'm' (male), 'f' (female).

Available options:
m,
f
Example:

"m"

​
styleWeight
number

Style adherence weight. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.61

​
weirdnessConstraint
number

Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.72

​
audioWeight
number

Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

Response

Request successful

​
code
enum<integer>

Status code. 200 - Request successful, 400 - Invalid parameters, 401 - Unauthorized access, 404 - Invalid request method or path, 405 - Rate limit exceeded, 413 - Theme or prompt too long, 429 - Insufficient credits, 430 - Your call frequency is too high. Please try again later, 455 - System maintenance, 500 - Server error

Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

Error message when code != 200

Example:

"success"

​
data
object