Generate Mashup Music

curl --request POST \
  --url https://api.kie.ai/api/v1/generate/mashup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "customMode": true,
  "model": "V4",
  "callBackUrl": "https://example.com/callback",
  "prompt": "A calm and relaxing piano track with soft melodies",
  "style": "Jazz",
  "title": "Relaxing Piano",
  "instrumental": true,
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}
'

{
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

POST

api

generate

mashup

Generate Mashup Music

curl --request POST \
  --url https://api.kie.ai/api/v1/generate/mashup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "customMode": true,
  "model": "V4",
  "callBackUrl": "https://example.com/callback",
  "prompt": "A calm and relaxing piano track with soft melodies",
  "style": "Jazz",
  "title": "Relaxing Piano",
  "instrumental": true,
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}
'

{
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

Usage Guide

This endpoint creates mashup music from up to 2 uploaded audio files
Combines elements from multiple tracks into a cohesive new composition
You can control detail level with custom mode and instrumental settings

Parameter Details

uploadUrlList is required and must contain exactly 2 audio file URLs
In Custom Mode (customMode: true):
- Character limits vary by model:
  - V4: prompt 3000 characters, style 200 characters
  - V4_5 & V4_5PLUS: prompt 5000 characters, style 1000 characters
  - V4_5ALL: prompt 5000 characters, style 1000 characters
  - V5: prompt 5000 characters, style 1000 characters
- title length limit: 80 characters (all models)
In Non-custom Mode (customMode: false):
- prompt length limit: 500 characters
- instrumental: whether to generate instrumental music
- Other parameters should be left empty

Developer Notes

Recommendation for new users: Start with customMode: false for simpler usage
Generated files are retained for 14 days
Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)
Uploaded audio files must be publicly accessible URLs
The uploadUrlList must contain exactly 2 audio file URLs for mashup generation

Optional parameters

vocalGender (string): Vocal gender preference. Use m for male, f for female. Note: This parameter only takes effect when customMode is true. Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions.
styleWeight (number): Strength of adherence to style. Note: This parameter only takes effect when customMode is true. Range 0–1, up to 2 decimals. Example: 0.61.
weirdnessConstraint (number): Controls creative deviation. Note: This parameter only takes effect when customMode is true. Range 0–1, up to 2 decimals. Example: 0.72.
audioWeight (number): Balance weight for audio features. Note: This parameter only takes effect when customMode is true. Range 0–1, up to 2 decimals. Example: 0.65.

Authorizations

Authorization

string

header

required

All APIs require authentication via Bearer Token.

Get API Key:

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

uploadUrlList

string<uri>[]

required

Array of audio file URLs to mashup. Must contain exactly 2 URLs. Each URL must be publicly accessible.

Required array length: 2 elements

Example:

[
  "https://example.com/audio1.mp3",
  "https://example.com/audio2.mp3"
]

customMode

boolean

required

Determines if advanced parameter customization is enabled.

If true: Allows detailed control with specific requirements for style and title fields.
If false: Simplified mode where only prompt is required and other parameters are ignored.

Example:

true

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 music generation task completion updates. Required for all music generation requests.

System will POST task status and results to this URL when generation completes
Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)
Note: Some cases may skip text and first stages and return complete directly
Your callback endpoint should accept POST requests with JSON payload containing task results and audio URLs
For detailed callback format and implementation guide, see Music Generation Callbacks
Alternatively, use the Get Music Details endpoint to poll task status
To ensure callback security, see Webhook Verification Guide for signature verification implementation

Example:

"https://example.com/callback"

prompt

string

A description of the desired audio content.

In Custom Mode (customMode: true): Required if instrumental is false. The prompt will be strictly used as the lyrics and sung in the generated track. Character limits by model:
- V4: Maximum 3000 characters
- V4_5 & V4_5PLUS: Maximum 5000 characters
- V4_5ALL: Maximum 5000 characters
- V5: Maximum 5000 characters
  Example: "A calm and relaxing piano track with soft melodies"
In Non-custom Mode (customMode: false): Always required. The prompt serves as the core idea, and lyrics will be automatically generated based on it (not strictly matching the input). Maximum 500 characters.
Example: "A short relaxing piano tune"

Example:

"A calm and relaxing piano track with soft melodies"

style

string

Music style specification for the generated audio.

Only available and required in Custom Mode (customMode: true). Defines the genre, mood, or artistic direction.
Character limits by model:
- V4: Maximum 200 characters
- V4_5 & V4_5PLUS: Maximum 1000 characters
- V4_5ALL: Maximum 1000 characters
- V5: Maximum 1000 characters
Common examples: Jazz, Classical, Electronic, Pop, Rock, Hip-hop, etc.

Example:

"Jazz"

title

string

Title for the generated music track.

Only available and required in Custom Mode (customMode: true).
Max length: 80 characters.
Will be displayed in player interfaces and filenames.

Example:

"Relaxing Piano"

instrumental

boolean

Determines if the audio should be instrumental (no lyrics).

In Custom Mode (customMode: true):
- If true: Only style and title are required.
- If false: style, title, and prompt are required (with prompt used as the exact lyrics).
In Non-custom Mode (customMode: false): No impact on required fields (prompt only).

Example:

true

vocalGender

enum<string>

Vocal gender preference for the singing voice.

Only available in Custom Mode (customMode: true). 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.

Only available in Custom Mode (customMode: true). 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.

Only available in Custom Mode (customMode: true). 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

Balance weight for audio features vs. other factors.

Only available in Custom Mode (customMode: true). 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 Codes

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

Show child attributes

Generate Persona Generate Lyrics

​Usage Guide

​Parameter Details

​Developer Notes

​Optional parameters

Authorizations

Body

Response

Usage Guide

Parameter Details

Developer Notes

Optional parameters