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

# 获取 MIDI 生成详情

> 检索 MIDI 生成任务的详细信息,包括所有检测到的乐器的完整音符数据。

### 使用指南

* 使用此接口检查 MIDI 生成任务的状态
* 处理完成后访问完整的 MIDI 音符数据
* 检索详细的乐器和音符信息
* 跟踪处理进度和可能发生的任何错误

### 查询参数

| 参数名称     | 类型     | 必填 | 说明                |
| :------- | :----- | :- | :---------------- |
| `taskId` | string | 是  | MIDI 生成请求返回的任务 ID |

### 开发者注意事项

* `midiData` 字段包含完整的 MIDI 数据,是包含乐器 and 音符的结构化对象
* MIDI 数据包含所有检测到的乐器,每个音符都有音高、时间和力度信息
* MIDI 生成记录保留 14 天
* **重要提醒**: 当使用 [人声分离](/cn/suno-api/separate-vocals-from-music) 接口的 `type: split_stem` 参数时，`midiData` 可能为空


## OpenAPI

````yaml cn/suno-api/suno-api-cn.json GET /api/v1/midi/record-info
openapi: 3.0.0
info:
  title: intro
  description: 这是生成音频的API接口文档
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@sunoapi.org
servers:
  - url: https://api.sunoapi.org
    description: API 服务器
security:
  - BearerAuth: []
tags:
  - name: Music Generation
    description: 用于创建和管理音乐生成任务的接口
  - name: Lyrics Generation
    description: 用于歌词生成和管理的接口
  - name: WAV Conversion
    description: 用于将音乐转换为WAV格式的接口
  - name: Vocal Removal
    description: 用于从音乐轨道中移除人声的接口
  - name: Music Video Generation
    description: 用于生成MP4视频的接口
  - name: Account Management
    description: 用于账户和积分管理的接口
paths:
  /api/v1/midi/record-info:
    get:
      summary: 获取 MIDI 生成详情
      description: |-
        检索 MIDI 生成任务的详细信息,包括所有检测到的乐器的完整音符数据。

        ### 使用指南
        - 使用此接口检查 MIDI 生成任务的状态
        - 处理完成后访问完整的 MIDI 音符数据
        - 检索详细的乐器和音符信息
        - 跟踪处理进度和可能发生的任何错误

        ### 状态说明
        - `successFlag: 0`: 待执行 - 任务等待执行中
        - `successFlag: 1`: 成功 - MIDI 生成成功完成
        - `successFlag: 2`: 失败 - 创建任务失败
        - `successFlag: 3`: 失败 - 生成MIDI失败
        - 查看 errorCode 和 errorMessage 字段了解失败详情

        ### 开发者注意事项
        - midiData 字段包含完整的 MIDI 数据,是包含乐器和音符的结构化对象
        - MIDI 数据包含所有检测到的乐器,每个音符都有音高、时间和力度信息
        - MIDI 生成记录保留 14 天
        - **重要提醒**: 当使用人声分离接口的 `type: split_stem` 参数时，midiData可能为空
      operationId: get-midi-details
      parameters:
        - name: taskId
          in: query
          required: true
          schema:
            type: string
          description: MIDI 生成请求返回的任务 ID
          example: 5c79****be8e
      responses:
        '200':
          description: MIDI 生成任务详情检索成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: 响应状态码
                    example: 200
                  msg:
                    type: string
                    description: 响应消息
                    example: success
                  data:
                    type: object
                    description: MIDI 生成任务详情
                    properties:
                      taskId:
                        type: string
                        description: MIDI 生成任务 ID
                      recordTaskId:
                        type: integer
                        description: 内部记录任务 ID
                      audioId:
                        type: string
                        description: 来自人声分离任务的音频 ID
                      callbackUrl:
                        type: string
                        description: 创建任务时提供的回调 URL
                      completeTime:
                        type: integer
                        description: 任务完成时间戳(毫秒)
                      midiData:
                        type: object
                        description: 包含检测到的乐器和音符的完整 MIDI 数据
                        properties:
                          state:
                            type: string
                            description: 处理状态
                            example: complete
                          instruments:
                            type: array
                            description: 检测到的乐器及其 MIDI 音符数组
                            items:
                              type: object
                              properties:
                                name:
                                  type: string
                                  description: 乐器名称
                                notes:
                                  type: array
                                  description: 该乐器的 MIDI 音符数组
                                  items:
                                    type: object
                                    properties:
                                      pitch:
                                        type: integer
                                        description: MIDI 音符编号 (0-127)
                                      start:
                                        type: number
                                        description: 音符起始时间(秒)
                                      end:
                                        type: number
                                        description: 音符结束时间(秒)
                                      velocity:
                                        type: number
                                        description: 音符力度/强度 (0-1)
                      successFlag:
                        type: integer
                        description: 任务状态标志:0 = 待执行,1 = 成功,2 = 创建任务失败,3 = 生成MIDI失败
                      createTime:
                        type: integer
                        description: 任务创建时间戳(毫秒)
                      errorCode:
                        type: string
                        nullable: true
                        description: 任务失败时的错误代码
                      errorMessage:
                        type: string
                        nullable: true
                        description: 任务失败时的错误消息
              example:
                code: 200
                msg: success
                data:
                  taskId: 5c79****be8e
                  recordTaskId: -1
                  audioId: e231****-****-****-****-****8cadc7dc
                  callbackUrl: https://example.callback
                  completeTime: 1760335255000
                  midiData:
                    state: complete
                    instruments:
                      - name: Drums
                        notes:
                          - pitch: 73
                            start: 0.036458333333333336
                            end: 0.18229166666666666
                            velocity: 1
                          - pitch: 61
                            start: 0.046875
                            end: 0.19270833333333334
                            velocity: 1
                      - name: Electric Bass (finger)
                        notes:
                          - pitch: 44
                            start: 7.6875
                            end: 7.911458333333333
                            velocity: 1
                  successFlag: 1
                  createTime: 1760335251000
                  errorCode: null
                  errorMessage: null
        '500':
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: 服务器异常
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: |-
        # 🔑 API 认证说明

        所有接口都需要通过 Bearer Token 方式进行认证。

        ## 获取 API Key

        1. 访问 [API Key 管理页面](https://sunoapi.org/api-key) 获取您的 API Key

        ## 使用方式

        在请求头中添加：

        ```
        Authorization: Bearer YOUR_API_KEY
        ```

        > **⚠️ 注意：**
        > - 请妥善保管您的 API Key，不要泄露给他人
        > - 如果怀疑 API Key 泄露，请立即在管理页面重置

````