openapi: 3.0.0
info:
  title: Suno API
  description: Apikley Suno API Documentation
  version: 1.0.0
  contact:
    name: Technical Support
    email: [email protected]
servers:
  - url: https://api.apikley.ru
    description: API Server
security:
  - BearerAuth: []
paths:
  /api/v1/generate/get-timestamped-lyrics:
    post:
      summary: Get Timestamped Lyrics
      description: >-
        Retrieve synchronized lyrics with precise timestamps for music tracks.


        ### Usage Guide

        - Use this endpoint to get lyrics that synchronize with audio playback

        - Implement karaoke-style lyric displays in your music players

        - Create visualizations that match audio timing


        ### Parameter Details

        - Both `taskId` and `audioId` are required to identify the specific
        track

        - The `taskId` comes from either "Generate Music" or "Extend Music"
        endpoints

        - The `audioId` identifies the specific track version when multiple were
        generated


        ### Developer Notes

        - Timestamps are provided in seconds for precise synchronization

        - Waveform data is included for audio visualization implementations

        - For instrumental tracks (created with `instrumental=true`), no lyrics
        data will be returned
      operationId: get-timestamped-lyrics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
                - audioId
              properties:
                taskId:
                  type: string
                  description: >-
                    Unique identifier of the music generation task. This should
                    be a taskId returned from either the "Generate Music" or
                    "Extend Music" endpoints.
                  example: 5c79****be8e
                audioId:
                  type: string
                  description: >-
                    Unique identifier of the specific audio track for which to
                    retrieve lyrics. This ID is returned in the callback data
                    after music generation completes.
                  example: e231****-****-****-****-****8cadc7dc
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 401
                          - 404
                          - 422
                          - 429
                          - 451
                          - 455
                          - 500
                        description: >-
                          Response status code


                          - **200**: Success - Request has been processed
                          successfully

                          - **401**: Unauthorized - Authentication credentials
                          are missing or invalid

                          - **404**: Not Found - The requested resource or
                          endpoint does not exist

                          - **422**: Validation Error - The request parameters
                          failed validation checks

                          - **429**: Rate Limited - Request limit has been
                          exceeded for this resource

                          - **451**: Unauthorized - Failed to fetch the image.
                          Kindly verify any access limits set by you or your
                          service provider.

                          - **455**: Service Unavailable - System is currently
                          undergoing maintenance

                          - **500**: Server Error - An unexpected error occurred
                          while processing the request
                      msg:
                        type: string
                        description: Error message when code != 200
                        example: success
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          alignedWords:
                            type: array
                            description: List of aligned lyrics words
                            items:
                              type: object
                              properties:
                                word:
                                  type: string
                                  description: Lyrics word
                                  example: |-
                                    [Verse]
                                    Waggin'
                                success:
                                  type: boolean
                                  description: Whether lyrics word is successfully aligned
                                  example: true
                                startS:
                                  type: number
                                  description: Word start time (seconds)
                                  example: 1.36
                                endS:
                                  type: number
                                  description: Word end time (seconds)
                                  example: 1.79
                                palign:
                                  type: integer
                                  description: Alignment parameter
                                  example: 0
                          waveformData:
                            type: array
                            description: Waveform data, used for audio visualization
                            items:
                              type: number
                            example:
                              - 0
                              - 1
                              - 0.5
                              - 0.75
                          hootCer:
                            type: number
                            description: Lyrics alignment accuracy score
                            example: 0.3803191489361702
                          isStreamed:
                            type: boolean
                            description: Whether it's streaming audio
                            example: false
              example:
                code: 200
                msg: success
                data:
                  alignedWords:
                    - word: |-
                        [Verse]
                        Waggin'
                      success: true
                      startS: 1.36
                      endS: 1.79
                      palign: 0
                  waveformData:
                    - 0
                    - 1
                    - 0.5
                    - 0.75
                  hootCer: 0.3803191489361702
                  isStreamed: false
        '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