Music GenerationtaskType: generate_mashup30 Credits / Task

Generate Mashup Music

Create seamless audio mashups by blending two Suno tracks together. Intelligently harmonizes key signatures, beat tempos, vocal stems, and acoustic instrumentations into two high-fidelity cohesive songs.

POST/api/v1/createTask

Test in Playground

How Mashup Generation Works

Harmonic Alignment

Analyzes harmonic roots and dynamically aligns musical keys so transitions between both source tracks sound natural.

Tempo & Beatmatching

Synchronizes BPM and rhythmic percussion so drum beats, drops, and baselines lock in simultaneously.

Stem Cross-Blending

Fuses vocal melodies from one track over instrumental hooks from the second, or synthesizes brand-new hybrid hooks.

Supported AI Models

V6, V6_WILD, V6_MINI, V4

V6DEFAULT

Flagship model offering rich acoustic depth, natural vocal timbres, and polished transitions.

V6_WILDEXPERIMENTAL

Pushes creative boundaries with bolder sonic variations, unexpected drops, and genre clashes.

V6_MINIFAST

Lightweight and rapid generation, balancing latency and high-fidelity output.

Validation Rules & Constraints

Audio URL Requirements

upload_url_list must contain at least 2 valid audio URLs.
Upstream uses the first two items in the array for the mashup.
URLs must be publicly accessible via standard HTTP/HTTPS GET requests.
Supported audio formats include MP3, WAV, and AAC.
Generated files will be retained on cloud storage for 14 days.

Character Limits by Model

V6 / V6_WILD / V6_MINI: Title ≤ 100 chars, Style ≤ 1,000 chars, Lyrics / Prompt ≤ 5,000 chars.
V4: Title ≤ 80 chars, Style ≤ 200 chars, Prompt ≤ 3,000 chars.
lyrics takes priority over prompt. If lyrics is omitted, prompt is used as lyrics.
duration: 10 to 360 seconds (default: 20 seconds).

Variety & Stylistic Controls (0 - 4)

0: Off

Strict adherence to exact reference styles.

1: Balanced (Default)

Harmonizes stability and creative variety.

2: High

Distinct rhythmic variations between tracks.

3: Extra

Bold exploration of unusual genre crossovers.

4: Max

Maximum divergence and radical style mashups.

Authentication & Headers

Header	Requirement	Description
Authorization	required	Bearer YOUR_API_KEY Secret API Key obtained from your Suno API dashboard.
Content-Type	required	application/json Request payload format.

Header

Requirement

Description

Authorization

required

Bearer YOUR_API_KEY

Secret API Key obtained from your Suno API dashboard.

Content-Type

required

application/json

Request payload format.

Request Body Schema

16 fields

upload_url_listarrayrequired

Array of publicly accessible audio URLs to mash up. Must contain at least 2 audio URLs. Upstream uses the first 2 tracks to harmonize tempo, key, vocals, and instrumentation.

titlestringrequired

Title for the generated mashup music track (max 100 characters for V6 / V6_MINI / V6_WILD, max 80 characters for V4).

stylestringrequired

Music style specification for the combined track (e.g., "Acoustic Pop, EDM Drop, Melodic Synth, 128 BPM"). Max 1,000 characters for V6, max 200 characters for V4.

modelstringoptional

default:V6

Suno AI generation model version. Supported: "V6" (Default, refined details & natural vocals), "V6_WILD" (creative experimental deviation), "V6_MINI" (fast & lightweight), or "V4".

taskTypestringoptional

default:generate_mashup

Task routing identifier. Explicitly set to "generate_mashup". Can also be auto-detected when "upload_url_list" is provided.

lyricsstringoptional

Custom lyrics for the mashup track (verses, chorus, bridge). Takes priority over prompt as lyrics. Max 5,000 characters.

promptstringoptional

Description of desired audio or additional lyric cues. Used as lyrics only when "lyrics" is omitted. Max 5,000 characters for V6.

durationnumberoptional

default:20

Audio duration in seconds. Integer range: 10 to 360, default is 20.

vocal_genderstringoptional

Vocal gender preference for singing voice: "m" for male, "f" for female (increases probability of preferred gender).

style_weightnumberoptional

default:0.65

Strength of adherence to specified style tags (range 0.0 to 1.0, up to 2 decimal places).

weirdness_constraintnumberoptional

default:0.65

Creative/experimental deviation control (range 0.0 to 1.0, up to 2 decimal places).

audio_weightnumberoptional

default:0.65

Balance weight for source audio features vs newly synthesized elements (range 0.0 to 1.0).

varietynumberoptional

default:1

Diversity and stylistic variation: 0 (exact match), 1 (normal / balanced, default), 2 (high diversity), 3 (extra exploration), 4 (max variation).

persona_idstringoptional

Persona ID or Suno Voice ID to apply consistent vocal tone and timbre to the mashup track.

persona_modelstringoptional

default:style_persona

Persona model type: "style_persona" for Persona IDs, or "voice_persona" for Voice IDs.

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notifications across text, first, and complete generation stages.

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

Text/Lyrics alignment processed (callbackType: "text")
First mashup track generated & stream ready (callbackType: "first")
All mashup variations completed (callbackType: "complete")
Task failed or validation rejected (code: 400, 408, 500, 501)

Webhook Payload Format

Response Body(200 status)

{
  "code": 200,
  "msg": "All generated successfully.",
  "data": {
    "callbackType": "complete",
    "task_id": "7f8b92c431e5491fa9c6691456a02b11",
    "data": [
      {
        "id": "m123bcde-5678-4901-abcd-ef0123456789",
        "audio_url": "https://cdn.example.com/audio/mashup_variation_1.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/mashup_stream_1.m3u8",
        "image_url": "https://cdn.example.com/cover/mashup_cover_1.jpeg",
        "prompt": "Electropop, Melodic Tropical House, 124 BPM, Uplifting",
        "model_name": "chirp-v4-5",
        "title": "Summer Sunrise Mashup",
        "createTime": 1786345800000,
        "duration": 62.4,
        "tags": "electropop, melodic tropical house, 124 bpm, uplifting",
        "source_audio_url": "https://example.com/audio/source_track_a.mp3",
        "source_image_url": "https://cdn.example.com/cover/source_a.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/source_a_stream"
      },
      {
        "id": "m234cdef-6789-5012-bcde-f0123456789a",
        "audio_url": "https://cdn.example.com/audio/mashup_variation_2.mp3",
        "stream_audio_url": "https://cdn.example.com/audio/mashup_stream_2.m3u8",
        "image_url": "https://cdn.example.com/cover/mashup_cover_2.jpeg",
        "prompt": "Electropop, Melodic Tropical House, 124 BPM, Uplifting",
        "model_name": "chirp-v4-5",
        "title": "Summer Sunrise Mashup",
        "createTime": 1786345800000,
        "duration": 62.4,
        "tags": "electropop, melodic tropical house, 124 bpm, uplifting",
        "source_audio_url": "https://example.com/audio/source_track_b.mp3",
        "source_image_url": "https://cdn.example.com/cover/source_b.jpeg",
        "source_stream_audio_url": "https://cdn.example.com/audio/source_b_stream"
      }
    ]
  }
}

Callback Payload Fields

Field	Type	Description
`code`	integer	Status code (200: Success, 400: Validation error, 408: Timeout, 500: Server error, 501: Synthesis failed).
`msg`	string	Execution message ("All generated successfully." or specific error reason).
`data.callbackType`	string	Generation progress stage: "text" (cue parse), "first" (track 1 ready), or "complete" (all tracks ready).
`data.task_id`	string	Unique task identifier corresponding to the taskId returned upon creation.
`data.data[]`	array	Array of 2 generated mashup audio objects containing MP3 URLs, HLS stream URLs, artwork, and metadata.
`data.data[].audio_url`	string	Direct high-fidelity MP3 download and streaming URL for the generated mashup.
`data.data[].duration`	number	Exact duration of the generated track in seconds.

Receiver Implementation Example

Webhook Receiver

// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if (code === 200 && data) {
    const { callbackType, task_id, data: tracks } = data;
    console.log(`Received ${callbackType} callback for mashup task ${task_id}`);

    if (callbackType === 'complete' && Array.isArray(tracks)) {
      tracks.forEach((track, index) => {
        console.log(`Track ${index + 1}: ${track.title} - ${track.audio_url}`);
        // Store final audio URLs in your database...
      });
    }
  } else {
    console.error(`Mashup generation failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Request Sample

curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "generate_mashup",
    "upload_url_list": [
      "https://example.com/audio/source_track_a.mp3",
      "https://example.com/audio/source_track_b.mp3"
    ],
    "title": "Summer Sunrise Mashup",
    "style": "Electropop, Melodic Tropical House, 124 BPM, Uplifting",
    "model": "V6",
    "vocal_gender": "f",
    "variety": 1,
    "duration": 60,
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'

Response Body(200 status)

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "7f8b92c431e5491fa9c6691456a02b11"
  }
}

Previous EndpointBoost Music Style Next EndpointReplace Music Section

Ready to integrate Generate Mashup Music?

Create your account, obtain your API key, and begin seamlessly blending tracks together.

Generate Secret Key