Skip to main content
POST
/
api
/
v1
/
generate
/
add-instrumental
Add Instrumental
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/add-instrumental \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrl": "https://example.com/music.mp3",
  "title": "Relaxing Piano",
  "negativeTags": "Heavy Metal, Aggressive Drums",
  "tags": "Relaxing Piano, Ambient, Peaceful",
  "callBackUrl": "https://api.example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}
This endpoint generates a musical accompaniment tailored to an uploaded audio file — typically a vocal stem or melody track. It helps users instantly flesh out their vocal ideas with high-quality backing music, all without needing a producer.

​
Perfect For

  • Vocal Recordings: Add professional backing tracks to vocal performances
  • Melody Ideas: Turn simple melodies into full arrangements
  • Demos: Transform basic recordings into polished demos
  • Songwriting: Develop musical ideas with AI-generated accompaniment

​
Required Parameters

All of these fields are mandatory for generating instrumental tracks:
  • Upload URL: Your source audio file (MP3, WAV, etc.)
  • Title: Name for the generated instrumental track
  • Tags: Desired style, mood, and instruments (e.g., “Jazz Piano, Smooth, Romantic”)
  • Negative Tags: Styles to avoid (e.g., “Heavy Metal, Aggressive Drums”)
  • Callback URL: Where to receive completion notifications

​
Generation Process

  1. Upload: Provide your source audio (vocal or melody)
  2. Style Definition: Specify desired instrumental characteristics
  3. AI Analysis: System analyzes your audio’s key, tempo, and structure
  4. Accompaniment Creation: Generates complementary instrumental parts
  5. Delivery: Receive your complete track via callback

​
Callback Stages

The generation process includes multiple callback stages:
  • Text: Initial processing and analysis complete
  • First: First version of instrumental ready
  • Complete: Final polished version delivered
Note: Some stages may be skipped, jumping directly to ‘complete’

​
Fine-Tuning Controls

Adjust these optional parameters for perfect results:
  • Style Weight (0-1): How closely to follow your style tags
  • Weirdness Constraint (0-1): Control creativity vs. conventional arrangements
  • Audio Weight (0-1): Balance between input audio influence and style tags
  • Vocal Gender: Specify if any vocal elements are needed

​
Best Practices

  • Clear Audio: Upload high-quality source files for best results
  • Specific Tags: Use descriptive style tags (e.g., “Acoustic Guitar, Folk, Intimate”)
  • Balanced Settings: Start with default weights and adjust as needed
  • Format Support: Use standard audio formats (MP3, WAV)
Transform your raw musical ideas into professional-quality tracks with AI-powered instrumental generation!

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
​
uploadUrl
string<uri>
required

The URL of the uploaded music file to add instrumental 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/music.mp3"

​
title
string
required

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

Example:

"Relaxing Piano"

​
negativeTags
string
required

Music styles or traits to exclude from the generated instrumental. Required. Use to avoid specific styles or instruments in the instrumental version.

Example:

"Heavy Metal, Aggressive Drums"

​
tags
string
required

Music style and characteristics for the instrumental. Required. Describe the desired style, mood, and instruments for the instrumental track.

Example:

"Relaxing Piano, Ambient, Peaceful"

​
callBackUrl
string<uri>
required

The URL to receive task completion notifications when instrumental 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 Instrumental 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 for any vocal elements. 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