MiniMax Format (MiniMax Music)

Generate songs via POST /v1/chat/completions with SSE streaming. Available models: minimax-music-v2.6 / minimax-music-v3.0 (priced separately, see the Model Plaza). Heartbeat chunks arrive every 15 seconds during generation, followed by the song download URL — no task submission or polling, and no risk of "billed but never delivered" from intermediate timeouts.

TIP

Music generation is also available in the Volcengine Format: the async task API (doubao-music-bgm / doubao-music-song, submit → poll → download) and the pre-upgrade synchronous endpoint (Legacy Guide) — choose by model and integration style.

Call Flow

  1. Send the request: POST /v1/chat/completions with stream: true (mandatory) and the creation parameters inside metadata;
  2. Read the stream: during generation (about 40–341 seconds; instrumental takes longer) an empty heartbeat chunk arrives every 15 seconds; once done, one chunk's delta.content is the song mp3 URL;
  3. Download the audio: open the URL and save the file. The URL is valid for 12 hours — transfer it promptly.
WARNING

stream must be true, and the request must carry a messages array. Set the client timeout to 600 seconds or more.

Request Parameters

FieldTypeRequiredDescription
modelstringYesminimax-music-v2.6 / minimax-music-v3.0
streamboolYesAlways true; non-stream requests are rejected
messagesarrayYesChat messages; if metadata has no prompt, the last user message is used as the style prompt
metadata.promptstringSee belowStyle description: genre / mood / scene / instruments, e.g. "独立民谣,忧郁,内省,咖啡馆". Length limit [0, 2000] characters; required when generating instrumental music (is_instrumental: true), length limit [1, 2000] characters
metadata.lyricsstringSee belowCustom lyrics with [verse] / [chorus] markers; when present, the song is composed from the lyrics
metadata.lyrics_optimizerboolNoWhether to auto-generate lyrics from the prompt description. When set to true and lyrics is empty, lyrics are written automatically from prompt. Default: false
metadata.is_instrumentalboolNotrue generates instrumental music (no vocals); prompt is then required
metadata.audio_settingobjectNoAudio parameters, e.g. {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"}
metadata.aigc_watermarkboolNoWhether to add a watermark at the end of the audio; default false. Note: when enabled, the upstream force-re-encodes the audio to 128 kbps, overriding audio_setting.bitrate; do not enable it if you need high audio quality

At least one of prompt / lyrics / is_instrumental is required. Three usage patterns:

  • Custom lyrics: lyrics (required) + optional prompt (style description)
  • Auto lyrics: lyrics_optimizer: true + prompt (song theme), no lyrics
  • Instrumental: is_instrumental: true + prompt (required), no lyrics

Examples

cURL
Python (openai)
Node.js (openai)
curl -N https://api-model.shuntianchuang.cn/v1/chat/completions \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minimax-music-v3.0",
    "stream": true,
    "messages": [{"role": "user", "content": "舒缓的钢琴曲, 适合专注学习"}],
    "metadata": {
      "prompt": "舒缓的钢琴曲, 适合专注学习, 平静放松",
      "is_instrumental": true
    }
  }'
# Chinese prompt works best for the upstream model

Streaming response excerpt (heartbeats omitted):

data: {"choices":[{"delta":{"role":"assistant","content":""}}],...}
data: {"choices":[{"delta":{"content":"https://...mp3?signature"}}],...}   ← the song mp3 URL
data: {"choices":[{"delta":{},"finish_reason":"stop"}],...}
data: {"choices":[],"usage":{"prompt_tokens":100000,"total_tokens":100000}}  ← billed usage
data: [DONE]

Billing & Errors

  • Billing: the final chunk's usage.prompt_tokens is the usage for this request (100000 per song), priced by model ratio; check the console "Usage Logs" for details.
  • Failures: upstream business errors arrive quickly as delta.content text ("生成失败(未计费): ..." — generation failed, not billed) with little to no charge; you will never be billed without receiving the result.
  • The audio URL is valid for 12 hours — download and transfer promptly.

Appendix: Suno Task Format (Deprecated)

WARNING

The Suno task format was deprecated on 2026-09-21: the /suno/* endpoints are offline and return 404. Use "MiniMax Music (chat streaming)" above or the new Volcengine async task API instead. The content below is kept for reference only.

Async task protocol (Suno format): submitting returns a task ID immediately, and the client polls the task status until the song is done. It suits scenarios that need batch submission and poll-based management in a task queue; the currently available model is minimax-music-2.0 (MiniMax Music 2.0, billed per song, subject to the Model Plaza).

Call Flow

  1. Submit the task: POST /suno/submit/music, returns a task ID;
  2. Poll the task: GET /suno/fetch/{task_id} (single) or POST /suno/fetch (batch, body {"ids": [...]}), until status becomes SUCCESS / FAIL;
  3. Download the audio: the task object's data[].audio_url is the song mp3 URL (valid for 7 days — transfer it to your own storage promptly).

Submit Parameters

FieldTypeRequiredNotes
mvstringYesModel name, currently minimax-music-2.0. Must be passed explicitly; a missing value gets filled with a Suno default and the request fails with "unsupported model"
gpt_description_promptstringOne of twoInspiration mode: a style description (genre / mood / scene / instruments); the model writes the lyrics
promptstringOne of twoCustom mode: the lyrics; the model composes and sings them
tagsstringRecommendedCustom mode: genre / style description (e.g. "cheerful folk")
make_instrumentalboolNotrue generates instrumental music (no vocals), default false
title / notify_hook--Not supported yet; ignored if passed
task_id / continue_at / continue_clip_id--Continuation is not supported yet; passing these returns an error

Fill in at least one of gpt_description_prompt (inspiration mode) and prompt (custom-mode lyrics); when both are provided, generation follows "lyrics + style".

Submit response: {"code":"success","message":"","data":"<task ID>"}; on failure {"code":"fail","message":"<error reason>"}.

Task Object

FieldNotes
statusIN_PROGRESS (generating) / SUCCESS (done) / FAIL (failed)
progressProgress percentage, e.g. "40%"
fail_reasonFailure reason (only when FAIL)
submit_time / start_time / finish_timeUnix timestamps (seconds) of submit / start / finish
data[].audio_urlSong mp3 download URL (when SUCCESS)
data[].metadata.durationSong duration (seconds)
data[].metadata.tags / metadata.promptEchoed style description / lyrics
cURL
Python
Node.js
# 1. Submit (inspiration mode: only a style description; the model writes the lyrics)
curl -s https://api-model.shuntianchuang.cn/suno/submit/music \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{"mv": "minimax-music-2.0", "gpt_description_prompt": "欢快的电子舞曲"}'
# => {"code":"success","message":"","data":"<task ID>"}

# 2. Poll (replace <task ID> with the value returned above, about once every 10 seconds)
curl -s https://api-model.shuntianchuang.cn/suno/fetch/<task ID> \
  -H "Authorization: Bearer sk-your-token"
# Once status is SUCCESS, data[0].audio_url is the song URL

# 3. Download
curl -s -o song.mp3 "<data[0].audio_url>"

Submit body example for custom mode (lyrics + style):

curl -s https://api-model.shuntianchuang.cn/suno/submit/music \
  -H "Authorization: Bearer sk-your-token" \
  -H "Content-Type: application/json" \
  -d '{"mv": "minimax-music-2.0", "prompt": "大海啊全是水", "tags": "欢快的民谣"}'
WARNING

mv must be passed explicitly as minimax-music-2.0: with this protocol a missing model name gets filled by the gateway with a Suno default (chirp-v3-0), which is not supported on this site — the request returns an "unsupported model" error.

NOTE

Billing is per song, regardless of song duration (in our testing, an auto-written-lyrics ~3-minute full song and a short-lyrics snippet cost the same); generation takes 1–5 minutes, which is normal — poll every 10 seconds and allow at least 5 minutes total. The song mp3 URL is valid for 7 days; for commercial use, transfer it to your own storage promptly.