Skip to main content
POST
Referencing source tracks: mashup requires exactly 2 source tracks—specify them via task_ids (an array of exactly 2 of your task_ids), with optional audio_indexes (a parallel array selecting which item in each task’s music[], 1-based, default 1 for both).
custom determines which fields take effect: fields written under the wrong mode are silently ignored by the upstream (no error). With custom=true, prompt (lyrics), title, tags, negative_tags, auto_lyrics, style_weight, weirdness_constraint, audio_weight, and persona_id take effect and gpt_description is ignored; with custom=false, only gpt_description is read (required in that case — if missing, a 400 is returned at submission time). vocal_gender works in both modes. If custom is omitted, the backend infers it in this order: prompt present → true; no prompt but gpt_description present → false; otherwise tags/title present → true.

Authorizations

Authorization
string
required
All endpoints require authentication using a Bearer TokenGet an API Key:Visit the API Key management page to get your API KeyAdd the following to the request headers when using it:

Body

model
string
default:"suno"
Audio model. Currently pass suno (defaults to suno if omitted).
task_ids
string[]
required
Array of your task_ids for the 2 source tracks (must be exactly 2; any other count returns 400 directly at submission time).
audio_indexes
integer[]
Array parallel to task_ids, selecting which item in each task’s result music[] (1-based, default 1 for both).
instrumental
boolean
default:"false"
Whether purely instrumental (true=no vocals). If omitted, defaults to false (with vocals).
version
string
default:"v5.5"
Generation version: v3.5 / v4 / v4.5 / v4.5+ / v4.5-all / v5 / v5.5, affects audio quality and billing; defaults to v5.5 if omitted, and an invalid value returns 400 directly at submission time.
custom
boolean
true=custom mode (prompt used as lyrics); false=inspiration mode (uses gpt_description); if omitted, inferred from the content (see the Warning above).
prompt
string
Lyrics. Takes effect when custom=true (ignored in inspiration mode).
gpt_description
string
Inspiration prompt. Required when custom=false — if missing, the request fails with 400 at submission (the upstream is not called, nothing is charged).
title
string
Title. Only takes effect when custom=true.
tags
string
Style tags. Only takes effect when custom=true.
negative_tags
string
Style tags to exclude. Only takes effect when custom=true.
auto_lyrics
boolean
true=rewrite the provided lyrics creatively. Only takes effect when custom=true.
style_weight
number
Style weight, 0.001.00 (out-of-range values return 400 directly at submission time). Only takes effect when custom=true.
weirdness_constraint
number
Creativity weight, 0.001.00 (alias weirdness). Only takes effect when custom=true.
audio_weight
number
Audio weight, 0.001.00. Only takes effect when custom=true.
vocal_gender
string
Vocal gender: Male / Female. Works in both modes.
persona_id
string
Persona style id. Only takes effect when custom=true.
Getting the result: This endpoint is an async task. After submitting you get a task_id; poll GET /v1/music/tasks/{task_id} at 3–5s intervals until status is completed or failed (music generation typically takes 30–120s; while generating, status is pending and progress goes queued 10 → ready 50 → done 100). On completion take audio_url from data.result.music[]. On failure data.error.message gives the reason and the pre-deducted quota is automatically refunded.

Response

code
integer
Response status code
data
array
Returned data array