{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "lyrics": "[Verse] Night city lights shining bright",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "variety": 1,
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

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

POST

api

generate

mashup

{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "lyrics": "[Verse] Night city lights shining bright",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "variety": 1,
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

{
  "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 runs in custom mode. Simple mode is not available.
This endpoint creates mashup music from 2 uploaded audio files (the upstream uses only the first 2)
Combines elements from multiple tracks into a cohesive new composition

Parameter Details

Required: uploadUrlList, model, callBackUrl
uploadUrlList must contain 2 audio file URLs
model (string, required): V6, V6_WILD, V6_MINI. Deprecated: V4, V4_5, V4_5PLUS, V4_5ALL, V5, V5_5.
prompt is lyrics. Optional. If lyrics is also provided, lyrics takes priority and prompt is not used as lyrics.
Character limits:
- 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: lyrics/prompt 5000 characters, style 1000 characters, title 80 characters

Optional parameters

The following fields are optional controls available for this endpoint:

lyrics (string): Lyrics content. Optional. V6 series maximum 5000 characters. Takes priority over prompt as lyrics.
prompt (string): Lyrics content. Optional. Used as lyrics when lyrics is not provided. V6 series maximum 5000 characters.
style (string): Music style. Optional. V6 series maximum 1000 characters.
title (string): Track title. Optional. Maximum 80 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)
variety (number): Diversity of generated results. Integer from 0–4, default 1. 0 off, 1 normal (default), 2 high, 3 extra, 4 max.
duration (number): Audio duration in seconds. Range 10–360. Valid for V5_5, V6, V6_WILD, and V6_MINI.
personaId (string): Persona ID or Suno Voice voiceId. If you use a Voice-generated ID, set personaModel to voice_persona.
personaModel (string): Persona type. Use style_persona for Generate Persona IDs, or voice_persona for Suno Voice IDs. Default style_persona.

{
  "uploadUrlList": [
    "https://example.com/audio1.mp3",
    "https://example.com/audio2.mp3"
  ],
  "lyrics": "[Verse] Night city lights shining bright",
  "style": "Electronic Dance Music",
  "title": "Mashup Work",
  "variety": 1,
  "model": "V6",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

Developer Notes

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. Pass 2 audio URLs (the upstream uses only the first 2). Each URL must be publicly accessible.

Required array length: 2 elements

Example:

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

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 content. Optional. Used as lyrics when lyrics is not provided. If lyrics is also provided, lyrics takes priority and this field is not used as lyrics.

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

Example:

"[Verse] Night city lights shining bright"

lyrics

string

Lyrics for the generated audio. Optional. For V6, V6_MINI, and V6_WILD: maximum 5000 characters. Takes priority over prompt as lyrics. If omitted, prompt is used as lyrics.

Example:

"[Verse] Night city lights shining bright"

style

string

Music style, e.g. Jazz, Classical, or Electronic. Optional. For V6, V6_WILD, and V6_MINI: maximum 1000 characters.

V4 (Deprecated): Maximum 200 characters
V4_5, V4_5PLUS, V4_5ALL, V5, V5_5 (Deprecated): Maximum 1000 characters

Example:

"Jazz"

title

string

Music title. Optional. Maximum 80 characters.

Maximum string length: 80

Example:

"Relaxing Piano"

vocalGender

enum<string>

Vocal gender preference for the singing voice. Optional. Use m for male and f for female. In practice, this only increases probability and cannot guarantee male/female voice instructions are followed.

Available options:

m,

f

Example:

"m"

styleWeight

number

Style adherence weight. Optional. Range 0–1, up to 2 decimal places.

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

Example:

0.65

weirdnessConstraint

number

Creativity/novelty constraint. Optional. Range 0–1, up to 2 decimal places.

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

Example:

0.65

audioWeight

number

Relative weight of audio consistency versus other controls. Optional. Range 0–1, up to 2 decimal places.

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

Example:

0.65

variety

number

default:1

Controls the diversity and stylistic variation of generated results. Optional. Integer from 0–4, default 1.

0: off (exact style) — fully off, strictly the same style
1: normal (balanced variety) — default, balances stability and diversity
2: high (distinct styles) — produces results with clearly different styles
3: extra (bold exploration) — higher variation, encourages bold exploration of different styles
4: max (unreasonably varied) — maximum diversity; results may differ in style very significantly

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

Example:

1

personaId

string

Persona ID or Voice ID to apply to the generated music. Optional. When using a Voice-generated ID, set personaModel to voice_persona.

Example:

"persona_123"

personaModel

enum<string>

default:style_persona

Persona model type. Optional. style_persona (default) for Generate Persona IDs; voice_persona when personaId is a Suno Voice voiceId. Default style_persona.

Available options:

style_persona,

voice_persona

Example:

"style_persona"

duration

integer

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

Required range: 10 <= x <= 360

Example:

20

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

Generate Lyrics

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