# MiniMax 音乐生成 API 参考

## 端点
```
POST https://api.minimaxi.com/v1/music_generation
```

## 请求头
```
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

## 请求体参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `model` | string | ✅ | `music-2.6`, `music-cover`, `music-2.6-free`, `music-cover-free` |
| `prompt` | string | ✅/❌ | 音乐描述，1-2000字符。纯音乐时必填 |
| `lyrics` | string | ✅/❌ | 歌词，`\n`分隔，支持结构标签如 `[Verse]`, `[Chorus]` 等 |
| `is_instrumental` | boolean | ❌ | 是否纯音乐（无人声），默认 false。true 时 lyrics 非必填 |
| `output_format` | string | ❌ | `url` 或 `hex`，默认 `hex`（24小时有效） |
| `stream` | boolean | ❌ | 流式传输，默认 false |
| `lyrics_optimizer` | boolean | ❌ | 自动生成歌词，仅 music-2.6 系列 |
| `aigc_watermark` | boolean | ❌ | 添加水印，默认 false |
| `audio_setting` | object | ❌ | 采样率/比特率/格式设置 |

### audio_setting 参数
```json
{
  "sample_rate": 44100,   // 16000, 24000, 32000, 44100
  "bitrate": 256000,     // 32000, 64000, 128000, 256000
  "format": "mp3"        // mp3, wav, pcm
}
```

### 歌词结构标签
`[Intro]`, `[Verse]`, `[Pre Chorus]`, `[Chorus]`, `[Interlude]`, `[Bridge]`, `[Outro]`, `[Post Chorus]`, `[Transition]`, `[Break]`, `[Hook]`, `[Build Up]`, `[Inst]`, `[Solo]`

## 响应
```json
{
  "data": {
    "audio": "hex编码...",
    "status": 2   // 1=合成中, 2=已完成
  },
  "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" }
}
```

## 错误码
- `0` — 成功
- `1002` — 限流
- `1004` — 鉴权失败
- `1008` — 余额不足
- `1026` — 内容涉敏
- `2013` — 参数错误
- `2049` — 无效 key
- `2061` — 模型不支持

## 常用调用示例

### curl（纯音乐，hex）
```bash
curl -X POST https://api.minimaxi.com/v1/music_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-2.6",
    "prompt": "acoustic guitar instrumental, relaxing, peaceful",
    "is_instrumental": true,
    "output_format": "hex"
  }'
```

### curl（非纯音乐，带歌词，url）
```bash
curl -X POST https://api.minimaxi.com/v1/music_generation \
  -H "Authorization: Bearer $MINIMAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "music-2.6",
    "prompt": "流行音乐, 忧郁, 适合在下雨的晚上",
    "lyrics": "[Verse]\n街灯微亮晚风轻抚\n影子拉长独自漫步\n\n[Chorus]\n推开木门香气弥漫",
    "output_format": "url",
    "audio_setting": {
      "sample_rate": 44100,
      "bitrate": 256000,
      "format": "mp3"
    }
  }'
```

### hex 解码保存
```python
import binascii, requests

resp = requests.post(endpoint, headers=headers, json=payload)
audio_hex = resp.json()["data"]["audio"]
with open("output.mp3", "wb") as f:
    f.write(binascii.unhexlify(audio_hex))
```

### url 下载保存
```python
import requests

resp = requests.post(endpoint, headers=headers, json=payload)
url = resp.json()["data"]["audio"]  # 24小时内有效
r = requests.get(url)
with open("output.mp3", "wb") as f:
    f.write(r.content)
```
