Skip to main content
POST
/
api
/
v1
/
generate
/
mashup
Generate Mashup
curl --request POST \
  --url https://api.sunoapi.org/api/v1/generate/mashup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "uploadUrlList": [
    "https://storage.example.com/audio1.mp3",
    "https://storage.example.com/audio2.mp3"
  ],
  "customMode": true,
  "model": "V4_5ALL",
  "callBackUrl": "https://api.example.com/callback",
  "prompt": "A calm and relaxing piano track with soft melodies",
  "style": "Classical",
  "title": "Peaceful Piano Meditation",
  "instrumental": true,
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65
}
'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
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

​
Parameter Details

  • uploadUrlList: Required parameter, array containing exactly 2 audio file URLs to be mashed up together. Both URLs must be valid and accessible.
  • customMode: Required parameter, enables Custom Mode for advanced audio generation settings
  • prompt: Required parameter. Character limits by model:
    • V4: Maximum 3000 characters (Custom Mode) or 500 characters (Non-custom Mode)
    • V4_5, V4_5PLUS, V4_5ALL & V5: Maximum 5000 characters (Custom Mode) or 500 characters (Non-custom Mode)
  • style: Required in Custom Mode. Character limits by model:
    • V4: Maximum 200 characters
    • V4_5, V4_5PLUS, V4_5ALL & V5: Maximum 1000 characters
  • title: Required in Custom Mode. Character limits by model:
    • V4 & V4_5ALL: Maximum 80 characters
    • V4_5, V4_5PLUS & V5: Maximum 100 characters
  • instrumental: Determines if the audio should be instrumental (no lyrics)
  • model: Required parameter, the model version to use for audio generation
  • vocalGender: Optional parameter, preferred vocal gender for generated vocals (m or f)
  • styleWeight: Optional parameter, weight of the provided style guidance (0.00–1.00)
  • weirdnessConstraint: Optional parameter, constraint on creative deviation/novelty (0.00–1.00)
  • audioWeight: Optional parameter, weight of the input audio influence (0.00–1.00)
  • callBackUrl: Required parameter, the URL to receive task completion notifications

​
Developer Notes

  1. Audio Requirements: Ensure both audio files in uploadUrlList are accessible and valid. The system will blend these two audio files to create the mashup.
  2. Generated files: Generated files are retained for 15 days before being deleted
  3. Ensure all required fields: Provide all required fields based on the customMode and instrumental settings to avoid errors
  4. Character limits: Respect the character limits for prompt, style, and title to ensure successful processing
  5. Callback process: Callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete)
  6. Task status: You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks
  7. Persona generation: Generated mashups can be used with the Generate Persona endpoint to create Personas for subsequent music generation

​
Parameter Example

{
  "uploadUrlList": [
    "https://storage.example.com/audio1.mp3",
    "https://storage.example.com/audio2.mp3"
  ],
  "customMode": true,
  "instrumental": true,
  "style": "Electronic Dance",
  "title": "Mashup Mix",
  "model": "V4_5ALL",
  "callBackUrl": "https://api.example.com/callback"
}
Ensure that both audio file URLs in uploadUrlList are accessible and valid. The system requires exactly 2 URLs to create the mashup.
For best results, use audio files with similar characteristics (tempo, key, etc.) to create more harmonious mashups. You can also use the generated mashup to create a Persona for subsequent music generation.
The uploadUrlList must contain exactly 2 audio file URLs. Providing more or fewer URLs will result in an error.

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 containing exactly 2 audio file URLs to be mashed up together. Both URLs must be valid and accessible.

Required array length: 2 elements
Example:
[
  "https://storage.example.com/audio1.mp3",
  "https://storage.example.com/audio2.mp3"
]
​
customMode
boolean
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.
Example:

true

​
model
enum<string>
required

The model version to use for audio generation.

  • Available options:
    • 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.
Available options:
V4,
V4_5,
V4_5PLUS,
V4_5ALL,
V5
Example:

"V4_5ALL"

​
callBackUrl
string<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:

"https://api.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, V4_5ALL & 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

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: Maximum 1000 characters
      Example: "Classical"
  • In Non-custom Mode (customMode: false): Leave empty.
Example:

"Classical"

​
title
string

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: Maximum 100 characters
      Example: "Peaceful Piano Meditation"
  • In Non-custom Mode (customMode: false): Leave empty.
Maximum string length: 100
Example:

"Peaceful Piano Meditation"

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

true

​
vocalGender
enum<string>

Preferred vocal gender for generated vocals. Optional.

Available options:
m,
f
Example:

"m"

​
styleWeight
number

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

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

0.65

​
weirdnessConstraint
number

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

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

0.65

​
audioWeight
number

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

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

Callback received successfully

Response

Request successful

​
code
enum<integer>

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
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

Error message when code != 200

Example:

"success"

​
data
object