Skip to main content
POST
/
api
/
v1
/
generate
/
mashup
{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "customMode": true,
  "prompt": "A dynamic mashup blending electronic and rock elements",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "model": "V4_5ALL",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "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
  • model (string, required): V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5. V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste — same custom-mode limits as V5.
  • 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
      • V5_5: same prompt / style limits as V5 (Unleash Your Voice: Custom Models Tailored to Your Unique Taste)
    • 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

​
Optional parameters

The following fields are optional controls available for this endpoint:
  • vocalGender (string): Preferred vocal gender. Allowed values: m (male), f (female)
  • styleWeight (number): Style adherence weight in range 0–1 (recommended two decimals)
  • weirdnessConstraint (number): Creativity/novelty constraint in range 0–1 (recommended two decimals)
  • audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "customMode": true,
  "prompt": "A dynamic mashup blending electronic and rock elements",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "model": "V4_5ALL",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

​
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)
  • The two audio files in uploadUrlList must be valid and accessible URLs
  • Audio files should be in supported formats (MP3, WAV, etc.)

Authorizations

​
Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

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 from 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.
    • V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste. Same custom-mode prompt and style character limits as V5 (5000 / 1000).
    • 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,
V5_5
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
    • V5_5: Maximum 5000 characters (same limits as V5)
      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
    • V5_5: Maximum 1000 characters (same limits as V5)
  • 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

Callbacks

POST
{request.body#/callBackUrl}audioGenerated

Body

application/json
​
code
integer

Status code

Example:

200

​
msg
string

Response message

Example:

"All generated successfully"

​
data
object

Response

200 - application/json

Callback received successfully

​
code
enum<integer>

Response status code

  • 200: Success - Request has been processed successfully
  • 400: Validation Error - Lyrics contained copyrighted material.
  • 408: Rate Limited - Timeout.
  • 413: Conflict - Uploaded audio matches existing work of art.
  • 500: Server Error - An unexpected error occurred while processing the request
  • 501: Audio generation failed.
  • 531: Server Error - Sorry, the generation failed due to an issue. Your credits have been refunded. Please try again.
Available options:
200,
400,
408,
413,
500,
501,
531
​
msg
string

Error message when code != 200

Example:

"success"

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