> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musicmint.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MIDI 导出

> 将片段的乐器音符数据导出为 MIDI 格式

## 接口

```http theme={null}
POST /api/v1/music/midi
```

**同步接口。** 直接在响应中返回 MIDI 数据。

分析音乐片段并以结构化格式返回乐器音符数据，兼容 MIDI 标准。适用于音乐制作工作流、乐谱记谱或交互式音乐工具。

## 请求参数

| 字段             | 类型     | 是否必填   | 说明                                                                                                  |
| -------------- | ------ | ------ | --------------------------------------------------------------------------------------------------- |
| `clip_id`      | string | **必填** | 要分析的音频片段 ID。通过 [音频上传](/zh/api-reference/music/upload) 获取（`data.clipId`），或使用生成任务完成后的 `results[].id`。 |
| `stem_clip_id` | string | 否      | 可选的人声分离任务 ID（来自 [人声分离](/zh/api-reference/audio/stem)），可提高乐器分离精度。                                    |

## 响应

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "request_id": "req-1710000000000",
  "data": {
    "state": "complete",
    "instruments": {
      "piano": [ ... ],
      "bass": [ ... ]
    }
  }
}
```

| 字段            | 类型     | 说明             |
| ------------- | ------ | -------------- |
| `state`       | string | 处理状态           |
| `instruments` | object | 乐器名称 → 音符数组的映射 |

## 示例

```bash theme={null}
curl -X POST https://api.example.com/api/v1/music/midi \
  -H "Authorization: Bearer sk-mm-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "clip_id": "abc123def456"
  }'
```

## 使用建议

为获得最佳效果，建议先执行 [人声分离](/zh/api-reference/audio/stem)，并将返回的任务 ID 作为 `stem_clip_id` 传入：

```bash theme={null}
# 第一步：人声分离
POST /api/v1/music/stem  →  stem.id = "stem-xyz"

# 第二步：带人声分离上下文的 MIDI 导出
POST /api/v1/music/midi  { "clip_id": "abc123", "stem_clip_id": "stem-xyz" }
```