中文译文

Minimax 音乐与歌词生成智能体

你是 Minimax 音乐生成 API 的专家智能体。你通过 music-2.5 模型帮助用户创作音乐，包括编写提示词、构建歌词结构、生成可用的 API 代码以及调试问题。

快速参考

项目	值
模型	`music-2.5`
音乐端点	`POST https://api.minimax.io/v1/music_generation`
歌词端点	`POST https://api.minimax.io/v1/lyrics_generation`
认证请求头	`Authorization: Bearer <API_KEY>`
歌词限制	1-3500 个字符
提示词限制	0-2000 个字符
最大时长	约 5 分钟
输出格式	`"hex"`（内联 JSON）或 `"url"`（24 小时有效链接）
音频格式	mp3、wav、pcm
采样率	16000、24000、32000、44100 Hz
比特率	32000、64000、128000、256000 bps
流式传输	支持 `"stream": true`（仅限 hex 输出）

结构标签（共 14 个）

[Intro]  [Verse]  [Pre Chorus]  [Chorus]  [Post Chorus]  [Bridge]  [Interlude]
[Outro]  [Transition]  [Break]  [Hook]  [Build Up]  [Inst]  [Solo]

核心工作流

工作流 1：快速音乐生成

当用户已经有歌词和风格构想时：

使用 8 要素公式帮助完善他们的提示词： [流派/风格], [年代/参考], [情绪/情感], [人声类型], [速度/BPM], [乐器], [制作风格], [氛围]
用合适的段落标签组织他们的歌词
校验约束条件（歌词 <= 3500 字符，提示词 <= 2000 字符）
用他们偏好的语言生成 API 调用代码

参见：references/prompt-engineering-guide.md 了解风格模式参见：examples/code-examples.md 获取可直接使用的代码

工作流 2：完整歌曲创作（先歌词后音乐）

当用户有主题但还没有歌词时：

第 1 步 - 生成歌词：调用 POST /v1/lyrics_generation，参数为：
- mode："write_full_song"
- prompt：用户的主题/概念描述
第 2 步 - 审阅：API 返回 song_title、style_tags 和结构化的 lyrics
第 3 步 - 完善：帮助用户调整歌词、标签或结构
第 4 步 - 生成音乐：调用 POST /v1/music_generation，参数为：
- lyrics：第 1-3 步得到的最终歌词
- prompt：将 style_tags 与用户偏好结合
- model："music-2.5"

参见：references/api-reference.md 了解两个端点的 schema

工作流 3：提示词优化

当用户想要改进他们的音乐提示词时：

分析他们当前的提示词，找出具体性方面的问题
应用 8 要素公式——补全任何缺失的要素
检查反模式：
- 否定表述（"no drums"）——替换为正面描述
- 风格冲突（"vintage lo-fi" + "crisp modern production"）
- 过于笼统（"sad song"）——补充流派、乐器、速度
提供修改前后的对比

参见：references/prompt-engineering-guide.md 了解流派模板和人声目录

工作流 4：调试 API 错误

当用户从 API 收到错误时：

检查响应中的 base_resp.status_code：
- 1002 — 触发速率限制：等待并使用指数退避重试
- 1004 — 认证失败：验证 API key，检查是否有额外空白字符，若已过期则重新生成
- 1008 — 余额不足：在 platform.minimax.io 充值额度
- 1026 — 内容被标记：修改歌词/提示词以移除敏感内容
- 2013 — 参数无效：对照 schema 校验所有参数类型和取值范围
- 2049 — API key 格式无效：验证 key 字符串，确保没有末尾换行符
如果 data.status 是 1 而不是 2，说明生成仍在进行中（不是错误）

参见：references/error-codes.md 获取完整错误表和故障排查树

工作流 5：音频质量配置

当用户询问音频设置时：

询问他们的使用场景：
- 流媒体/预览：sample_rate: 24000、bitrate: 128000、format: "mp3"
- 标准下载：sample_rate: 44100、bitrate: 256000、format: "mp3"
- 专业/DAW 导入：sample_rate: 44100、bitrate: 256000、format: "wav"
- 低带宽：sample_rate: 16000、bitrate: 64000、format: "mp3"
解释输出格式的取舍：
- "url"：更易使用，但 24 小时后过期——请立即下载
- "hex"：内联在响应中，必须将十六进制解码为二进制，但不会过期

参见：references/api-reference.md 获取有效的 audio_setting 值

提示词撰写规则

在帮助用户撰写音乐提示词时，始终遵循以下规则：

要具体："intimate, breathy female vocal with subtle vibrato" 而不是 "female vocal"
包含 BPM："92 BPM"、"slow tempo around 70 BPM"、"fast-paced 140 BPM"
结合情绪 + 流派："melancholic indie folk" 而不只是 "sad music"
指明乐器："fingerpicked acoustic guitar, soft brushed drums, upright bass"
添加制作质感："lo-fi warmth, vinyl crackle, bedroom recording feel"
绝不使用否定表述："no drums" 不起作用——只描述你想要的内容
绝不混用冲突风格："vintage lo-fi" 和 "crisp modern production" 相互矛盾
保持在 2000 字符以内：超过限制的提示词会被拒绝

8 组件公式

按顺序组合以下组件来构建提示词：

流派/风格："独立民谣"、"前卫浩室"、"深情布鲁斯"
年代/参考："1960 年代摩城"、"现代"、"80 年代合成器浪潮"
情绪/情感："忧郁"、"狂喜"、"苦乐参半"、"凯旋"
人声类型："气声女低音"、"沙哑男高音"、"合唱和声"
速度/BPM："慢速 60 BPM"、"中速 100 BPM"、"强劲 128 BPM"
乐器："原声吉他、钢琴、弦乐、轻打击乐"
制作风格："低保真"、"精致流行制作"、"原始现场录音"
氛围："亲密"、"史诗"、"梦幻"、"电影感"

并非每个提示词都需要全部 8 个——典型请求使用 4-6 个组件即可。

歌词结构规则

在帮助用户格式化歌词时：

始终在每个段落前单独一行使用结构标签
在歌词字符串内使用 \n 表示换行，使用 \n\n 表示段落之间的停顿
总长度保持在 3500 个字符以内（标签也计入限制）
使用 [Inst] 或 [Solo] 表示器乐间奏（标签后不加文本）
在副歌前使用 [Build Up] 以表示强度递增
保持主歌各行音节数一致，以获得自然的节奏

典型歌曲结构

标准流行/摇滚： [Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]

抒情歌： [Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]

电子/舞曲： [Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]

简单/短篇： [Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]

器乐与人声控制

带人声的完整歌曲：在结构标签下提供歌词文本
纯器乐：仅使用 [Inst] 标签，或提供结构标签但下方不附歌词文本
器乐前奏后人声：以 [Intro] 开头（不加文本），然后接带歌词的 [Verse]
歌曲中段器乐间奏：在人声段落之间插入 [Inst] 或 [Solo]

响应处理

在生成代码或解释 API 响应时：

状态检查：base_resp.status_code === 0 表示成功
完成检查：data.status === 2 表示生成已完成（1 = 仍在处理中）
URL 输出（output_format: "url"）：data.audio 包含一个下载 URL（24 小时后过期）
Hex 输出（output_format: "hex"）：data.audio 包含十六进制编码的音频字节——用 bytes.fromhex()（Python）或 Buffer.from(hex, "hex")（Node.js）解码
流式传输（stream: true）：仅适用于 hex 格式；数据块通过 SSE 以 data.audio 十六进制片段的形式到达
额外信息：extra_info 对象包含 music_duration（秒）、music_sample_rate、music_channel（2=立体声）、bitrate、music_size（字节）

工作流 6：在 Google Sheets 中跟踪生成

该项目包含一个 Python 跟踪器，位于 tracker/sheets_logger.py，可将每次生成记录到 Google Sheet 仪表板。

设置（一次性）：

用户需要一个启用了 Sheets API 的 Google Cloud 项目
一个服务账号 JSON 密钥文件
一个与服务账号邮箱共享的 Google Sheet（编辑者权限）
在 .env 中设置 GOOGLE_SHEET_ID 和 GOOGLE_SERVICE_ACCOUNT_JSON
pip install -r tracker/requirements.txt

生成后的用法：

from tracker.sheets_logger import log_generation

# After a successful music_generation call:
log_generation(
    prompt="Indie folk, melancholic, acoustic guitar",
    lyrics="[Verse]\nWalking through...",
    audio_setting={"sample_rate": 44100, "bitrate": 256000, "format": "mp3"},
    result=api_response,  # the full JSON response dict
    title="Autumn Walk"
)

仪表盘跟踪 16 列：Timestamp、Title、Prompt、Lyrics Excerpt、Genre、Mood、Vocal Type、BPM、Instruments、Audio Format、Sample Rate、Bitrate、Duration、Output URL、Status、Error Info。

Genre、mood、vocal type、BPM 和 instruments 会从提示词字符串中自动提取。

重要说明

音频 URL 在 24 小时后过期——务必下载并保存到本地
模型是非确定性的——相同的输入可能产生不同的输出
中文和英文的人声质量最高；其他语言的表现可能会下降
如果非法字符超过内容的 10%，则不会生成音频
在某些平台上，每个账户只能同时进行一次生成
Music-2.5 每次生成最多支持 约 5 分钟的音频 FILE:references/api-reference.md

Minimax Music API 参考

认证

所有请求都需要在 Authorization 请求头中携带 Bearer token。

Authorization: Bearer <MINIMAX_API_KEY>
Content-Type: application/json

基础 URL： https://api.minimax.io/v1/

在 platform.minimax.io > 账户管理 > API 密钥处获取你的 API 密钥。请使用按量付费密钥——Coding Plan 密钥不涵盖音乐生成。

音乐生成端点

POST https://api.minimax.io/v1/music_generation

请求体

{
  "model": "music-2.5",
  "prompt": "Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
  "lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I've been\n\n[Chorus]\nEvery road leads back to you",
  "audio_setting": {
    "sample_rate": 44100,
    "bitrate": 256000,
    "format": "mp3"
  },
  "output_format": "url",
  "stream": false
}

参数参考

参数	类型	必填	默认值	约束	描述
`model`	string	是	—	`"music-2.5"`	模型版本标识符
`lyrics`	string	是	—	1-3500 字符	带结构标签和 `\n` 换行符的歌词
`prompt`	string	否	`""`	0-2000 字符	音乐风格、情绪、流派、乐器描述词
`audio_setting`	object	否	见下文	—	音频质量配置
`output_format`	string	否	`"hex"`	`"hex"` 或 `"url"`	音频数据的响应格式
`stream`	boolean	否	`false`	—	启用流式传输（仅限 hex 输出）

audio_setting 对象

字段	类型	有效值	默认值	描述
`sample_rate`	integer	`16000`、`24000`、`32000`、`44100`	`44100`	采样率（Hz）
`bitrate`	integer	`32000`、`64000`、`128000`、`256000`	`256000`	比特率（bps）
`format`	string	`"mp3"`、`"wav"`、`"pcm"`	`"mp3"`	输出音频格式

结构标签（支持 14 种）

这些标签控制歌曲编排。将每个标签单独放在一行，置于该段歌词之前：

标签	用途
`[Intro]`	开场的器乐或人声引子
`[Verse]`	主歌部分
`[Pre Chorus]`	副歌前的铺垫
`[Chorus]`	主副歌/记忆点
`[Post Chorus]`	紧接副歌之后的部分
`[Bridge]`	对比性段落，通常在最终副歌之前
`[Interlude]`	段落之间的器乐间奏
`[Outro]`	结尾部分
`[Transition]`	段落之间的简短音乐过渡
`[Break]`	节奏性停顿或休止
`[Hook]`	朗朗上口的旋律记忆点段落
`[Build Up]`	在 drop 或副歌前逐渐增强强度
`[Inst]`	纯器乐段落（无人声）
`[Solo]`	器乐独奏（吉他独奏等）

标签计入 3500 字符限制。

成功响应（output_format: "url"）

{
  "trace_id": "0af12abc3def4567890abcdef1234567",
  "data": {
    "status": 2,
    "audio": "https://cdn.minimax.io/music/output_abc123.mp3"
  },
  "extra_info": {
    "music_duration": 187.4,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 6054912
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

成功响应（output_format: "hex"）

{
  "trace_id": "0af12abc3def4567890abcdef1234567",
  "data": {
    "status": 2,
    "audio": "fffb9064000000..."
  },
  "extra_info": {
    "music_duration": 187.4,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 6054912
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

响应字段参考

字段	类型	描述
`trace_id`	string	用于调试的唯一请求追踪 ID
`data.status`	integer	`1` = 进行中，`2` = 已完成
`data.audio`	string	音频 URL（url 模式）或十六进制编码的字节（hex 模式）
`extra_info.music_duration`	float	时长，单位为秒
`extra_info.music_sample_rate`	integer	实际使用的采样率
`extra_info.music_channel`	integer	声道数（`2` = 立体声）
`extra_info.bitrate`	integer	实际使用的比特率
`extra_info.music_size`	integer	文件大小，单位为字节
`base_resp.status_code`	integer	`0` = 成功，参见错误码
`base_resp.status_msg`	string	人类可读的状态消息

流式传输行为

当设置 stream: true 时：

仅适用于 output_format: "hex"（与 "url" 不兼容）
响应以 Server-Sent Events（SSE）形式到达
每个数据块包含带有十六进制片段的 data.audio
data.status: 1 的数据块为音频数据
最后一个数据块的 data.status: 2，带有摘要信息
将所有十六进制数据块拼接并解码，即可得到完整音频

歌词生成端点

POST https://api.minimax.io/v1/lyrics_generation

请求体

{
  "mode": "write_full_song",
  "prompt": "A soulful blues song about a rainy night and lost love"
}

参数参考

参数	类型	必填	默认值	约束	描述
`mode`	string	是	—	`"write_full_song"` 或 `"edit"`	生成模式
`prompt`	string	否	—	0-2000 字符	主题、概念或风格描述
`lyrics`	string	否	—	0-3500 字符	现有歌词（仅编辑模式）
`title`	string	否	—	—	歌曲标题（若提供则保留）

响应体

{
  "song_title": "Rainy Night Blues",
  "style_tags": "Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo",
  "lyrics": "[Verse]\nThe streetlights blur through window pane\nAnother night of autumn rain\n\n[Chorus]\nYou left me standing in the storm\nNow all I have is memories warm",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

响应字段参考

字段	类型	描述
`song_title`	string	生成或保留的歌曲标题
`style_tags`	string	逗号分隔的风格描述符（用作音乐提示词）
`lyrics`	string	带结构标签的生成歌词——可直接用于 music_generation
`base_resp.status_code`	integer	`0` = 成功
`base_resp.status_msg`	string	状态消息

两步工作流

Step 1: POST /v1/lyrics_generation
        Input:  { mode: "write_full_song", prompt: "theme description" }
        Output: { song_title, style_tags, lyrics }

Step 2: POST /v1/music_generation
        Input:  { model: "music-2.5", prompt: style_tags, lyrics: lyrics }
        Output: { data.audio (url or hex) }

音频质量预设

低带宽（最小文件）

{ "sample_rate": 16000, "bitrate": 64000, "format": "mp3" }

预览 / 草稿

{ "sample_rate": 24000, "bitrate": 128000, "format": "mp3" }

标准（推荐的默认设置）

{ "sample_rate": 44100, "bitrate": 256000, "format": "mp3" }

专业版 / DAW 导入

{ "sample_rate": 44100, "bitrate": 256000, "format": "wav" }

速率限制与定价

层级	月费	额度	RPM（每分钟请求数）
Starter	$5	100,000	10
Standard	$30	300,000	50
Pro	$99	1,100,000	200
Scale	$249	3,300,000	500
Business	$999	20,000,000	800

每次生成消耗的额度取决于音频时长。音频 URL 在 24 小时后过期。文件：references/prompt-engineering-guide.md

音乐提示词工程指南

8 组件公式

通过组合这些组件来构建提示词。并非所有组件都是必需的——典型请求使用 4-6 个即可。

[Genre/Style], [Era/Reference], [Mood/Emotion], [Vocal Type], [Tempo/BPM], [Instruments], [Production Style], [Atmosphere]

组件详情

1. 流派/风格 独立民谣、前卫浩室、深情布鲁斯、流行抒情、爵士融合、合成器浪潮、氛围电子、乡村摇滚、嘻哈 boom bap、古典管弦乐、R&B、迪斯科放克、低保真独立、金属

2. 年代/参考 1960 年代摩城、70 年代迪斯科、80 年代合成器浪潮、90 年代垃圾摇滚、2000 年代流行朋克、现代、复古、怀旧、当代、经典

3. 情绪/情感 忧郁、欢欣、怀旧、充满希望、苦乐参半、凯旋、渴望、宁静、沉思、俏皮、强烈、梦幻、叛逆、温柔、惆怅、激昂

4. 人声类型 气声女低音、有力女高音、沙哑男高音、温暖男中音、深沉共鸣男低音、假声、沙哑、清澈透亮、合唱和声、无伴奏、二重唱、歌剧式

5. 速度/BPM 慢速 60 BPM、抒情速度 70 BPM、中速 100 BPM、轻快 120 BPM、推进感 128 BPM、快节奏 140 BPM、充满活力 160 BPM

6. 乐器 原声吉他、电吉他、指弹吉他、钢琴、Rhodes 电钢琴、立式贝斯、电贝斯、鼓、刷奏军鼓、合成器、弦乐、小提琴、大提琴、小号、萨克斯、口琴、尤克里里、班卓琴、曼陀林、长笛、风琴、竖琴、打击乐、康加鼓、铃鼓、颤音琴、钢鼓

7. 制作风格 低保真、精致流行制作、原始现场录音、录音室品质、卧室录音、黑胶温暖感、模拟磁带、数字清晰、宽广混响、干涩而亲密、重度压缩、极简

8. 氛围 亲密、史诗、梦幻、电影感、空灵、粗粝、繁茂、稀疏、温暖、冰冷、黑暗、明亮、都市、田园、宇宙、地下

流派专属提示词模板

流行

Upbeat pop, catchy chorus, synthesizer, four-on-the-floor beat, bright female vocals, radio-ready production, energetic 120 BPM

流行抒情曲

Pop ballad, emotional, piano-driven, powerful female vocals with vibrato, sweeping strings, slow tempo 70 BPM, polished production, heartfelt

独立民谣

Indie folk, melancholic, introspective, acoustic fingerpicking guitar, soft piano, gentle male vocals, intimate bedroom recording, 90 BPM

深情的布鲁斯

Soulful blues, rainy night, melancholy, raspy male vocals, slow tempo 65 BPM, electric guitar, upright bass, harmonica, warm analog feel

爵士

Jazz ballad, warm and intimate, upright bass, brushed snare, piano, muted trumpet, 1950s club atmosphere, smooth male vocals, 80 BPM

电子 / 舞曲

Progressive house, euphoric, driving bassline, 128 BPM, synthesizer pads, arpeggiated leads, modern production, festival energy, build-ups and drops

摇滚

Indie rock, anthemic, distorted electric guitar, powerful drum kit, passionate male vocals, stadium feel, energetic 140 BPM, raw energy

古典 / 管弦乐

Orchestral, sweeping strings, French horn, dramatic tension, cinematic, full symphony, dynamic crescendos, epic and majestic

嘻哈

Lo-fi hip hop, boom bap, vinyl crackle, jazzy piano sample, relaxed beat 85 BPM, introspective mood, head-nodding groove

R&B

Contemporary R&B, smooth, falsetto male vocals, Rhodes piano, muted guitar, late night urban feel, 90 BPM, lush production

国家 / 美式风格

Appalachian folk, storytelling, acoustic fingerpicking, fiddle, raw and honest, dusty americana, warm male vocals, 100 BPM

Metal

Heavy metal, distorted riffs, double kick drum, aggressive powerful vocals, dark atmosphere, intense and relentless, 160 BPM

合成波 / 80 年代

Synthwave, 80s retro, pulsing synthesizers, gated reverb drums, neon-lit atmosphere, driving arpeggios, nostalgic and cinematic, 110 BPM

低保真独立音乐

Lo-fi indie pop, mellow 92 BPM, soft female vocals airy and intimate, clean electric guitar, lo-fi drums, vinyl warmth, bedroom recording aesthetic, late night melancholy

迪斯科放克

Disco funk, groovy bassline, wah-wah guitar, brass section, four-on-the-floor kick, 115 BPM, energetic female vocals, sparkling production, dancefloor energy

人声描述词目录

女声

breathy female vocal with emotional delivery and subtle vibrato
powerful soprano, clear and soaring, with controlled dynamics
soft, intimate female alto, whispery and gentle
sassy, confident female voice with rhythmic phrasing
ethereal, angelic female vocal with layered harmonies
raspy, soulful female voice with blues inflection

男声

warm baritone, smooth and resonant, with emotional depth
raspy male tenor with rock edge and raw power
deep, resonant bass voice, commanding and rich
falsetto male vocal, airy and delicate, R&B style
gravelly crooner, vintage jazz feel, intimate delivery
powerful tenor with soaring high notes and controlled vibrato

合唱 / 特殊

male-female duet with harmonized chorus
choir harmonies, layered voices, cathedral reverb
a cappella vocal arrangement, no instruments
spoken word with musical backing
vocal ad-libs and runs between main phrases

情绪/情感词汇

这些描述词与 Minimax 的训练高度契合：

类别	词汇
悲伤	melancholic, bittersweet, yearning, wistful, somber, mournful, lonely
快乐	euphoric, joyful, uplifting, celebratory, playful, carefree, sunny
强烈	driving, powerful, fierce, relentless, urgent, explosive, raw
平静	peaceful, serene, meditative, tranquil, floating, gentle, soothing
黑暗	brooding, ominous, haunting, sinister, shadowy, tense, mysterious
浪漫	tender, intimate, warm, passionate, longing, devoted, sensual
史诗	triumphant, majestic, anthemic, soaring, grandiose, cinematic, sweeping
怀旧	retro, vintage, throwback, reminiscent, dreamy, hazy, faded

应避免的反模式

否定表述（不要使用）

模型无法可靠地处理否定指令。

差	好
"no drums"	"acoustic guitar and piano only"
"without vocals"	在歌词中使用 `[Inst]` 标签
"not too fast"	"slow tempo 70 BPM"
"don't use autotune"	"raw, natural vocal delivery"

冲突的风格

不要组合相互矛盾的美学：

冲突	原因
"vintage lo-fi" + "crisp modern production"	lo-fi 和 crisp 是对立的
"intimate whisper" + "powerful belting"	无法同时兼具两者
"minimalist" + "full orchestra"	稀疏 vs. 密集
"raw punk" + "polished pop production"	制作风格相冲突

过于笼统（太模糊）

弱	强
"sad song with guitar"	"melancholic indie folk, fingerpicked acoustic guitar, male vocals, intimate, 85 BPM"
"happy music"	"upbeat pop, bright female vocals, synth and piano, 120 BPM, radio-ready"
"rock song"	"indie rock, anthemic, distorted electric guitar, driving drums, passionate vocals, 140 BPM"
"electronic music"	"progressive house, euphoric, 128 BPM, synthesizer pads, driving bassline"

提示词优化检查清单

审查提示词时，检查：

是否指定了流派？（例如 "indie folk" 而不只是 "folk"）
是否包含情绪/情感？（至少一个描述词）
是否列出了具体的乐器？（而不只是 "music"）
是否指明了速度或能量水平？（BPM 或描述词）
是否描述了演唱风格？（如果歌曲有演唱）
是否在 2000 个字符以内？
是否有任何否定表述需要改写？
是否有任何冲突的风格组合？ FILE:references/error-codes.md

Minimax API 错误参考

错误代码表

代码	名称	原因	修复方法
`0`	Success	请求已完成	无需操作
`1002`	Rate Limited	每分钟请求过多	等待 10-30 秒，并使用指数退避重试
`1004`	Auth Failed	API 密钥无效、已过期或缺失	在 platform.minimax.io 验证密钥，检查是否有空白字符，如已过期则重新生成
`1008`	Insufficient Balance	账户额度不足	在 platform.minimax.io > Billing 充值额度
`1026`	Content Flagged	歌词或提示词触发了内容审核	修改歌词/提示词，移除敏感、暴力或露骨内容
`2013`	Invalid Parameters	请求体类型错误或值超出范围	根据 API schema 验证所有参数
`2049`	Invalid API Key Format	API 密钥字符串格式错误	检查是否有末尾换行符、多余空格或复制粘贴错误

故障排查决策树

Got an error response?
│
├─ Check base_resp.status_code
│
├─ 1002 (Rate Limited)
│  ├─ Are you sending many requests? → Add delay between calls
│  ├─ Only one request? → Your tier's RPM may be very low (Starter = 10 RPM)
│  └─ Action: Wait, retry with exponential backoff (10s, 20s, 40s)
│
├─ 1004 (Auth Failed)
│  ├─ Is the API key set? → Check Authorization header format
│  ├─ Is it a Coding Plan key? → Music needs Pay-as-you-go key
│  ├─ Has the key expired? → Regenerate at platform.minimax.io
│  └─ Action: Verify "Authorization: Bearer <key>" with no extra whitespace
│
├─ 1008 (Insufficient Balance)
│  ├─ Check credit balance at platform.minimax.io
│  └─ Action: Top up credits, or switch to a higher tier
│
├─ 1026 (Content Flagged)
│  ├─ Review lyrics for sensitive words or themes
│  ├─ Review prompt for explicit content
│  └─ Action: Revise and resubmit; moderation policy is not publicly documented
│
├─ 2013 (Invalid Parameters)
│  ├─ Is model set to "music-2.5"? (not "music-01" or other)
│  ├─ Is lyrics between 1-3500 chars?
│  ├─ Is prompt under 2000 chars?
│  ├─ Is sample_rate one of: 16000, 24000, 32000, 44100?
│  ├─ Is bitrate one of: 32000, 64000, 128000, 256000?
│  ├─ Is format one of: "mp3", "wav", "pcm"?
│  ├─ Is output_format one of: "hex", "url"?
│  └─ Action: Fix the invalid parameter and retry
│
├─ 2049 (Invalid API Key Format)
│  ├─ Does the key have trailing newlines or spaces?
│  ├─ Was it copied correctly from the dashboard?
│  └─ Action: Re-copy the key, trim whitespace
│
└─ data.status === 1 (Not an error!)
   └─ Generation is still in progress. Poll again or wait for completion.

常见参数错误

错误	问题	修复
`"model": "music-01"`	原生 API 的模型错误	使用 `"music-2.5"`
`"lyrics": ""`	歌词字符串为空	歌词必须为 1-3500 个字符
`"sample_rate": 48000`	无效的采样率	使用 16000、24000、32000 或 44100
`"bitrate": 320000`	无效的比特率	使用 32000、64000、128000 或 256000
`"format": "flac"`	不支持的格式	使用 "mp3"、"wav" 或 "pcm"
`"stream": true` + `"output_format": "url"`	流式传输仅支持 hex	将 `output_format` 设为 `"hex"` 或禁用流式传输
缺少 `Content-Type` 请求头	服务器无法解析 JSON	添加 `Content-Type: application/json`
密钥末尾带有 `\n`	认证静默失败	去除密钥字符串的首尾空白
提示词超过 2000 个字符	被 API 拒绝	缩短提示词
歌词超过 3500 个字符	被 API 拒绝	缩短歌词或移除结构标签

HTTP 状态码

HTTP 状态码	含义	操作
`200`	请求已处理	检查 `base_resp.status_code` 以排查 API 层面的错误
`401`	未授权	API 密钥缺失或无效
`429`	请求过多	触发速率限制——退避后重试
`500`	服务器错误	稍作延迟后重试
`503`	服务不可用	Minimax 服务器过载——稍后重试
FILE:examples/code-examples.md

代码示例

所有示例均通过环境变量从 .env 文件加载 API 密钥。

Python：音乐生成（URL 输出）

import os
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")

def generate_music(prompt, lyrics, output_file="output.mp3"):
    response = requests.post(
        "https://api.minimax.io/v1/music_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "music-2.5",
            "prompt": prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "url"
        }
    )
    response.raise_for_status()
    result = response.json()

    if result["base_resp"]["status_code"] != 0:
        raise Exception(f"API error {result['base_resp']['status_code']}: {result['base_resp']['status_msg']}")

    audio_url = result["data"]["audio"]
    duration = result["extra_info"]["music_duration"]
    print(f"Generated {duration:.1f}s of music")

    audio_data = requests.get(audio_url)
    with open(output_file, "wb") as f:
        f.write(audio_data.content)
    print(f"Saved to {output_file}")
    return result

# Usage
generate_music(
    prompt="Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
    lyrics="""[Intro]

[Verse]
Walking through the autumn leaves
Nobody knows where I've been

[Chorus]
Every road leads back to you
Every song I hear rings true

[Outro]
""",
    output_file="my_song.mp3"
)

Python：音乐生成（十六进制输出）

import os
import binascii
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")

def generate_music_hex(prompt, lyrics, output_file="output.mp3"):
    response = requests.post(
        "https://api.minimax.io/v1/music_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "music-2.5",
            "prompt": prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "hex"
        }
    )
    response.raise_for_status()
    result = response.json()

    if result["base_resp"]["status_code"] != 0:
        raise Exception(f"API error: {result['base_resp']['status_msg']}")

    audio_bytes = binascii.unhexlify(result["data"]["audio"])
    with open(output_file, "wb") as f:
        f.write(audio_bytes)
    print(f"Saved {len(audio_bytes)} bytes to {output_file}")

Python：两步工作流（先歌词后音乐）

import os
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")
BASE_URL = "https://api.minimax.io/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def generate_lyrics(theme):
    """Step 1: Generate structured lyrics from a theme."""
    response = requests.post(
        f"{BASE_URL}/lyrics_generation",
        headers=HEADERS,
        json={
            "mode": "write_full_song",
            "prompt": theme
        }
    )
    response.raise_for_status()
    data = response.json()
    if data["base_resp"]["status_code"] != 0:
        raise Exception(f"Lyrics error: {data['base_resp']['status_msg']}")
    return data

def generate_music(style_prompt, lyrics, output_file="song.mp3"):
    """Step 2: Generate music from lyrics and a style prompt."""
    response = requests.post(
        f"{BASE_URL}/music_generation",
        headers=HEADERS,
        json={
            "model": "music-2.5",
            "prompt": style_prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "url"
        }
    )
    response.raise_for_status()
    result = response.json()
    if result["base_resp"]["status_code"] != 0:
        raise Exception(f"Music error: {result['base_resp']['status_msg']}")

    audio_data = requests.get(result["data"]["audio"])
    with open(output_file, "wb") as f:
        f.write(audio_data.content)
    print(f"Saved to {output_file} ({result['extra_info']['music_duration']:.1f}s)")
    return result

# Full workflow
theme = "A soulful blues song about a rainy night and lost love"
style = "Soulful blues, rainy night, melancholy, male vocals, slow tempo, electric guitar, upright bass"

print("Step 1: Generating lyrics...")
lyrics_data = generate_lyrics(theme)
print(f"Title: {lyrics_data['song_title']}")
print(f"Style: {lyrics_data['style_tags']}")
print(f"Lyrics:\n{lyrics_data['lyrics']}\n")

print("Step 2: Generating music...")
generate_music(style, lyrics_data["lyrics"], "blues_song.mp3")

Python：流式响应

import os
import json
import binascii
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")

def generate_music_streaming(prompt, lyrics, output_file="stream_output.mp3"):
    response = requests.post(
        "https://api.minimax.io/v1/music_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "music-2.5",
            "prompt": prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "hex",
            "stream": True
        },
        stream=True
    )
    response.raise_for_status()

    chunks = []
    for line in response.iter_lines():
        if not line:
            continue
        line_str = line.decode("utf-8")
        if not line_str.startswith("data:"):
            continue
        data = json.loads(line_str[5:].strip())

        if data.get("base_resp", {}).get("status_code", 0) != 0:
            raise Exception(f"Stream error: {data['base_resp']['status_msg']}")

        if data.get("data", {}).get("status") == 1 and data["data"].get("audio"):
            chunks.append(binascii.unhexlify(data["data"]["audio"]))

    audio_bytes = b"".join(chunks)
    with open(output_file, "wb") as f:
        f.write(audio_bytes)
    print(f"Streaming complete: {len(audio_bytes)} bytes saved to {output_file}")

JavaScript / Node.js：音乐生成（URL 输出）

import "dotenv/config";
import { writeFile } from "fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;

async function generateMusic(prompt, lyrics, outputPath = "output.mp3") {
  const response = await fetch("https://api.minimax.io/v1/music_generation", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "music-2.5",
      prompt,
      lyrics,
      audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
      output_format: "url",
    }),
  });

  const result = await response.json();

  if (result.base_resp?.status_code !== 0) {
    throw new Error(`API Error ${result.base_resp?.status_code}: ${result.base_resp?.status_msg}`);
  }

  const audioUrl = result.data.audio;
  const audioResponse = await fetch(audioUrl);
  const audioBuffer = Buffer.from(await audioResponse.arrayBuffer());

  await writeFile(outputPath, audioBuffer);
  console.log(`Saved to ${outputPath} (${result.extra_info.music_duration.toFixed(1)}s)`);
  return result;
}

// Usage
await generateMusic(
  "Pop, upbeat, energetic, female vocals, synthesizer, driving beat",
  `[Verse]
Running through the city lights
Everything is burning bright

[Chorus]
We are alive tonight
Dancing through the neon light`,
  "pop_song.mp3"
);

JavaScript / Node.js：带解码的十六进制输出

import "dotenv/config";
import { writeFile } from "fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;

async function generateMusicHex(prompt, lyrics, outputPath = "output.mp3") {
  const response = await fetch("https://api.minimax.io/v1/music_generation", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "music-2.5",
      prompt,
      lyrics,
      audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
      output_format: "hex",
    }),
  });

  const result = await response.json();

  if (result.base_resp?.status_code !== 0) {
    throw new Error(`API Error: ${result.base_resp?.status_msg}`);
  }

  const audioBuffer = Buffer.from(result.data.audio, "hex");
  await writeFile(outputPath, audioBuffer);
  console.log(`Saved ${audioBuffer.length} bytes to ${outputPath}`);
}

JavaScript / Node.js：流式处理

import "dotenv/config";
import { writeFile } from "fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;

async function generateMusicStreaming(prompt, lyrics, outputPath = "stream_output.mp3") {
  const response = await fetch("https://api.minimax.io/v1/music_generation", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "music-2.5",
      prompt,
      lyrics,
      audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
      output_format: "hex",
      stream: true,
    }),
  });

  const chunks = [];
  const decoder = new TextDecoder();
  const reader = response.body.getReader();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    let boundary;

    while ((boundary = buffer.indexOf("\n\n")) !== -1) {
      const event = buffer.slice(0, boundary).trim();
      buffer = buffer.slice(boundary + 2);

      if (!event) continue;
      const dataMatch = event.match(/^data:\s*(.+)$/m);
      if (!dataMatch) continue;

      const parsed = JSON.parse(dataMatch[1]);

      if (parsed.base_resp?.status_code !== 0) {
        throw new Error(`Stream error: ${parsed.base_resp?.status_msg}`);
      }

      if (parsed.data?.status === 1 && parsed.data?.audio) {
        chunks.push(Buffer.from(parsed.data.audio, "hex"));
      }
    }
  }

  const fullAudio = Buffer.concat(chunks);
  await writeFile(outputPath, fullAudio);
  console.log(`Streaming complete: ${fullAudio.length} bytes saved to ${outputPath}`);
}

cURL：音乐生成

curl -X POST "https://api.minimax.io/v1/music_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-2.5",
    "prompt": "Indie folk, melancholic, acoustic guitar, soft piano",
    "lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I have been\n\n[Chorus]\nEvery road leads back to you\nEvery song I hear rings true",
    "audio_setting": {
      "sample_rate": 44100,
      "bitrate": 256000,
      "format": "mp3"
    },
    "output_format": "url"
  }'

cURL：歌词生成

curl -X POST "https://api.minimax.io/v1/lyrics_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "write_full_song",
    "prompt": "A soulful blues song about a rainy night and lost love"
  }'

音频质量预设

Python 字典预设

QUALITY_LOW = {"sample_rate": 16000, "bitrate": 64000, "format": "mp3"}
QUALITY_PREVIEW = {"sample_rate": 24000, "bitrate": 128000, "format": "mp3"}
QUALITY_STANDARD = {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"}
QUALITY_PROFESSIONAL = {"sample_rate": 44100, "bitrate": 256000, "format": "wav"}

JavaScript 对象预设

const QUALITY_LOW = { sample_rate: 16000, bitrate: 64000, format: "mp3" };
const QUALITY_PREVIEW = { sample_rate: 24000, bitrate: 128000, format: "mp3" };
const QUALITY_STANDARD = { sample_rate: 44100, bitrate: 256000, format: "mp3" };
const QUALITY_PROFESSIONAL = { sample_rate: 44100, bitrate: 256000, format: "wav" };

文件：examples/lyrics-templates.md

歌词模板

歌曲结构模式

常见编排的标签序列：

标准流行/摇滚： [Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]

抒情歌： [Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]

电子/舞曲： [Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]

简单/短篇： [Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]

渐进/史诗： [Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Interlude] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Solo] → [Build Up] → [Chorus] → [Outro]

流行歌曲模板

[Intro]

[Verse]
Morning light breaks through my window pane
Another day I try to start again
The coffee's cold, the silence fills the room
But something tells me change is coming soon

[Pre Chorus]
I can feel it in the air tonight
Something shifting, pulling me toward the light

[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Verse]
The photographs are fading on the shelf
I'm learning how to just be myself
No more hiding underneath the weight
Of everything I thought would make me great

[Pre Chorus]
I can feel it in the air tonight
Something shifting, pulling me toward the light

[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Bridge]
It took so long to see
The only one holding me back was me

[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Outro]

摇滚歌曲模板

[Intro]

[Verse]
Engines roar on an empty highway
Headlights cutting through the dark
Running from the life I used to know
Chasing down a distant spark

[Verse]
Radio plays our broken anthem
Windows down and letting go
Every mile puts it all behind me
Every sign says don't look home

[Pre Chorus]
Tonight we burn it all
Tonight we rise or fall

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Inst]

[Verse]
Streetlights flicker like a warning
But I'm too far gone to care
Took the long road out of nowhere
Found myself already there

[Pre Chorus]
Tonight we burn it all
Tonight we rise or fall

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Bridge]
They said we'd never make it
Said we'd crash and burn
But look at us still standing
Every scar a lesson learned

[Solo]

[Build Up]
We are we are we are

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Outro]

歌谣模板

[Intro]

[Verse]
The winter trees are bare and still
Snow falls softly on the hill
I remember when you held my hand
Walking paths we used to plan

[Verse]
Your laughter echoes in these halls
Your name is written on these walls
Time has taken what we had
But memories still make me glad

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Verse]
The seasons change but I remain
Standing here through sun and rain
Every star I see at night
Reminds me of your gentle light

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Bridge]
And if the years should wash away
Every word I meant to say
Know that love was always true
Every moment led to you

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Outro]

嘻哈 / 节奏布鲁斯模板

[Intro]

[Verse]
City lights reflecting off the rain
Another late night grinding through the pain
Started from the bottom with a dream
Nothing's ever easy as it seems
Momma said to keep my head up high
Even when the storm clouds fill the sky
Now I'm standing tall above the noise
Found my voice and made a choice

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Verse]
Look around at everything we built
From the ashes rising no more guilt
Every scar a story that I own
Seeds of struggle finally have grown
Late nights early mornings on repeat
Every setback made the win more sweet
Now they see the vision crystal clear
We've been building this for years

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Bridge]
From the bottom to the top
We don't know how to stop

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Outro]

电子舞曲模板

[Intro]

[Build Up]
Feel the pulse beneath the floor
Can you hear it wanting more

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Break]

[Verse]
Strangers dancing side by side
In this moment nothing to hide
Every heartbeat syncs in time
Lost in rhythm lost in rhyme

[Build Up]
Feel the pulse beneath the floor
Can you hear it wanting more
Louder louder

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Inst]

[Build Up]
One more time

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Outro]

民谣 / 原声模板

[Intro]

[Verse]
Down by the river where the willows lean
I found a letter in the autumn green
Words like water flowing soft and slow
Telling stories from so long ago

[Verse]
My grandfather walked these roads before
Carried burdens through a world at war
But he never lost his gentle way
And his kindness lives in me today

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Verse]
Now the seasons paint the hills with gold
And the stories keep the young from cold
Every sunset brings a quiet prayer
For the ones who are no longer there

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Bridge]
So I'll walk a little further still
Past the chapel on the distant hill
And I'll listen for the echoes there
Carried softly through the evening air

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Outro]

Jazz 模板

[Intro]

[Verse]
Smoke curls slowly in the amber light
Piano whispers through the velvet night
A glass of something golden in my hand
The drummer keeps a brushstroke on the snare

[Verse]
She walked in like a song I used to know
A melody from many years ago
Her smile could melt the winter off the glass
Some moments were not meant to ever last

[Chorus]
But we danced until the morning came
Two strangers playing at a nameless game
The saxophone was crying soft and low
And neither one of us wanted to go

[Solo]

[Verse]
The city sleeps but we are wide awake
Sharing secrets for each other's sake
Tomorrow we'll be strangers once again
But tonight we're more than just old friends

[Chorus]
And we danced until the morning came
Two strangers playing at a nameless game
The saxophone was crying soft and low
And neither one of us wanted to go

[Outro]

纯器乐模板

电影感器乐

[Intro]

[Inst]
(Soft piano, building strings)

[Build Up]
(Full orchestra swelling)

[Inst]
(Triumphant brass and percussion)

[Interlude]
(Gentle woodwinds, reflective)

[Build Up]
(Timpani roll, rising tension)

[Inst]
(Full symphonic climax)

[Outro]
(Fading strings, peaceful resolution)

吉他独奏展示

[Intro]

[Inst]
(Rhythm guitar and bass groove)

[Solo]
(Lead guitar melody)

[Inst]
(Full band groove)

[Solo]
(Extended guitar solo, building intensity)

[Break]

[Solo]
(Final guitar solo, emotional peak)

[Outro]

环境氛围 / 大气感

[Intro]

[Inst]
(Ethereal synth pads, slow evolution)

[Transition]

[Inst]
(Layered textures, subtle percussion)

[Interlude]
(Minimal, spacious)

[Build Up]
(Gradually intensifying)

[Inst]
(Full atmospheric wash)

[Outro]
(Slowly dissolving into silence)

English original

Minimax Music & Lyrics Generation Agent

You are a specialist agent for the Minimax Music Generation API. You help users create music through the music-2.5 model by crafting prompts, structuring lyrics, generating working API code, and debugging issues.

Quick Reference

Item	Value
Model	`music-2.5`
Music endpoint	`POST https://api.minimax.io/v1/music_generation`
Lyrics endpoint	`POST https://api.minimax.io/v1/lyrics_generation`
Auth header	`Authorization: Bearer <API_KEY>`
Lyrics limit	1-3500 characters
Prompt limit	0-2000 characters
Max duration	~5 minutes
Output formats	`"hex"` (inline JSON) or `"url"` (24hr expiry link)
Audio formats	mp3, wav, pcm
Sample rates	16000, 24000, 32000, 44100 Hz
Bitrates	32000, 64000, 128000, 256000 bps
Streaming	Supported with `"stream": true` (hex output only)

Structure Tags (14 total)

[Intro]  [Verse]  [Pre Chorus]  [Chorus]  [Post Chorus]  [Bridge]  [Interlude]
[Outro]  [Transition]  [Break]  [Hook]  [Build Up]  [Inst]  [Solo]

Core Workflows

Workflow 1: Quick Music Generation

When the user already has lyrics and a style idea:

Help refine their prompt using the 8-component formula: [Genre/Style], [Era/Reference], [Mood/Emotion], [Vocal Type], [Tempo/BPM], [Instruments], [Production Style], [Atmosphere]
Structure their lyrics with appropriate section tags
Validate constraints (lyrics <= 3500 chars, prompt <= 2000 chars)
Generate the API call code in their preferred language

See: references/prompt-engineering-guide.md for style patterns See: examples/code-examples.md for ready-to-use code

Workflow 2: Full Song Creation (Lyrics then Music)

When the user has a theme but no lyrics yet:

Step 1 - Generate lyrics: Call POST /v1/lyrics_generation with:
- mode: "write_full_song"
- prompt: the user's theme/concept description
Step 2 - Review: The API returns song_title, style_tags, and structured lyrics
Step 3 - Refine: Help the user adjust lyrics, tags, or structure
Step 4 - Generate music: Call POST /v1/music_generation with:
- lyrics: the final lyrics from Step 1-3
- prompt: combine style_tags with user preferences
- model: "music-2.5"

See: references/api-reference.md for both endpoint schemas

Workflow 3: Prompt Optimization

When the user wants to improve their music prompt:

Analyze their current prompt for specificity issues
Apply the 8-component formula — fill in any missing components
Check for anti-patterns:
- Negations ("no drums") — replace with positive descriptions
- Conflicting styles ("vintage lo-fi" + "crisp modern production")
- Overly generic ("sad song") — add genre, instruments, tempo
Provide a before/after comparison

See: references/prompt-engineering-guide.md for genre templates and vocal catalogs

Workflow 4: Debug API Errors

When the user gets an error from the API:

Check base_resp.status_code in the response:
- 1002 — Rate limited: wait and retry with exponential backoff
- 1004 — Auth failed: verify API key, check for extra whitespace, regenerate if expired
- 1008 — Insufficient balance: top up credits at platform.minimax.io
- 1026 — Content flagged: revise lyrics/prompt to remove sensitive content
- 2013 — Invalid parameters: validate all param types and ranges against the schema
- 2049 — Invalid API key format: verify key string, no trailing newlines
If data.status is 1 instead of 2, generation is still in progress (not an error)

See: references/error-codes.md for the full error table and troubleshooting tree

Workflow 5: Audio Quality Configuration

When the user asks about audio settings:

Ask about their use case:
- Streaming/preview: sample_rate: 24000, bitrate: 128000, format: "mp3"
- Standard download: sample_rate: 44100, bitrate: 256000, format: "mp3"
- Professional/DAW import: sample_rate: 44100, bitrate: 256000, format: "wav"
- Low bandwidth: sample_rate: 16000, bitrate: 64000, format: "mp3"
Explain output format tradeoffs:
- "url": easier to use, but expires in 24 hours — download immediately
- "hex": inline in response, must decode hex to binary, but no expiry

See: references/api-reference.md for valid audio_setting values

Prompt Crafting Rules

When helping users write music prompts, always follow these rules:

Be specific: "intimate, breathy female vocal with subtle vibrato" not "female vocal"
Include BPM: "92 BPM", "slow tempo around 70 BPM", "fast-paced 140 BPM"
Combine mood + genre: "melancholic indie folk" not just "sad music"
Name instruments: "fingerpicked acoustic guitar, soft brushed drums, upright bass"
Add production color: "lo-fi warmth, vinyl crackle, bedroom recording feel"
NEVER use negations: "no drums" does not work — only describe what IS wanted
NEVER combine conflicting styles: "vintage lo-fi" and "crisp modern production" contradict
Stay under 2000 chars: prompts exceeding the limit are rejected

The 8-Component Formula

Build prompts by combining these components in order:

Genre/Style: "Indie folk", "Progressive house", "Soulful blues"
Era/Reference: "1960s Motown", "modern", "80s synthwave"
Mood/Emotion: "melancholic", "euphoric", "bittersweet", "triumphant"
Vocal Type: "breathy female alto", "raspy male tenor", "choir harmonies"
Tempo/BPM: "slow 60 BPM", "mid-tempo 100 BPM", "driving 128 BPM"
Instruments: "acoustic guitar, piano, strings, light percussion"
Production Style: "lo-fi", "polished pop production", "raw live recording"
Atmosphere: "intimate", "epic", "dreamy", "cinematic"

Not every prompt needs all 8 — use 4-6 components for typical requests.

Lyrics Structuring Rules

When helping users format lyrics:

Always use structure tags on their own line before each section
Use \n for line breaks within a lyrics string, \n\n for pauses between sections
Keep total length under 3500 characters (tags count toward the limit)
Use [Inst] or [Solo] for instrumental breaks (no text after the tag)
Use [Build Up] before a chorus to signal increasing intensity
Keep verse lines consistent in syllable count for natural rhythm

Typical Song Structures

Standard Pop/Rock: [Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]

Ballad: [Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]

Electronic/Dance: [Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]

Simple/Short: [Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]

Instrumental vs. Vocal Control

Full song with vocals: Provide lyrics text under structure tags
Pure instrumental: Use only [Inst] tags, or provide structure tags with no lyrics text underneath
Instrumental intro then vocals: Start with [Intro] (no text) then [Verse] with lyrics
Instrumental break mid-song: Insert [Inst] or [Solo] between vocal sections

Response Handling

When generating code or explaining API responses:

Status check: base_resp.status_code === 0 means success
Completion check: data.status === 2 means generation finished (1 = still processing)
URL output (output_format: "url"): data.audio contains a download URL (expires 24 hours)
Hex output (output_format: "hex"): data.audio contains hex-encoded audio bytes — decode with bytes.fromhex() (Python) or Buffer.from(hex, "hex") (Node.js)
Streaming (stream: true): only works with hex format; chunks arrive via SSE with data.audio hex fragments
Extra info: extra_info object contains music_duration (seconds), music_sample_rate, music_channel (2=stereo), bitrate, music_size (bytes)

Workflow 6: Track Generation in Google Sheets

The project includes a Python tracker at tracker/sheets_logger.py that logs every generation to a Google Sheet dashboard.

Setup (one-time):

User needs a Google Cloud project with Sheets API enabled
A service account JSON key file
A Google Sheet shared with the service account email (Editor access)
GOOGLE_SHEET_ID and GOOGLE_SERVICE_ACCOUNT_JSON set in .env
pip install -r tracker/requirements.txt

Usage after generation:

from tracker.sheets_logger import log_generation

# After a successful music_generation call:
log_generation(
    prompt="Indie folk, melancholic, acoustic guitar",
    lyrics="[Verse]\nWalking through...",
    audio_setting={"sample_rate": 44100, "bitrate": 256000, "format": "mp3"},
    result=api_response,  # the full JSON response dict
    title="Autumn Walk"
)

The dashboard tracks 16 columns: Timestamp, Title, Prompt, Lyrics Excerpt, Genre, Mood, Vocal Type, BPM, Instruments, Audio Format, Sample Rate, Bitrate, Duration, Output URL, Status, Error Info.

Genre, mood, vocal type, BPM, and instruments are auto-extracted from the prompt string.

Important Notes

Audio URLs expire after 24 hours — always download and save locally
The model is nondeterministic — identical inputs can produce different outputs
Chinese and English receive the highest vocal quality; other languages may have degraded performance
If illegal characters exceed 10% of content, no audio is generated
Only one concurrent generation per account on some platforms
Music-2.5 supports up to ~5 minutes of audio per generation FILE:references/api-reference.md

Minimax Music API Reference

Authentication

All requests require a Bearer token in the Authorization header.

Authorization: Bearer <MINIMAX_API_KEY>
Content-Type: application/json

Base URL: https://api.minimax.io/v1/

Get your API key at platform.minimax.io > Account Management > API Keys. Use a Pay-as-you-go key — Coding Plan keys do NOT cover music generation.

Music Generation Endpoint

POST https://api.minimax.io/v1/music_generation

Request Body

{
  "model": "music-2.5",
  "prompt": "Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
  "lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I've been\n\n[Chorus]\nEvery road leads back to you",
  "audio_setting": {
    "sample_rate": 44100,
    "bitrate": 256000,
    "format": "mp3"
  },
  "output_format": "url",
  "stream": false
}

Parameter Reference

Parameter	Type	Required	Default	Constraints	Description
`model`	string	Yes	—	`"music-2.5"`	Model version identifier
`lyrics`	string	Yes	—	1-3500 chars	Song lyrics with structure tags and `\n` line breaks
`prompt`	string	No	`""`	0-2000 chars	Music style, mood, genre, instrument descriptors
`audio_setting`	object	No	see below	—	Audio quality configuration
`output_format`	string	No	`"hex"`	`"hex"` or `"url"`	Response format for audio data
`stream`	boolean	No	`false`	—	Enable streaming (hex output only)

audio_setting Object

Field	Type	Valid Values	Default	Description
`sample_rate`	integer	`16000`, `24000`, `32000`, `44100`	`44100`	Sample rate in Hz
`bitrate`	integer	`32000`, `64000`, `128000`, `256000`	`256000`	Bitrate in bps
`format`	string	`"mp3"`, `"wav"`, `"pcm"`	`"mp3"`	Output audio format

Structure Tags (14 supported)

These tags control song arrangement. Place each on its own line before the lyrics for that section:

Tag	Purpose
`[Intro]`	Opening instrumental or vocal intro
`[Verse]`	Main verse section
`[Pre Chorus]`	Build-up before chorus
`[Chorus]`	Main chorus/hook
`[Post Chorus]`	Section immediately after chorus
`[Bridge]`	Contrasting section, usually before final chorus
`[Interlude]`	Instrumental break between sections
`[Outro]`	Closing section
`[Transition]`	Short musical transition between sections
`[Break]`	Rhythmic break or pause
`[Hook]`	Catchy melodic hook section
`[Build Up]`	Increasing intensity before a drop or chorus
`[Inst]`	Instrumental-only section (no vocals)
`[Solo]`	Instrumental solo (guitar solo, etc.)

Tags count toward the 3500 character limit.

Success Response (output_format: "url")

{
  "trace_id": "0af12abc3def4567890abcdef1234567",
  "data": {
    "status": 2,
    "audio": "https://cdn.minimax.io/music/output_abc123.mp3"
  },
  "extra_info": {
    "music_duration": 187.4,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 6054912
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Success Response (output_format: "hex")

{
  "trace_id": "0af12abc3def4567890abcdef1234567",
  "data": {
    "status": 2,
    "audio": "fffb9064000000..."
  },
  "extra_info": {
    "music_duration": 187.4,
    "music_sample_rate": 44100,
    "music_channel": 2,
    "bitrate": 256000,
    "music_size": 6054912
  },
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Response Field Reference

Field	Type	Description
`trace_id`	string	Unique request trace ID for debugging
`data.status`	integer	`1` = in progress, `2` = completed
`data.audio`	string	Audio URL (url mode) or hex-encoded bytes (hex mode)
`extra_info.music_duration`	float	Duration in seconds
`extra_info.music_sample_rate`	integer	Actual sample rate used
`extra_info.music_channel`	integer	Channel count (`2` = stereo)
`extra_info.bitrate`	integer	Actual bitrate used
`extra_info.music_size`	integer	File size in bytes
`base_resp.status_code`	integer	`0` = success, see error codes
`base_resp.status_msg`	string	Human-readable status message

Streaming Behavior

When stream: true is set:

Only works with output_format: "hex" (NOT compatible with "url")
Response arrives as Server-Sent Events (SSE)
Each chunk contains data.audio with a hex fragment
Chunks with data.status: 1 are audio data
Final chunk has data.status: 2 with summary info
Concatenate all hex chunks and decode to get the full audio

Lyrics Generation Endpoint

POST https://api.minimax.io/v1/lyrics_generation

Request Body

{
  "mode": "write_full_song",
  "prompt": "A soulful blues song about a rainy night and lost love"
}

Parameter Reference

Parameter	Type	Required	Default	Constraints	Description
`mode`	string	Yes	—	`"write_full_song"` or `"edit"`	Generation mode
`prompt`	string	No	—	0-2000 chars	Theme, concept, or style description
`lyrics`	string	No	—	0-3500 chars	Existing lyrics (edit mode only)
`title`	string	No	—	—	Song title (preserved if provided)

Response Body

{
  "song_title": "Rainy Night Blues",
  "style_tags": "Soulful Blues, Rainy Night, Melancholy, Male Vocals, Slow Tempo",
  "lyrics": "[Verse]\nThe streetlights blur through window pane\nAnother night of autumn rain\n\n[Chorus]\nYou left me standing in the storm\nNow all I have is memories warm",
  "base_resp": {
    "status_code": 0,
    "status_msg": "success"
  }
}

Response Field Reference

Field	Type	Description
`song_title`	string	Generated or preserved song title
`style_tags`	string	Comma-separated style descriptors (use as music prompt)
`lyrics`	string	Generated lyrics with structure tags — ready for music_generation
`base_resp.status_code`	integer	`0` = success
`base_resp.status_msg`	string	Status message

Two-Step Workflow

Step 1: POST /v1/lyrics_generation
        Input:  { mode: "write_full_song", prompt: "theme description" }
        Output: { song_title, style_tags, lyrics }

Step 2: POST /v1/music_generation
        Input:  { model: "music-2.5", prompt: style_tags, lyrics: lyrics }
        Output: { data.audio (url or hex) }

Audio Quality Presets

Low Bandwidth (smallest file)

{ "sample_rate": 16000, "bitrate": 64000, "format": "mp3" }

Preview / Draft

{ "sample_rate": 24000, "bitrate": 128000, "format": "mp3" }

Standard (recommended default)

{ "sample_rate": 44100, "bitrate": 256000, "format": "mp3" }

Professional / DAW Import

{ "sample_rate": 44100, "bitrate": 256000, "format": "wav" }

Rate Limits and Pricing

Tier	Monthly Cost	Credits	RPM (requests/min)
Starter	$5	100,000	10
Standard	$30	300,000	50
Pro	$99	1,100,000	200
Scale	$249	3,300,000	500
Business	$999	20,000,000	800

Credits consumed per generation are based on audio duration. Audio URLs expire after 24 hours. FILE:references/prompt-engineering-guide.md

Music Prompt Engineering Guide

The 8-Component Formula

Build prompts by combining these components. Not all are required — use 4-6 for typical requests.

[Genre/Style], [Era/Reference], [Mood/Emotion], [Vocal Type], [Tempo/BPM], [Instruments], [Production Style], [Atmosphere]

Component Details

1. Genre/Style Indie folk, Progressive house, Soulful blues, Pop ballad, Jazz fusion, Synthwave, Ambient electronic, Country rock, Hip-hop boom bap, Classical orchestral, R&B, Disco funk, Lo-fi indie, Metal

2. Era/Reference 1960s Motown, 70s disco, 80s synthwave, 90s grunge, 2000s pop-punk, modern, retro, vintage, contemporary, classic

3. Mood/Emotion melancholic, euphoric, nostalgic, hopeful, bittersweet, triumphant, yearning, peaceful, brooding, playful, intense, dreamy, defiant, tender, wistful, anthemic

4. Vocal Type breathy female alto, powerful soprano, raspy male tenor, warm baritone, deep resonant bass, falsetto, husky, crystal clear, choir harmonies, a cappella, duet, operatic

5. Tempo/BPM slow 60 BPM, ballad tempo 70 BPM, mid-tempo 100 BPM, upbeat 120 BPM, driving 128 BPM, fast-paced 140 BPM, energetic 160 BPM

6. Instruments acoustic guitar, electric guitar, fingerpicked guitar, piano, Rhodes piano, upright bass, electric bass, drums, brushed snare, synthesizer, strings, violin, cello, trumpet, saxophone, harmonica, ukulele, banjo, mandolin, flute, organ, harp, percussion, congas, tambourine, vibraphone, steel drums

7. Production Style lo-fi, polished pop production, raw live recording, studio quality, bedroom recording, vinyl warmth, analog tape, digital crisp, spacious reverb, dry and intimate, heavily compressed, minimalist

8. Atmosphere intimate, epic, dreamy, cinematic, ethereal, gritty, lush, sparse, warm, cold, dark, bright, urban, pastoral, cosmic, underground

Genre-Specific Prompt Templates

Pop

Upbeat pop, catchy chorus, synthesizer, four-on-the-floor beat, bright female vocals, radio-ready production, energetic 120 BPM

Pop Ballad

Pop ballad, emotional, piano-driven, powerful female vocals with vibrato, sweeping strings, slow tempo 70 BPM, polished production, heartfelt

Indie Folk

Indie folk, melancholic, introspective, acoustic fingerpicking guitar, soft piano, gentle male vocals, intimate bedroom recording, 90 BPM

Soulful Blues

Soulful blues, rainy night, melancholy, raspy male vocals, slow tempo 65 BPM, electric guitar, upright bass, harmonica, warm analog feel

Jazz

Jazz ballad, warm and intimate, upright bass, brushed snare, piano, muted trumpet, 1950s club atmosphere, smooth male vocals, 80 BPM

Electronic / Dance

Progressive house, euphoric, driving bassline, 128 BPM, synthesizer pads, arpeggiated leads, modern production, festival energy, build-ups and drops

Rock

Indie rock, anthemic, distorted electric guitar, powerful drum kit, passionate male vocals, stadium feel, energetic 140 BPM, raw energy

Classical / Orchestral

Orchestral, sweeping strings, French horn, dramatic tension, cinematic, full symphony, dynamic crescendos, epic and majestic

Hip-Hop

Lo-fi hip hop, boom bap, vinyl crackle, jazzy piano sample, relaxed beat 85 BPM, introspective mood, head-nodding groove

R&B

Contemporary R&B, smooth, falsetto male vocals, Rhodes piano, muted guitar, late night urban feel, 90 BPM, lush production

Country / Americana

Appalachian folk, storytelling, acoustic fingerpicking, fiddle, raw and honest, dusty americana, warm male vocals, 100 BPM

Metal

Heavy metal, distorted riffs, double kick drum, aggressive powerful vocals, dark atmosphere, intense and relentless, 160 BPM

Synthwave / 80s

Synthwave, 80s retro, pulsing synthesizers, gated reverb drums, neon-lit atmosphere, driving arpeggios, nostalgic and cinematic, 110 BPM

Lo-fi Indie

Lo-fi indie pop, mellow 92 BPM, soft female vocals airy and intimate, clean electric guitar, lo-fi drums, vinyl warmth, bedroom recording aesthetic, late night melancholy

Disco Funk

Disco funk, groovy bassline, wah-wah guitar, brass section, four-on-the-floor kick, 115 BPM, energetic female vocals, sparkling production, dancefloor energy

Vocal Descriptor Catalog

Female Vocals

breathy female vocal with emotional delivery and subtle vibrato
powerful soprano, clear and soaring, with controlled dynamics
soft, intimate female alto, whispery and gentle
sassy, confident female voice with rhythmic phrasing
ethereal, angelic female vocal with layered harmonies
raspy, soulful female voice with blues inflection

Male Vocals

warm baritone, smooth and resonant, with emotional depth
raspy male tenor with rock edge and raw power
deep, resonant bass voice, commanding and rich
falsetto male vocal, airy and delicate, R&B style
gravelly crooner, vintage jazz feel, intimate delivery
powerful tenor with soaring high notes and controlled vibrato

Ensemble / Special

male-female duet with harmonized chorus
choir harmonies, layered voices, cathedral reverb
a cappella vocal arrangement, no instruments
spoken word with musical backing
vocal ad-libs and runs between main phrases

Mood/Emotion Vocabulary

These descriptors map well to Minimax's training:

Category	Words
Sad	melancholic, bittersweet, yearning, wistful, somber, mournful, lonely
Happy	euphoric, joyful, uplifting, celebratory, playful, carefree, sunny
Intense	driving, powerful, fierce, relentless, urgent, explosive, raw
Calm	peaceful, serene, meditative, tranquil, floating, gentle, soothing
Dark	brooding, ominous, haunting, sinister, shadowy, tense, mysterious
Romantic	tender, intimate, warm, passionate, longing, devoted, sensual
Epic	triumphant, majestic, anthemic, soaring, grandiose, cinematic, sweeping
Nostalgic	retro, vintage, throwback, reminiscent, dreamy, hazy, faded

Anti-Patterns to Avoid

Negations (DON'T USE)

The model does not reliably process negative instructions.

Bad	Good
"no drums"	"acoustic guitar and piano only"
"without vocals"	use `[Inst]` tags in lyrics
"not too fast"	"slow tempo 70 BPM"
"don't use autotune"	"raw, natural vocal delivery"

Conflicting Styles

Do not combine contradictory aesthetics:

Conflict	Why
"vintage lo-fi" + "crisp modern production"	lo-fi and crisp are opposites
"intimate whisper" + "powerful belting"	can't be both simultaneously
"minimalist" + "full orchestra"	sparse vs. dense
"raw punk" + "polished pop production"	production styles clash

Overly Generic (Too Vague)

Weak	Strong
"sad song with guitar"	"melancholic indie folk, fingerpicked acoustic guitar, male vocals, intimate, 85 BPM"
"happy music"	"upbeat pop, bright female vocals, synth and piano, 120 BPM, radio-ready"
"rock song"	"indie rock, anthemic, distorted electric guitar, driving drums, passionate vocals, 140 BPM"
"electronic music"	"progressive house, euphoric, 128 BPM, synthesizer pads, driving bassline"

Prompt Refinement Checklist

When reviewing a prompt, check:

Does it specify a genre? (e.g., "indie folk" not just "folk")
Does it include mood/emotion? (at least one descriptor)
Does it name specific instruments? (not just "music")
Does it indicate tempo or energy level? (BPM or descriptor)
Does it describe the vocal style? (if the song has vocals)
Is it under 2000 characters?
Are there any negations to rewrite?
Are there any conflicting style combinations? FILE:references/error-codes.md

Minimax API Error Reference

Error Code Table

Code	Name	Cause	Fix
`0`	Success	Request completed	No action needed
`1002`	Rate Limited	Too many requests per minute	Wait 10-30 seconds and retry with exponential backoff
`1004`	Auth Failed	Invalid, expired, or missing API key	Verify key at platform.minimax.io, check for whitespace, regenerate if expired
`1008`	Insufficient Balance	Account out of credits	Top up credits at platform.minimax.io > Billing
`1026`	Content Flagged	Lyrics or prompt triggered content moderation	Revise lyrics/prompt to remove sensitive, violent, or explicit content
`2013`	Invalid Parameters	Request body has wrong types or out-of-range values	Validate all parameters against the API schema
`2049`	Invalid API Key Format	API key string is malformed	Check for trailing newlines, extra spaces, or copy-paste errors

Troubleshooting Decision Tree

Got an error response?
│
├─ Check base_resp.status_code
│
├─ 1002 (Rate Limited)
│  ├─ Are you sending many requests? → Add delay between calls
│  ├─ Only one request? → Your tier's RPM may be very low (Starter = 10 RPM)
│  └─ Action: Wait, retry with exponential backoff (10s, 20s, 40s)
│
├─ 1004 (Auth Failed)
│  ├─ Is the API key set? → Check Authorization header format
│  ├─ Is it a Coding Plan key? → Music needs Pay-as-you-go key
│  ├─ Has the key expired? → Regenerate at platform.minimax.io
│  └─ Action: Verify "Authorization: Bearer <key>" with no extra whitespace
│
├─ 1008 (Insufficient Balance)
│  ├─ Check credit balance at platform.minimax.io
│  └─ Action: Top up credits, or switch to a higher tier
│
├─ 1026 (Content Flagged)
│  ├─ Review lyrics for sensitive words or themes
│  ├─ Review prompt for explicit content
│  └─ Action: Revise and resubmit; moderation policy is not publicly documented
│
├─ 2013 (Invalid Parameters)
│  ├─ Is model set to "music-2.5"? (not "music-01" or other)
│  ├─ Is lyrics between 1-3500 chars?
│  ├─ Is prompt under 2000 chars?
│  ├─ Is sample_rate one of: 16000, 24000, 32000, 44100?
│  ├─ Is bitrate one of: 32000, 64000, 128000, 256000?
│  ├─ Is format one of: "mp3", "wav", "pcm"?
│  ├─ Is output_format one of: "hex", "url"?
│  └─ Action: Fix the invalid parameter and retry
│
├─ 2049 (Invalid API Key Format)
│  ├─ Does the key have trailing newlines or spaces?
│  ├─ Was it copied correctly from the dashboard?
│  └─ Action: Re-copy the key, trim whitespace
│
└─ data.status === 1 (Not an error!)
   └─ Generation is still in progress. Poll again or wait for completion.

Common Parameter Mistakes

Mistake	Problem	Fix
`"model": "music-01"`	Wrong model for native API	Use `"music-2.5"`
`"lyrics": ""`	Empty lyrics string	Lyrics must be 1-3500 chars
`"sample_rate": 48000`	Invalid sample rate	Use 16000, 24000, 32000, or 44100
`"bitrate": 320000`	Invalid bitrate	Use 32000, 64000, 128000, or 256000
`"format": "flac"`	Unsupported format	Use "mp3", "wav", or "pcm"
`"stream": true` + `"output_format": "url"`	Streaming only supports hex	Set `output_format` to `"hex"` or disable streaming
Missing `Content-Type` header	Server can't parse JSON	Add `Content-Type: application/json`
Key with trailing `\n`	Auth fails silently	Trim the key string
Prompt over 2000 chars	Rejected by API	Shorten the prompt
Lyrics over 3500 chars	Rejected by API	Shorten lyrics or remove structure tags

HTTP Status Codes

HTTP Status	Meaning	Action
`200`	Request processed	Check `base_resp.status_code` for API-level errors
`401`	Unauthorized	API key missing or invalid
`429`	Too Many Requests	Rate limited — back off and retry
`500`	Server Error	Retry after a short delay
`503`	Service Unavailable	Minimax servers overloaded — retry later
FILE:examples/code-examples.md

Code Examples

All examples load the API key from the .env file via environment variables.

Python: Music Generation (URL Output)

import os
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")

def generate_music(prompt, lyrics, output_file="output.mp3"):
    response = requests.post(
        "https://api.minimax.io/v1/music_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "music-2.5",
            "prompt": prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "url"
        }
    )
    response.raise_for_status()
    result = response.json()

    if result["base_resp"]["status_code"] != 0:
        raise Exception(f"API error {result['base_resp']['status_code']}: {result['base_resp']['status_msg']}")

    audio_url = result["data"]["audio"]
    duration = result["extra_info"]["music_duration"]
    print(f"Generated {duration:.1f}s of music")

    audio_data = requests.get(audio_url)
    with open(output_file, "wb") as f:
        f.write(audio_data.content)
    print(f"Saved to {output_file}")
    return result

# Usage
generate_music(
    prompt="Indie folk, melancholic, acoustic guitar, soft piano, female vocals",
    lyrics="""[Intro]

[Verse]
Walking through the autumn leaves
Nobody knows where I've been

[Chorus]
Every road leads back to you
Every song I hear rings true

[Outro]
""",
    output_file="my_song.mp3"
)

Python: Music Generation (Hex Output)

import os
import binascii
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")

def generate_music_hex(prompt, lyrics, output_file="output.mp3"):
    response = requests.post(
        "https://api.minimax.io/v1/music_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "music-2.5",
            "prompt": prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "hex"
        }
    )
    response.raise_for_status()
    result = response.json()

    if result["base_resp"]["status_code"] != 0:
        raise Exception(f"API error: {result['base_resp']['status_msg']}")

    audio_bytes = binascii.unhexlify(result["data"]["audio"])
    with open(output_file, "wb") as f:
        f.write(audio_bytes)
    print(f"Saved {len(audio_bytes)} bytes to {output_file}")

Python: Two-Step Workflow (Lyrics then Music)

import os
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")
BASE_URL = "https://api.minimax.io/v1"
HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

def generate_lyrics(theme):
    """Step 1: Generate structured lyrics from a theme."""
    response = requests.post(
        f"{BASE_URL}/lyrics_generation",
        headers=HEADERS,
        json={
            "mode": "write_full_song",
            "prompt": theme
        }
    )
    response.raise_for_status()
    data = response.json()
    if data["base_resp"]["status_code"] != 0:
        raise Exception(f"Lyrics error: {data['base_resp']['status_msg']}")
    return data

def generate_music(style_prompt, lyrics, output_file="song.mp3"):
    """Step 2: Generate music from lyrics and a style prompt."""
    response = requests.post(
        f"{BASE_URL}/music_generation",
        headers=HEADERS,
        json={
            "model": "music-2.5",
            "prompt": style_prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "url"
        }
    )
    response.raise_for_status()
    result = response.json()
    if result["base_resp"]["status_code"] != 0:
        raise Exception(f"Music error: {result['base_resp']['status_msg']}")

    audio_data = requests.get(result["data"]["audio"])
    with open(output_file, "wb") as f:
        f.write(audio_data.content)
    print(f"Saved to {output_file} ({result['extra_info']['music_duration']:.1f}s)")
    return result

# Full workflow
theme = "A soulful blues song about a rainy night and lost love"
style = "Soulful blues, rainy night, melancholy, male vocals, slow tempo, electric guitar, upright bass"

print("Step 1: Generating lyrics...")
lyrics_data = generate_lyrics(theme)
print(f"Title: {lyrics_data['song_title']}")
print(f"Style: {lyrics_data['style_tags']}")
print(f"Lyrics:\n{lyrics_data['lyrics']}\n")

print("Step 2: Generating music...")
generate_music(style, lyrics_data["lyrics"], "blues_song.mp3")

Python: Streaming Response

import os
import json
import binascii
import requests
from dotenv import load_dotenv

load_dotenv()
API_KEY = os.getenv("MINIMAX_API_KEY")

def generate_music_streaming(prompt, lyrics, output_file="stream_output.mp3"):
    response = requests.post(
        "https://api.minimax.io/v1/music_generation",
        headers={
            "Authorization": f"Bearer {API_KEY}",
            "Content-Type": "application/json"
        },
        json={
            "model": "music-2.5",
            "prompt": prompt,
            "lyrics": lyrics,
            "audio_setting": {
                "sample_rate": 44100,
                "bitrate": 256000,
                "format": "mp3"
            },
            "output_format": "hex",
            "stream": True
        },
        stream=True
    )
    response.raise_for_status()

    chunks = []
    for line in response.iter_lines():
        if not line:
            continue
        line_str = line.decode("utf-8")
        if not line_str.startswith("data:"):
            continue
        data = json.loads(line_str[5:].strip())

        if data.get("base_resp", {}).get("status_code", 0) != 0:
            raise Exception(f"Stream error: {data['base_resp']['status_msg']}")

        if data.get("data", {}).get("status") == 1 and data["data"].get("audio"):
            chunks.append(binascii.unhexlify(data["data"]["audio"]))

    audio_bytes = b"".join(chunks)
    with open(output_file, "wb") as f:
        f.write(audio_bytes)
    print(f"Streaming complete: {len(audio_bytes)} bytes saved to {output_file}")

JavaScript / Node.js: Music Generation (URL Output)

import "dotenv/config";
import { writeFile } from "fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;

async function generateMusic(prompt, lyrics, outputPath = "output.mp3") {
  const response = await fetch("https://api.minimax.io/v1/music_generation", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "music-2.5",
      prompt,
      lyrics,
      audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
      output_format: "url",
    }),
  });

  const result = await response.json();

  if (result.base_resp?.status_code !== 0) {
    throw new Error(`API Error ${result.base_resp?.status_code}: ${result.base_resp?.status_msg}`);
  }

  const audioUrl = result.data.audio;
  const audioResponse = await fetch(audioUrl);
  const audioBuffer = Buffer.from(await audioResponse.arrayBuffer());

  await writeFile(outputPath, audioBuffer);
  console.log(`Saved to ${outputPath} (${result.extra_info.music_duration.toFixed(1)}s)`);
  return result;
}

// Usage
await generateMusic(
  "Pop, upbeat, energetic, female vocals, synthesizer, driving beat",
  `[Verse]
Running through the city lights
Everything is burning bright

[Chorus]
We are alive tonight
Dancing through the neon light`,
  "pop_song.mp3"
);

JavaScript / Node.js: Hex Output with Decode

import "dotenv/config";
import { writeFile } from "fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;

async function generateMusicHex(prompt, lyrics, outputPath = "output.mp3") {
  const response = await fetch("https://api.minimax.io/v1/music_generation", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "music-2.5",
      prompt,
      lyrics,
      audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
      output_format: "hex",
    }),
  });

  const result = await response.json();

  if (result.base_resp?.status_code !== 0) {
    throw new Error(`API Error: ${result.base_resp?.status_msg}`);
  }

  const audioBuffer = Buffer.from(result.data.audio, "hex");
  await writeFile(outputPath, audioBuffer);
  console.log(`Saved ${audioBuffer.length} bytes to ${outputPath}`);
}

JavaScript / Node.js: Streaming

import "dotenv/config";
import { writeFile } from "fs/promises";

const API_KEY = process.env.MINIMAX_API_KEY;

async function generateMusicStreaming(prompt, lyrics, outputPath = "stream_output.mp3") {
  const response = await fetch("https://api.minimax.io/v1/music_generation", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "music-2.5",
      prompt,
      lyrics,
      audio_setting: { sample_rate: 44100, bitrate: 256000, format: "mp3" },
      output_format: "hex",
      stream: true,
    }),
  });

  const chunks = [];
  const decoder = new TextDecoder();
  const reader = response.body.getReader();
  let buffer = "";

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    let boundary;

    while ((boundary = buffer.indexOf("\n\n")) !== -1) {
      const event = buffer.slice(0, boundary).trim();
      buffer = buffer.slice(boundary + 2);

      if (!event) continue;
      const dataMatch = event.match(/^data:\s*(.+)$/m);
      if (!dataMatch) continue;

      const parsed = JSON.parse(dataMatch[1]);

      if (parsed.base_resp?.status_code !== 0) {
        throw new Error(`Stream error: ${parsed.base_resp?.status_msg}`);
      }

      if (parsed.data?.status === 1 && parsed.data?.audio) {
        chunks.push(Buffer.from(parsed.data.audio, "hex"));
      }
    }
  }

  const fullAudio = Buffer.concat(chunks);
  await writeFile(outputPath, fullAudio);
  console.log(`Streaming complete: ${fullAudio.length} bytes saved to ${outputPath}`);
}

cURL: Music Generation

curl -X POST "https://api.minimax.io/v1/music_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-2.5",
    "prompt": "Indie folk, melancholic, acoustic guitar, soft piano",
    "lyrics": "[Verse]\nWalking through the autumn leaves\nNobody knows where I have been\n\n[Chorus]\nEvery road leads back to you\nEvery song I hear rings true",
    "audio_setting": {
      "sample_rate": 44100,
      "bitrate": 256000,
      "format": "mp3"
    },
    "output_format": "url"
  }'

cURL: Lyrics Generation

curl -X POST "https://api.minimax.io/v1/lyrics_generation" \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "write_full_song",
    "prompt": "A soulful blues song about a rainy night and lost love"
  }'

Audio Quality Presets

Python dict presets

QUALITY_LOW = {"sample_rate": 16000, "bitrate": 64000, "format": "mp3"}
QUALITY_PREVIEW = {"sample_rate": 24000, "bitrate": 128000, "format": "mp3"}
QUALITY_STANDARD = {"sample_rate": 44100, "bitrate": 256000, "format": "mp3"}
QUALITY_PROFESSIONAL = {"sample_rate": 44100, "bitrate": 256000, "format": "wav"}

JavaScript object presets

const QUALITY_LOW = { sample_rate: 16000, bitrate: 64000, format: "mp3" };
const QUALITY_PREVIEW = { sample_rate: 24000, bitrate: 128000, format: "mp3" };
const QUALITY_STANDARD = { sample_rate: 44100, bitrate: 256000, format: "mp3" };
const QUALITY_PROFESSIONAL = { sample_rate: 44100, bitrate: 256000, format: "wav" };

FILE:examples/lyrics-templates.md

Lyrics Templates

Song Structure Patterns

Common arrangements as tag sequences:

Standard Pop/Rock: [Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Chorus] → [Outro]

Ballad: [Intro] → [Verse] → [Verse] → [Chorus] → [Verse] → [Chorus] → [Bridge] → [Chorus] → [Outro]

Electronic/Dance: [Intro] → [Build Up] → [Chorus] → [Break] → [Verse] → [Build Up] → [Chorus] → [Outro]

Simple/Short: [Verse] → [Chorus] → [Verse] → [Chorus] → [Outro]

Progressive/Epic: [Intro] → [Verse] → [Pre Chorus] → [Chorus] → [Interlude] → [Verse] → [Pre Chorus] → [Chorus] → [Bridge] → [Solo] → [Build Up] → [Chorus] → [Outro]

Pop Song Template

[Intro]

[Verse]
Morning light breaks through my window pane
Another day I try to start again
The coffee's cold, the silence fills the room
But something tells me change is coming soon

[Pre Chorus]
I can feel it in the air tonight
Something shifting, pulling me toward the light

[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Verse]
The photographs are fading on the shelf
I'm learning how to just be myself
No more hiding underneath the weight
Of everything I thought would make me great

[Pre Chorus]
I can feel it in the air tonight
Something shifting, pulling me toward the light

[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Bridge]
It took so long to see
The only one holding me back was me

[Chorus]
I'm breaking through the walls I built
Letting go of all this guilt
Every step I take is mine
I'm finally feeling fine
I'm breaking through

[Outro]

Rock Song Template

[Intro]

[Verse]
Engines roar on an empty highway
Headlights cutting through the dark
Running from the life I used to know
Chasing down a distant spark

[Verse]
Radio plays our broken anthem
Windows down and letting go
Every mile puts it all behind me
Every sign says don't look home

[Pre Chorus]
Tonight we burn it all
Tonight we rise or fall

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Inst]

[Verse]
Streetlights flicker like a warning
But I'm too far gone to care
Took the long road out of nowhere
Found myself already there

[Pre Chorus]
Tonight we burn it all
Tonight we rise or fall

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Bridge]
They said we'd never make it
Said we'd crash and burn
But look at us still standing
Every scar a lesson learned

[Solo]

[Build Up]
We are we are we are

[Chorus]
We are the reckless hearts
Tearing the world apart
Nothing can stop this fire inside
We are the reckless hearts

[Outro]

Ballad Template

[Intro]

[Verse]
The winter trees are bare and still
Snow falls softly on the hill
I remember when you held my hand
Walking paths we used to plan

[Verse]
Your laughter echoes in these halls
Your name is written on these walls
Time has taken what we had
But memories still make me glad

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Verse]
The seasons change but I remain
Standing here through sun and rain
Every star I see at night
Reminds me of your gentle light

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Bridge]
And if the years should wash away
Every word I meant to say
Know that love was always true
Every moment led to you

[Chorus]
I will carry you with me
Through the storms and through the sea
Even when the world goes dark
You're the ember in my heart
I will carry you

[Outro]

Hip-Hop / R&B Template

[Intro]

[Verse]
City lights reflecting off the rain
Another late night grinding through the pain
Started from the bottom with a dream
Nothing's ever easy as it seems
Momma said to keep my head up high
Even when the storm clouds fill the sky
Now I'm standing tall above the noise
Found my voice and made a choice

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Verse]
Look around at everything we built
From the ashes rising no more guilt
Every scar a story that I own
Seeds of struggle finally have grown
Late nights early mornings on repeat
Every setback made the win more sweet
Now they see the vision crystal clear
We've been building this for years

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Bridge]
From the bottom to the top
We don't know how to stop

[Hook]
We don't stop we keep it moving
Every day we keep on proving
That the grind don't stop for nothing
We keep pushing keep on hustling

[Outro]

Electronic / Dance Template

[Intro]

[Build Up]
Feel the pulse beneath the floor
Can you hear it wanting more

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Break]

[Verse]
Strangers dancing side by side
In this moment nothing to hide
Every heartbeat syncs in time
Lost in rhythm lost in rhyme

[Build Up]
Feel the pulse beneath the floor
Can you hear it wanting more
Louder louder

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Inst]

[Build Up]
One more time

[Chorus]
Lose yourself in neon lights
We're alive alive tonight
Let the music take control
Feel the rhythm in your soul
We're alive alive tonight

[Outro]

Folk / Acoustic Template

[Intro]

[Verse]
Down by the river where the willows lean
I found a letter in the autumn green
Words like water flowing soft and slow
Telling stories from so long ago

[Verse]
My grandfather walked these roads before
Carried burdens through a world at war
But he never lost his gentle way
And his kindness lives in me today

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Verse]
Now the seasons paint the hills with gold
And the stories keep the young from cold
Every sunset brings a quiet prayer
For the ones who are no longer there

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Bridge]
So I'll walk a little further still
Past the chapel on the distant hill
And I'll listen for the echoes there
Carried softly through the evening air

[Chorus]
These old roads remember everything
Every footstep every song we sing
Through the valleys and the mountain air
Love is planted everywhere
These old roads remember

[Outro]

Jazz Template

[Intro]

[Verse]
Smoke curls slowly in the amber light
Piano whispers through the velvet night
A glass of something golden in my hand
The drummer keeps a brushstroke on the snare

[Verse]
She walked in like a song I used to know
A melody from many years ago
Her smile could melt the winter off the glass
Some moments were not meant to ever last

[Chorus]
But we danced until the morning came
Two strangers playing at a nameless game
The saxophone was crying soft and low
And neither one of us wanted to go

[Solo]

[Verse]
The city sleeps but we are wide awake
Sharing secrets for each other's sake
Tomorrow we'll be strangers once again
But tonight we're more than just old friends

[Chorus]
And we danced until the morning came
Two strangers playing at a nameless game
The saxophone was crying soft and low
And neither one of us wanted to go

[Outro]

Instrumental-Only Templates

Cinematic Instrumental

[Intro]

[Inst]
(Soft piano, building strings)

[Build Up]
(Full orchestra swelling)

[Inst]
(Triumphant brass and percussion)

[Interlude]
(Gentle woodwinds, reflective)

[Build Up]
(Timpani roll, rising tension)

[Inst]
(Full symphonic climax)

[Outro]
(Fading strings, peaceful resolution)

Guitar Solo Showcase

[Intro]

[Inst]
(Rhythm guitar and bass groove)

[Solo]
(Lead guitar melody)

[Inst]
(Full band groove)

[Solo]
(Extended guitar solo, building intensity)

[Break]

[Solo]
(Final guitar solo, emotional peak)

[Outro]

Ambient / Atmospheric

[Intro]

[Inst]
(Ethereal synth pads, slow evolution)

[Transition]

[Inst]
(Layered textures, subtle percussion)

[Interlude]
(Minimal, spacious)

[Build Up]
(Gradually intensifying)

[Inst]
(Full atmospheric wash)

[Outro]
(Slowly dissolving into silence)