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,
  "model": "V4_5PLUS"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
Key Capabilities

  • Accepts uploadUrl of an existing audio file (usually vocals or stems).
  • Supports fine-grained customization via parameters such as:
    • tags and negativeTags (musical style controls)
    • styleWeight, audioWeight, weirdnessConstraint (stylistic & creative blending)
    • vocalGender, title, callBackUrl for metadata & workflow control  .
  • Returns a taskId for tracking, and results are retained for 14 days. Callback workflow includes three stages: text, first, and complete  .

​
Typical Use Cases

  • Singers or melody writers who want instant fuller arrangements around their vocal inputs.
  • Applications like karaoke platforms, demo-generation tools, or co-creation interfaces that allow users to experiment with accompaniment styles easily.

​
Parameter Usage Guide

Required parameters for all requests:
  • uploadUrl: Valid audio file URL (MP3, WAV, or other supported formats)
  • title: Title for the generated instrumental track (max 100 characters)
  • tags: Desired style and characteristics for the instrumental
  • negativeTags: Styles or instruments to exclude
  • callBackUrl: URL to receive completion notifications
Optional parameters for enhanced control:
  • vocalGender: Preferred vocal gender for any vocal elements (‘m’ or ‘f’)
  • styleWeight: Style adherence weight (0.00-1.00)
  • weirdnessConstraint: Creativity/novelty constraint (0.00-1.00)
  • audioWeight: Audio consistency weight (0.00-1.00)
  • model: Model version used for generation. Allowed values: V4_5PLUS (default), V5
Audio requirements:
  • File Format: MP3, WAV, or other supported audio formats
  • Quality: Higher quality input generally produces better instrumental results
  • Accessibility: Ensure uploaded audio URLs are publicly accessible and stable

​
Developer Notes

  1. Generated instrumental files are retained for 15 days before being deleted
  2. Ensure you have proper rights to use the uploaded audio content
  3. Be specific with tags to get the desired instrumental style (e.g., “acoustic guitar, soft piano, ambient”)
  4. Use negative tags effectively to avoid unwanted elements
  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
​
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"
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"
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

​
model
enum<string>
default:V4_5PLUS

Model version to use for generation. Optional. Default: V4_5PLUS.

Available options:
V4_5PLUS,
V5
Example:

"V4_5PLUS"

Response

Request successful

​
code
enum<integer>

Status Codes

  • ✅ 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