Skip to main content
POST
/
api
/
v1
/
generate
/
add-vocals
Add Vocals to Music
curl --request POST \
  --url https://api.kie.ai/api/v1/generate/add-vocals \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "A calm and relaxing piano track.",
  "title": "Relaxing Piano",
  "negativeTags": "heavy metal, strong drum beats",
  "style": "Jazz",
  "uploadUrl": "https://example.com/music.mp3",
  "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 an existing instrumental via uploadUrl, with optional prompt-based stylistic input.
  • Supports control parameters including:
    • prompt, style, tags, model, negativeTags (define lyrical content and vocal style)
    • vocalGender, styleWeight, weirdnessConstraint, audioWeight, callBackUrl  .
  • Returns a taskId, supports the same 14-day retention and three-stage callback model as the instrumental endpoint  .

​
Typical Use Cases

  • Music platforms or tools enabling topline creation and rapid prototyping of lyrical ideas.
  • Collaborative songwriting or co-creation workflows, where lyrics or vocal styles are iteratively tested over instrumental drafts.

​
Parameter Details

  • uploadUrl specifies the audio file URL to be processed
  • prompt defines lyric content and singing style
  • model specifies the AI model version for generation
  • style and negativeTags are used to control music and vocal style
  • negativeTags are used to exclude unwanted elements
  • 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
​
prompt
string
required

Prompt for generating audio. Usually text describing audio content, used to guide vocal singing content and style.

Example:

"A calm and relaxing piano track."

​
title
string
required

Music title. Will be displayed in the player interface and file name.

Example:

"Relaxing Piano"

​
negativeTags
string
required

Excluded music styles. Used to avoid including specific styles or elements in the generated music.

Example:

"heavy metal, strong drum beats"

​
style
string
required

Music style. Such as jazz, electronic, classical and other music types.

Example:

"Jazz"

​
uploadUrl
string<uri>
required

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

Example:

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

​
callBackUrl
string<uri>
required

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

  • The system will send a POST request to this URL when vocal 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