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

​
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 (80 characters max)
  • 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)
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

Response

200
application/json

Request successful

The response is of type object.