Generate Mashup Music

Create mashup music by combining multiple audio tracks using AI models.

POST /api/v1/generate/mashup

Generate Mashup Music

cURL

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
}
'

200

{
  "code": 200,
  "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:

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

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

200

application/json

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