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"
  }
}

​
Key Capabilities

  • Accepts an existing instrumental via uploadUrl, with optional prompt-based stylistic input.
  • Supports control parameters including:
    • prompt, style, tags, negativeTags (define lyrical content and vocal style)
    • vocalGender, styleWeight, weirdnessConstraint, audioWeight, 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 Usage Guide

Required parameters for all requests:
  • uploadUrl: Valid instrumental audio file URL
  • prompt: Description of the desired vocal content and style
  • title: Title for the generated vocal track (80 characters max)
  • style: Music and vocal style (e.g., “Jazz”, “Pop”, “Classical”)
  • negativeTags: Vocal styles or characteristics to exclude
  • callBackUrl: URL to receive completion notifications
Optional parameters for enhanced control:
  • vocalGender: Preferred vocal gender (‘m’ for male, ‘f’ for female)
  • styleWeight: Style adherence weight (0.00-1.00)
  • weirdnessConstraint: Creativity/novelty constraint (0.00-1.00)
  • audioWeight: Audio consistency weight (0.00-1.00)
Audio requirements:
  • Input Type: Instrumental or backing track audio files
  • File Format: MP3, WAV, or other supported audio formats
  • Quality: Clear instrumental tracks work best for vocal addition
  • Accessibility: Ensure uploaded audio URLs are publicly accessible

​
Developer Notes

  1. Generated vocal tracks are retained for 15 days before being deleted
  2. Ensure you have proper rights to use the uploaded audio content
  3. Use clear, well-mixed instrumental tracks for best results
  4. Be specific about vocal style in your prompt (e.g., “smooth jazz vocals”, “energetic pop vocals”)
  5. Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)
  6. You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks

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

Response

200
application/json

Request successful

The response is of type object.