Skip to main content
POST
/
api
/
v1
/
generate
/
add-instrumental
Add Instrumental to Music
curl --request POST \
  --url https://api.kie.ai/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, fast drums",
  "tags": "relaxing, piano, soothing",
  "callBackUrl": "https://example.com/callback",
  "model": "V4_5PLUS",
  "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 Details

  • uploadUrl specifies the audio file URL to be processed
  • title specifies the title for the generated music
  • model specifies the AI model version for generation
  • tags and negativeTags are used to control music style
  • Supports various optional parameters for fine-tuning generation effects

​
Developer Notes

  • Generated files will be retained for 14 days
  • Callback process has three stages: text (text generation), first (first track completed), complete (all completed)

Authorizations

​
Authorization
string
header
required

All APIs require authentication via Bearer Token.

Get API Key:

  1. Visit API Key Management Page to get your API Key

Usage: Add to request header: 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 in the management page

Body

application/json
​
uploadUrl
string<uri>
required

URL of the uploaded audio file. Specifies the source audio file location for adding accompaniment.

Example:

"https://example.com/music.mp3"

​
title
string
required

Title of the generated music. Will be displayed in the player interface and file name.

Example:

"Relaxing Piano"

​
negativeTags
string
required

Music styles or characteristics to exclude from the generated audio. Used to avoid specific unwanted music elements.

Example:

"heavy metal, fast drums"

​
tags
string
required

Music styles or tags to include in the generated music. Defines the desired music style and characteristics.

Example:

"relaxing, piano, soothing"

​
callBackUrl
string<uri>
required

URL address for receiving instrumental generation task completion updates. This parameter is required for all instrumental generation requests.

  • The system will send a POST request to this URL when instrumental generation is completed, including task status and results
  • Callback process has three stages: text (text generation), first (first track completed), complete (all completed)
  • Your callback endpoint should be able to accept POST requests containing JSON payloads with music generation results
  • Alternatively, you can use the get music details interface to poll task status
Example:

"https://example.com/callback"

​
model
enum<string>
default:V4_5PLUS

The AI model version to use for generation.

  • Available options:
    • V5: Superior musical expression, faster generation.
    • V4_5PLUS: V4.5+ is richer sound, new ways to create.
Available options:
V4_5PLUS,
V5
Example:

"V4_5PLUS"

​
vocalGender
enum<string>

Vocal gender preference. Optional. 'm' for male, 'f' for female. Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions.

Available options:
m,
f
Example:

"m"

​
styleWeight
number

Adherence strength to specified style. Optional. Range 0–1, up to 2 decimal places.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.61

​
weirdnessConstraint
number

Controls experimental/creative deviation level. Optional. Range 0–1, up to 2 decimal places.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.72

​
audioWeight
number

Relative weight of audio elements. Optional. Range 0–1, up to 2 decimal places.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

Response

Request successful

​
code
enum<integer>

Response status code

  • 200: Success - Request processed successfully
  • 401: Unauthorized - Authentication credentials missing or invalid
  • 402: Insufficient credits - Account does not have enough credits to perform this operation
  • 404: Not found - Requested resource or endpoint does not exist
  • 409: Conflict - WAV record already exists
  • 422: Validation error - Request parameters failed validation checks
  • 429: Rate limit exceeded - Request limit for this resource has been exceeded
  • 451: Unauthorized - Failed to retrieve image. Please verify any access restrictions set by you or your service provider.
  • 455: Service unavailable - System currently undergoing maintenance
  • 500: Server error - Unexpected error occurred while processing request
Available options:
200,
401,
402,
404,
409,
422,
429,
451,
455,
500
​
msg
string

Error message when code != 200

Example:

"success"

​
data
object