openapi: 3.0.0
info:
  title: Suno API
  description: Apikley Suno API Documentation
  version: 1.0.0
  contact:
    name: Technical Support
    email: support@apikley.ru
servers:
  - url: https://api.apikley.ru
    description: API Server
security:
  - BearerAuth: []
paths:
  /api/v1/midi/generate:
    post:
      summary: Generate MIDI from Audio
      description: >-
        Convert separated audio tracks into MIDI format with detailed note
        information for each instrument.


        ### Usage Guide

        - Convert separated audio tracks into structured MIDI data containing
        pitch, timing, and velocity information

        - Requires a completed vocal separation task ID (from the Vocal Removal
        API)

        - Generates MIDI note data for multiple detected instruments including
        drums, bass, guitar, keyboards, and more

        - Ideal for music transcription, notation, remixing, or educational
        analysis

        - Best results on clean, well-separated audio tracks with clear
        instrument parts


        ### Prerequisites

        - You must first use the Vocal & Instrument Stem Separation API with
        `type: split_stem` to separate your audio before generating MIDI


        ### Parameter Details

        - `taskId` identifies a completed vocal separation task 

        - `callBackUrl` receives MIDI generation completion notifications


        ### Developer Notes

        - MIDI generation typically takes 30-90 seconds depending on audio
        length and complexity

        - The callback will contain detailed note data for each detected
        instrument

        - Each note includes: pitch (MIDI note number), start (seconds), end
        (seconds), velocity (0-1)

        - Not all instruments may be detected - depends on audio content

        - Generated MIDI data is retained for 14 days
      operationId: generate-midi
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
                - callBackUrl
              properties:
                taskId:
                  type: string
                  description: >-
                    Task ID from a completed vocal separation. This should be
                    the taskId returned from the Vocal & Instrument Stem
                    Separation endpoint.
                  example: 5c79****be8e
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    The URL to receive MIDI generation task completion updates.
                    Required for all MIDI generation requests.


                    - System will POST task status and MIDI note data to this
                    URL when generation completes

                    - Callback includes detailed note information for each
                    detected instrument with pitch, timing, and velocity

                    - Your callback endpoint should accept POST requests with
                    JSON payload containing MIDI data

                    - For detailed callback format and implementation guide, see
                    [MIDI Generation
                    Callbacks](https://docs.apikley.ru/suno-api/generate-midi-callbacks)

                    - Alternatively, use the Get MIDI Generation Details
                    endpoint to poll task status
                  example: https://example.callback
      responses:
        '200':
          description: MIDI generation task created successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    description: Response status code
                    example: 200
                  msg:
                    type: string
                    description: Response message
                    example: success
                  data:
                    type: object
                    description: Response data containing task information
                    properties:
                      taskId:
                        type: string
                        description: >-
                          Unique identifier for the MIDI generation task. Use
                          this to query task status or receive callback results.
                        example: 5c79****be8e
              example:
                code: 200
                msg: success
                data:
                  taskId: 5c79****be8e
        '500':
          $ref: '#/components/responses/Error'
components:
  responses:
    Error:
      description: Server Error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        All APIs require authentication via Bearer Token.


        Get API Key:

        1. Visit [API Key Management Page](https://app.apikley.ru/keys) to get your
        API Key


        Usage:

        Add to request header:

        Authorization: Bearer APIKLEY_API_KEY


        Note:

        - Keep your API Key secure and do not share it with others

        - If you suspect your API Key has been compromised, reset it immediately
        in the management page