v1

latestOpenAPI 3.0.02026-07-26355125.0 KB

Music Generation

Generate Mashup

Create a mashup by blending two audio files together to generate new music.

Usage Guide

Use this endpoint to create mashups by combining two audio files
Requires exactly 2 audio file URLs in the uploadUrlList array
Supports both custom and non-custom modes for different generation styles
Generated mashups can be used to create Personas for subsequent music generation

post/api/v1/generate/mashup

Request body

uploadUrlListstring[] required

Array containing exactly 2 audio file URLs to be mashed up together. Both URLs must be valid and accessible.

customModeboolean required

Enables Custom Mode for advanced audio generation settings.

Set to true to use Custom Mode (requires style and title; prompt required if instrumental is false). The prompt will be strictly used as lyrics if instrumental is false.
Set to false for Non-custom Mode (only prompt is required). Lyrics will be auto-generated based on the prompt.

promptstring

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, V4_5ALL, V5 & V5_5: 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"

stylestring

The music style or genre for the audio.

Required in Custom Mode (customMode: true). Examples: "Jazz", "Classical", "Electronic". Character limits by model:
- V4: Maximum 200 characters
- V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 1000 characters
  Example: "Classical"
In Non-custom Mode (customMode: false): Leave empty.

titlestring

The title of the generated music track.

Required in Custom Mode (customMode: true). Character limits by model:
- V4 & V4_5ALL: Maximum 80 characters
- V4_5, V4_5PLUS, V5 & V5_5: Maximum 100 characters
  Example: "Peaceful Piano Meditation"
In Non-custom Mode (customMode: false): Leave empty.

instrumentalboolean

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). Lyrics are auto-generated if instrumental is false.

The model version to use for audio generation.

Available options:
- V5_5: Unleash your voice: custom models tailored to your unique taste. Same prompt/style character limits as V5 in Custom Mode.
- V5: Superior musical expression, faster generation.
- V4_5PLUS: V4.5+ is richer sound, new ways to create, max 8 min.
- V4_5ALL: V4.5-all is better song structure, max 8 min.
- V4_5: Superior genre blending with smarter prompts and faster output, up to 8 minutes.
- V4: Best audio quality with refined song structure, up to 4 minutes.

vocalGender'm' | 'f'

Preferred vocal gender for generated vocals. Optional.

styleWeightnumber

Weight of the provided style guidance. Range 0.00–1.00.

weirdnessConstraintnumber

Constraint on creative deviation/novelty. Range 0.00–1.00.

audioWeightnumber

Weight of the input audio influence (where applicable). Range 0.00–1.00.

durationinteger

Optional duration in seconds. Only effective when customMode is true and model is V5_5.

Range: 10–360
Example: 20

callBackUrlstring uri required

The URL to receive task completion notifications when mashup generation is complete.

For detailed callback format and implementation guide, see Music Generation Callbacks
Alternatively, you can use the get music generation details endpoint to poll task status

Example request

{
  "uploadUrlList": [
    "https://storage.example.com/audio1.mp3",
    "https://storage.example.com/audio2.mp3"
  ],
  "customMode": true,
  "prompt": "A calm and relaxing piano track with soft melodies",
  "style": "Classical",
  "title": "Peaceful Piano Meditation",
  "instrumental": true,
  "model": "V4_5ALL",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "duration": 20,
  "callBackUrl": "https://api.example.com/callback"
}

Response

Request successful

code200 | 400 | 401 | 404 | 405 | 413 | 429 | 430 | 455 | 500

Status Codes

✅ 200 - Request successful
⚠️ 400 - Invalid parameters
⚠️ 401 - Unauthorized access
⚠️ 404 - Invalid request method or path
⚠️ 405 - Rate limit exceeded
⚠️ 413 - Theme or prompt too long
⚠️ 429 - Insufficient credits
⚠️ 430 - Your call frequency is too high. Please try again later.
⚠️ 455 - System maintenance
❌ 500 - Server error

msgstring

Error message when code != 200

Example response

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