Skip to main content
POST
/
api
/
v1
/
generate
/
upload-extend
Upload And Extend Audio
curl --request POST \
  --url https://api.kie.ai/api/v1/generate/upload-extend \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrl": "https://storage.example.com/upload",
  "defaultParamFlag": true,
  "instrumental": true,
  "continueAt": 60,
  "model": "V4",
  "callBackUrl": "https://api.example.com/callback",
  "prompt": "Extend the music with more relaxing notes",
  "style": "Classical",
  "title": "Peaceful Piano Extended",
  "negativeTags": "Relaxing Piano",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "personaId": "persona_123"
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
Parameter Usage Guide

Character limits vary depending on the model version:
  • For model V5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
  • For models V4_5PLUS and V4_5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
  • For model V4_5ALL: style (max 1000 chars), title (max 80 chars), prompt (max 5000 chars)
  • For model V4: style (max 200 chars), title (max 80 chars), prompt (max 3000 chars)
  • When defaultParamFlag is true (Custom Parameters):
    • If instrumental is true: style, title, and uploadUrl are required
    • If instrumental is false: style, prompt, title, and uploadUrl are required
    • Character limits vary by model version (see note above)
    • continueAt: the time point in seconds from which to start extending (must be greater than 0 and less than the uploaded audio duration)
    • uploadUrl: specifies the upload location for audio files; ensure uploaded audio does not exceed 8 minutes.
  • When defaultParamFlag is false (Default Parameters):
    • Regardless of instrumental setting, only uploadUrl and prompt are required
    • Other parameters will use the original audio’s parameters

​
Developer Notes

  1. Generated files will be retained for 14 days
  2. Model version must be consistent with the source music
  3. This feature is ideal for creating longer works by extending existing music
  4. uploadUrl parameter specifies the upload location for audio files; provide a valid URL.

​
Optional parameters

  • vocalGender (string): Vocal gender preference. Use m for male, f for female.
  • styleWeight (number): Strength of adherence to style. Range 0–1, up to 2 decimals. Example: 0.65.
  • weirdnessConstraint (number): Controls creative deviation. Range 0–1, up to 2 decimals. Example: 0.65.
  • audioWeight (number): Balance weight for audio features. Range 0–1, up to 2 decimals. Example: 0.65.
  • personaId (string): Persona ID to apply to the generated music. Only available when Custom Mode is enabled. To create one, use Generate Persona.

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

The URL for uploading audio files, required regardless of whether defaultParamFlag is true or false. Ensure the uploaded audio does not exceed 8 minutes in length. Note: For the V4_5ALL model, the uploaded audio must not exceed 1 minute in length.

Example:

"https://storage.example.com/upload"

​
defaultParamFlag
boolean
required

Enable custom mode for advanced audio generation settings.

  • Set to true to use custom parameter mode (requires style, title, and uploadUrl; if instrumental is false, uploadUrl and prompt are required). If instrumental is false, the prompt will be strictly used as lyrics.
  • Set to false to use non-custom mode (only uploadUrl required). Lyrics will be automatically generated based on the prompt.
Example:

true

​
instrumental
boolean
required

Determines whether the audio is instrumental (without lyrics).

  • In custom parameter mode (defaultParamFlag: true):
    • If true: only style, title, and uploadUrl are required.
    • If false: style, title, prompt (prompt will be used as exact lyrics), and uploadUrl are required.
  • In non-custom parameter mode (defaultParamFlag: false): does not affect required fields (only uploadUrl needed). If false, lyrics will be automatically generated.
Example:

true

​
continueAt
number
required

The time point (in seconds) from which to start extending the music.

  • Required when defaultParamFlag is true.
  • Value range: greater than 0 and less than the total duration of the uploaded audio.
  • Specifies the position in the original track where the extension should begin.
Example:

60

​
model
enum<string>
required

The AI model version to use for generation.

  • Required for all requests.
  • Available options:
    • V5: Superior musical expression, faster generation.
    • V4_5PLUS: V4.5+ delivers richer sound, new ways to create, max 8 min.
    • V4_5: V4.5 enables smarter prompts, faster generations, max 8 min.
    • V4_5ALL: V4.5ALL enables smarter prompts, faster generations, max 8 min.
    • V4: V4 improves vocal quality, max 4 min.
Available options:
V4,
V4_5,
V4_5PLUS,
V4_5ALL,
V5
Example:

"V4"

​
callBackUrl
string<uri>
required

The URL to receive audio extension task completion updates. Required for all audio extension requests.

  • System will POST task status and results to this URL when audio extension completes
  • Callback includes extended audio files that seamlessly continue the uploaded track's style
  • Your callback endpoint should accept POST requests with JSON payload containing extended track results and audio URLs
  • For detailed callback format and implementation guide, see Audio Extension Callbacks
  • Alternatively, use the Get Music Details endpoint to poll task status
Example:

"https://api.example.com/callback"

​
prompt
string

Description of how the music should be extended. Required when defaultParamFlag is true. Character limits by model:

  • V5: Maximum 5000 characters
  • V4_5PLUS & V4_5: Maximum 5000 characters
  • V4_5ALL: Maximum 5000 characters
  • V4: Maximum 3000 characters
Example:

"Extend the music with more relaxing notes"

​
style
string

Music style, e.g., Jazz, Classical, Electronic. Character limits by model:

  • V5: Maximum 1000 characters
  • V4_5PLUS & V4_5: Maximum 1000 characters
  • V4_5ALL: Maximum 1000 characters
  • V4: Maximum 200 characters
Example:

"Classical"

​
title
string

Music title. Character limits by model:

  • V5: Maximum 100 characters
  • V4_5PLUS & V4_5: Maximum 100 characters
  • V4_5ALL: Maximum 80 characters
  • V4: Maximum 80 characters
Example:

"Peaceful Piano Extended"

​
negativeTags
string

Music styles to exclude from generation

Example:

"Relaxing Piano"

​
vocalGender
enum<string>

Vocal gender preference for the singing voice. Optional. Use 'm' for male and '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

Strength of adherence to the specified style. Optional. Range 0–1, up to 2 decimal places.

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

0.65

​
weirdnessConstraint
number

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

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

0.65

​
audioWeight
number

Balance weight for audio features vs. other factors. Optional. Range 0–1, up to 2 decimal places.

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

0.65

​
personaId
string

Only available when Custom Mode (customMode: true) is enabled. Persona ID to apply to the generated music. Optional. Use this to apply a specific persona style to your music generation.

To generate a persona ID, use the Generate Persona endpoint to create a personalized music Persona based on generated music.

Example:

"persona_123"

Response

Request successful

​
code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 401: Unauthorized - Authentication credentials are missing or invalid
  • 402: Insufficient Credits - Account does not have enough credits to perform the operation
  • 404: Not Found - The requested resource or endpoint does not exist
  • 409: Conflict - WAV record already exists
  • 422: Validation Error - The request parameters failed validation checks
  • 429: Rate Limited - Request limit has been exceeded for this resource
  • 451: Unauthorized - Failed to fetch the image. Kindly verify any access limits set by you or your service provider.
  • 455: Service Unavailable - System is currently undergoing maintenance
  • 500: Server Error - An unexpected error occurred while processing the request
Available options:
200,
401,
402,
404,
409,
422,
429,
451,
455,
500
​
msg
string

Error message when code != 200

Example:

"success"

​
data
object