---
title: "Add Instrumental"
method: POST
path: "/api/v1/generate/add-instrumental"
tags: ["Music Generation"]
---

# Add Instrumental

`POST /api/v1/generate/add-instrumental`

## Request body

- object
  - `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.).
  - `title` string, required — The title of the music track. - Required. - This will be used as the title for the generated instrumental track.
  - `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](https://docs.sunoapi.org/suno-api/add-instrumental-callbacks) - Alternatively, you can use the Get Music Generation Details interface to poll task status
  - `vocalGender` 'm' | 'f' — Preferred vocal gender for any vocal elements. Optional. Allowed values: 'm' (male), 'f' (female).
  - `styleWeight` number — Style adherence weight. Optional. Range: 0-1. Two decimal places recommended.
  - `weirdnessConstraint` number — Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended.
  - `audioWeight` number — Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended.
  - `model` 'V4_5PLUS' | 'V5' | 'V5_5' — Model version to use for generation. Optional. Default: V4_5PLUS.

## Response `200`

Request successful

- object
  - `code` 200 | 400 | 401 | 404 | 405 | 413 | 429 | 430 | 455 | 500 — # 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
  - `msg` string — Error message when code != 200
  - `data` object
    - `taskId` string — Task ID for tracking task status

## Other responses

- `500` — Server error

---

[API](https://skmtc.dev/sunoapi/apis/file-upload-api.md) · [All operations](https://skmtc.dev/sunoapi/apis/file-upload-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sunoapi/file-upload-api/revisions/22d45ee33a4a/schema)