MiniMax Music Generation API Guide

Unduh

Mode fokus

Ukuran font

Terakhir diperbarui: 2026-10-28 17:28:20

Diterjemahkan oleh AI

Overview
The MiniMax music generation model supports generating complete songs or instrumental music from text descriptions (style, mood, scene). It also supports custom lyrics (including structural tags), automatic lyric writing, and multi-quality parameter configuration. This document describes how to call the MiniMax music model through TokenHub: minimax-music-v3.0.
Call Method
Music generation is a synchronous call: a single request directly returns the generated result without creating a task or polling. Audio supports two return formats:
hex: Hex-encoded audio data (default). The client must decode it and write it to a file.
url: The download link for the audio file, valid for 12 hours. Download it promptly.
Prerequisites
You have registered a Tencent Cloud account and activated the TokenHub service.
You have obtained an API Key from the TokenHub console.
Enable postpaid billing for the corresponding model in Console - Online Inference - Voice Models.
Note:
In all examples below, replace YOUR_API_KEY with your own API Key. The authentication method is the request header Authorization: Bearer YOUR_API_KEY.
Model list
Model Name
model ID
Supported Capability
Lyrics Limit
Prompt Limit
Selection Recommendations
MiniMax-Music-v3.0
minimax-music-v3.0
Song generation (vocals) / Instrumental music / Automatic lyric writing
3500 characters
2000 characters
Overall sound quality is significantly improved, and vocal synthesis is more natural.
Music Generation
1. API Description
Enter a song description and lyrics to generate complete music. Three creation modes are supported: Custom Lyrics, Auto Write Lyrics (lyrics are automatically generated based on the prompt), and Instrumental (no vocals).
API: POST https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-music/generation
2. Input Parameters
Parameter Name
Required
Type
Description
model
Yes
string
Model version. Value: minimax-music-v3.0
prompt
Conditionally required
string
Music description used to specify the style, mood, and scene, such as "Pop, melancholic, perfect for a rainy night". Length limit: [0, 2000] characters. Required when instrumental music is generated (is_instrumental: true), with a length limit of [1, 2000] characters.
lyrics
Conditionally required
string
Song lyrics, with each line separated by \\n. Supported structure tags: [Intro], [Verse], [Pre Chorus], [Chorus], [Interlude], [Bridge], [Outro], [Post Chorus], [Transition], [Break], [Hook], [Build Up], [Inst], [Solo]. Required when songs with vocals are generated, with a length limit of [1, 3500] characters; optional for instrumental music.
lyrics_optimizer
No
boolean
Whether to automatically generate lyrics based on the prompt description. When set to true and lyrics is empty, the system automatically writes lyrics based on the prompt. Default value: false.
is_instrumental
No
boolean
Whether to generate instrumental music (without vocals). When set to true, lyrics is optional. Default value: false.
output_format
No
string
Audio return format. Optional values: hex (hexadecimal encoding, default) / url (download link, valid for 12 hours).
audio_setting
No
object
Audio output configuration. See the table below for subfields.
aigc_watermark
No
boolean
Whether to add a watermark at the end of the audio. Default value: false.
Subfields of the audio_setting object:
Parameter Name
Required
Type
Description
sample_rate
No
integer
Sample rate (Hz), for example, 44100
bitrate
No
integer
Bitrate (bps), for example, 256000
format
No
string
Audio format, for example, mp3
Attention:
The parameter combinations for the three creation modes are as follows:
Custom Lyrics: Pass lyrics (required) + prompt (optional).
Auto Write Lyrics: Set lyrics_optimizer: true, leave lyrics empty, and use prompt to describe the song theme.
Instrumental: is_instrumental: true + prompt (required). No lyrics is needed.
3. Request Example
Mode 1: Auto Write Lyrics (generate lyrics and vocal songs based on the prompt)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-music/generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "minimax-music-v3.0",
  "prompt": "Pop, melancholic, perfect for a rainy night",
  "lyrics_optimizer": true,
  "output_format":"url"
}'
Mode 2: Custom Lyrics
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-music/generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "minimax-music-v3.0",
  "prompt": "Indie folk, Melancholic, Introspective, Coffeehouse",
  "lyrics": "[verse]\\nStreetlights glow faintly, the evening breeze gently strokes\\nShadows stretch long as I wander alone\\nAn old coat wraps me in deep melancholy\\nNot knowing where to go, longing for somewhere\\n[chorus]\\nPush open the wooden door, aroma fills the air\\nA familiar corner, strangers glance",
  "output_format": "url",
  "audio_setting": {
    "sample_rate": 44100,
    "bitrate": 256000,
    "format": "mp3"
  }
}'
Mode 3: Instrumental (no vocals)
curl -X POST 'https://tokenhub-intl.tencentcloudmaas.com/v1/wand/minimax-music/generation' \\
  -H 'Authorization: Bearer YOUR_API_KEY' \\
  -H 'Content-Type: application/json' \\
  -d '{
  "model": "minimax-music-v3.0",
  "prompt": "Soothing piano music, suitable for focused studying, calm and relaxing",
  "is_instrumental": true
}'
4. Output Parameters
Field
Type
Description
data
object
Generated result data object.
data.audio
string
Audio content. When output_format=hex, it is hexadecimal-encoded audio data; when output_format=url, it is an audio download link (valid for 12 hours).
data.status
integer
Generation status: 1 generating / 2 completed.
trace_id
string
ID of the requested task, used for troubleshooting.
extra_info
object
Audio information object.
extra_info.music_duration
integer
Audio duration (milliseconds).
extra_info.music_sample_rate
integer
Sample rate (Hz).
extra_info.music_channel
integer
Number of channels.
extra_info.bitrate
integer
Bitrate (bps).
extra_info.music_size
integer
Audio file size (bytes).
base_resp
object
Status code object.
base_resp.status_code
integer
Status code; 0 indicates success.
base_resp.status_msg
string
Status description.
usage
object
Usage consumption.
usage.total_tokens
integer
Number of tokens consumed by this task.
request_id
string
Unique request identifier, used for troubleshooting.
5. Response Example
{
	"data": {
		"audio": "hex-encoded audio data or URL",
		"status": 2
	},
	"trace_id": "4-WandAudio-37d8fc5946e6419380fa5627fe6ae5ff",
	"extra_info": {
		"music_duration": 25364,
		"music_sample_rate": 44100,
		"music_channel": 2,
		"bitrate": 256000,
		"music_size": 813651
	},
	"base_resp": {
		"status_code": 0,
		"status_msg": "success"
	},
	"usage": {
		"total_tokens": 100000
	},
	"request_id": "3aec3299-06ad-4654-8b45-c57b823a15d2"
}
Note:
When output_format=hex (default), data.audio is a hex-encoded string. Decode it as hex and write it to an audio file (such as output.mp3) for playback. When output_format=url, data.audio directly returns a download link.
6. Error Codes
A request fails when the HTTP status code is not 200, or when base_resp.status_code in the response body is not 0. For the specific reason, see base_resp.status_msg. Common failure scenarios:
Failure Scenario
Handling Recommendation
Authentication Failure
Check whether the API Key is correct and whether the TokenHub service is enabled.
Missing Required Parameter
Check the parameter combination: For songs with vocals, lyrics is required (or enable lyrics_optimizer); for instrumental music, prompt is required.
Content Moderation Failed
Check whether prompt / lyrics contain prohibited content, modify them, and retry.
Rate Limit Triggered
Retry after reducing the request frequency.
Server-Side Generation Failed
Retry. If the failure persists, contact technical support and provide the trace_id.
FAQs
1. Can a song be generated by passing only prompt without lyrics?
Yes, but you must set lyrics_optimizer: true, and the system will automatically generate lyrics based on the prompt. If lyrics_optimizer is false and lyrics is not passed, requests to generate songs with vocals will fail, except in instrumental scenarios (when is_instrumental: true, no lyrics are required).
2. How to choose between the hex and url return formats?
To directly obtain a downloadable/playable link, use url. Note that the link expires after 12 hours, so download and save it promptly.
3. Are tags like [Verse] and [Chorus] in the lyrics mandatory?
It is not required, but recommended. Structure tags (such as [Intro], [Verse], and [Chorus]) can significantly improve the structural integrity and listening experience of a song. Tags are not counted as lyrics characters.
4. What information should be provided when generation failures are troubleshot?
Provide the trace_id from the response. It is the task id of the request and can be used to locate specific issues in the generation pipeline.
﻿
﻿

Bantuan dan Dukungan

Apakah halaman ini membantu?

Anda juga dapat Menghubungi Penjualan atau Mengirimkan Tiket untuk meminta bantuan.

masukan

tencent cloud

LLM Service TokenHub

MiniMax Music Generation API Guide

Overview

Call Method

Prerequisites

Model list

Music Generation

1. API Description

2. Input Parameters

3. Request Example

4. Output Parameters

5. Response Example

6. Error Codes

FAQs

1. Can a song be generated by passing only prompt without lyrics?

2. How to choose between the hex and url return formats?

3. Are tags like [Verse] and [Chorus] in the lyrics mandatory?

4. What information should be provided when generation failures are troubleshot?

Bantuan dan Dukungan

Model Name	model ID	Supported Capability	Lyrics Limit	Prompt Limit	Selection Recommendations
MiniMax-Music-v3.0	minimax-music-v3.0	Song generation (vocals) / Instrumental music / Automatic lyric writing	3500 characters	2000 characters	Overall sound quality is significantly improved, and vocal synthesis is more natural.

Parameter Name	Required	Type	Description
model	Yes	string	Model version. Value: `minimax-music-v3.0`
prompt	Conditionally required	string	Music description used to specify the style, mood, and scene, such as "Pop, melancholic, perfect for a rainy night". Length limit: [0, 2000] characters. Required when instrumental music is generated (`is_instrumental: true`), with a length limit of [1, 2000] characters.
lyrics	Conditionally required	string	Song lyrics, with each line separated by `\\n`. Supported structure tags: `[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`. Required when songs with vocals are generated, with a length limit of [1, 3500] characters; optional for instrumental music.
lyrics_optimizer	No	boolean	Whether to automatically generate lyrics based on the `prompt` description. When set to `true` and `lyrics` is empty, the system automatically writes lyrics based on the prompt. Default value: false.
is_instrumental	No	boolean	Whether to generate instrumental music (without vocals). When set to `true`, `lyrics` is optional. Default value: false.
output_format	No	string	Audio return format. Optional values: `hex` (hexadecimal encoding, default) / `url` (download link, valid for 12 hours).
audio_setting	No	object	Audio output configuration. See the table below for subfields.
aigc_watermark	No	boolean	Whether to add a watermark at the end of the audio. Default value: false.

Field	Type	Description
data	object	Generated result data object.
data.audio	string	Audio content. When `output_format=hex`, it is hexadecimal-encoded audio data; when `output_format=url`, it is an audio download link (valid for 12 hours).
data.status	integer	Generation status: 1 generating / 2 completed.
trace_id	string	ID of the requested task, used for troubleshooting.
extra_info	object	Audio information object.
extra_info.music_duration	integer	Audio duration (milliseconds).
extra_info.music_sample_rate	integer	Sample rate (Hz).
extra_info.music_channel	integer	Number of channels.
extra_info.bitrate	integer	Bitrate (bps).
extra_info.music_size	integer	Audio file size (bytes).
base_resp	object	Status code object.
base_resp.status_code	integer	Status code; 0 indicates success.
base_resp.status_msg	string	Status description.
usage	object	Usage consumption.
usage.total_tokens	integer	Number of tokens consumed by this task.
request_id	string	Unique request identifier, used for troubleshooting.

Failure Scenario	Handling Recommendation
Authentication Failure	Check whether the API Key is correct and whether the TokenHub service is enabled.
Missing Required Parameter	Check the parameter combination: For songs with vocals, `lyrics` is required (or enable `lyrics_optimizer`); for instrumental music, `prompt` is required.
Content Moderation Failed	Check whether prompt / lyrics contain prohibited content, modify them, and retry.
Rate Limit Triggered	Retry after reducing the request frequency.
Server-Side Generation Failed	Retry. If the failure persists, contact technical support and provide the `trace_id`.