{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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

POST

api

generate

mashup

{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

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

Model Versions

Current models: V6 (default), V6_WILD, V6_MINI
Deprecated models: V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, V4
Deprecated values remain available only for backward compatibility. New integrations should use a V6-series model.

Usage Guide

This endpoint always uses custom parameters. Simple mode is not available.
This endpoint creates mashup music from 2 uploaded audio files
Combines elements from multiple tracks into a cohesive new composition

Parameter Details

uploadUrlList is required and must contain exactly 2 audio file URLs; only the first 2 are used
model (string, required): V6, V6_WILD, V6_MINI. Deprecated: V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5.
style and title are required
prompt is optional and is treated as lyrics. When lyrics is also provided, lyrics takes priority and prompt is not used as lyrics
lyrics is optional. It takes priority over prompt as the lyrics. If lyrics is omitted, prompt is used as the lyrics
Character limits (based on model):
- V4, V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5 (Deprecated): prompt 3000–5000 characters and style 200–1000 characters according to the legacy model.
- V6, V6_WILD & V6_MINI: prompt and lyrics max 5000 characters, style max 1000 characters
- title length limit: 80 characters (all models)

Optional parameters

The following fields are optional controls available for this endpoint:

lyrics (string): Lyrics for the mashup. Takes priority over prompt. If omitted, prompt is used as the lyrics. For V6, V6_WILD, and V6_MINI: maximum 5000 characters.
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)
duration (number): Duration in seconds, range 10–360. Only effective with V5_5 (Deprecated), V6, V6_WILD, or V6_MINI.
variety (integer): Diversity of generated results. Integer from 0–4, default 1. 0 off, 1 normal (default), 2 high, 3 extra, 4 max.
personaId (string): Persona ID or Suno Voice voiceId to apply to the generated music. If you use a Voice-generated ID, set personaModel to voice_persona.
personaModel (string): Persona type, default style_persona. Use style_persona for Generate Persona IDs, or voice_persona for Suno Voice IDs.

{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "lyrics": "[Chorus] Brighter lights, we keep going on",
  "prompt": "[Verse] City hums under neon rain",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65,
  "variety": 1
}

Developer Notes

This endpoint always uses custom parameters; style and title must be provided along with the two source audio URLs
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

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. Required. Provide exactly 2 URLs; only the first 2 are used. Each URL must be publicly accessible.

Required array length: 2 elements

Example:

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

style

string

required

The music style or genre. Required. Examples: "Jazz", "Classical", "Electronic".

For V4 (Deprecated): Maximum 200 characters.
For V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL (Deprecated): Maximum 1000 characters.
For V6, V6_WILD & V6_MINI: Maximum 1000 characters.

Example:

"Jazz"

title

string

required

Title for the generated music track. Required.

Max length: 80 characters.
Will be displayed in player interfaces and filenames.

Example:

"Relaxing Piano"

model

enum<string>

default:V6

required

AI model version. Default: V6.

V6: Current standard model and recommended default.
V6_WILD: Current model for more experimental and creative results.
V6_MINI: Current lightweight model.
Deprecated: V5_5, V5, V4_5PLUS, V4_5ALL, V4_5, and V4. These values remain listed only for backward compatibility; use a V6-series model for new integrations.

Available options:

V6,

V6_WILD,

V6_MINI,

V5_5,

V5,

V4_5PLUS,

V4_5ALL,

V4_5,

V4

Example:

"V6"

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

Example:

"https://example.com/callback"

prompt

string

Lyrics for the mashup. Optional. The prompt is used strictly as lyrics and sung in the generated track. When lyrics is also provided, lyrics takes priority and prompt is not used as lyrics. Character limits by model:

V4 (Deprecated): Maximum 3000 characters
V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL (Deprecated): Maximum 5000 characters
V6, V6_WILD & V6_MINI: Maximum 5000 characters

Example:

"[Verse] City hums under neon rain"

lyrics

string

Lyrics for the mashup. Optional. Takes priority over prompt as the lyrics. If omitted, prompt is used as the lyrics.

V6, V6_WILD & V6_MINI: Maximum 5000 characters

Example:

"[Chorus] Brighter lights, we keep going on"

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.61

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.72

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

duration

number

Duration in seconds. Optional. Range 10–360. Only effective when model is V5_5 (Deprecated), V6, V6_WILD, or V6_MINI.

Required range: 10 <= x <= 360

Example:

20

variety

integer

default:1

Diversity of generated results. Optional. Integer from 0 to 4. Default: 1.

0: off — variety off, strictly the same style
1: normal — default, balances stability and diversity
2: high — results with clearly different styles
3: extra — higher variation, bolder exploration
4: max — maximum variation

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

Example:

1

personaId

string

Persona ID to apply to the generated music. Optional. You can use either:

A Persona ID generated by the Generate Persona endpoint. Use personaModel: style_persona or omit personaModel to use the default.
A voiceId generated by the Suno Voice workflow. When using a voice-generated ID, you must set personaModel: voice_persona.

Example:

"persona_123"

personaModel

enum<string>

default:style_persona

Persona model type to apply when using personaId. Optional.

style_persona (default): Use this for Persona IDs generated by the Generate Persona endpoint.
voice_persona: Required when personaId is a voiceId generated by Suno Voice. This option is only available with V5 (Deprecated), V5_5 (Deprecated), V6, V6_WILD, and V6_MINI models.

Available options:

style_persona,

voice_persona

Example:

"style_persona"

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

Show child attributes

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

Show child attributes

Generate Music

Suno Voice

Lyrics Generation

Generate Sounds

WAV Conversion

Vocal Removal

Music Video Generation

Account Management

File Upload API

Generate Mashup

Model Versions

Usage Guide

Parameter Details

Optional parameters

Developer Notes

Authorizations

🔑 API Authentication

Get API Key

Usage

Body

Callbacks

Body

Response

Response

​Model Versions

​Usage Guide

​Parameter Details

​Optional parameters

​Developer Notes

Authorizations

🔑 API Authentication

Get API Key

Usage

Body

Callbacks

Body

Response

Response

Model Versions

Usage Guide

Parameter Details

Optional parameters

Developer Notes