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/suno/cover/generate:
    post:
      summary: Create Suno Cover Task
      description: >-
        Generate personalized cover images based on original music tasks.


        ### Usage Guide

        - Use this interface to create personalized cover images for generated
        music

        - Requires the taskId of the original music task

        - Each music task can only generate a Cover once; duplicate requests
        will return the existing taskId

        - Results will be notified through the callback URL upon completion


        ### Parameter Details

        - `taskId` identifies the unique identifier of the original music
        generation task

        - `callBackUrl` receives callback address for completion notifications


        ### Developer Notes

        - Cover image file URLs will be retained for 14 days

        - If a Cover has already been generated for this music task, a 400
        status code and existing taskId will be returned

        - It's recommended to call this interface after music generation is
        complete
      operationId: generate-cover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
                - callBackUrl
              properties:
                taskId:
                  type: string
                  description: >-
                    Original music task ID, should be the taskId returned by the
                    music generation interface.
                  example: 73d6128b3523a0079df10da9471017c8
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    URL address for receiving Cover generation task completion
                    updates. This parameter is required for all Cover generation
                    requests.


                    - The system will send POST requests to this URL when Cover
                    generation is complete, including task status and results

                    - Your callback endpoint should be able to accept JSON
                    payloads containing cover image URLs

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

                    - Alternatively, you can use the Get Cover Details interface
                    to poll task status
                  example: https://api.example.com/callback
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 400
                          - 401
                          - 402
                          - 404
                          - 409
                          - 422
                          - 429
                          - 455
                          - 500
                        description: >-
                          Response status code


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

                          - **400**: Validation error - Cover already generated
                          for this task

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

                          - **402**: Insufficient credits - Account doesn't have
                          enough credits for this operation

                          - **404**: Not found - Requested resource or endpoint
                          doesn't exist

                          - **409**: Conflict - Cover record already exists

                          - **422**: Validation error - Request parameters
                          failed validation checks

                          - **429**: Rate limited - Your call frequency is too
                          high. Please try again later.

                          - **455**: Service unavailable - System currently
                          undergoing maintenance

                          - **500**: Server error - Unexpected error occurred
                          while processing request

                          Build failed - Cover image generation failed
                      msg:
                        type: string
                        description: Error message when code != 200
                        example: success
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    description: Status code
                    example: 200
                  msg:
                    type: string
                    description: Status message
                    example: success
                  data:
                    type: object
                    properties:
                      taskId:
                        type: string
                        description: Task ID
                        example: 21aee3c3c2a01fa5e030b3799fa4dd56
              example:
                code: 200
                msg: success
                data:
                  taskId: 21aee3c3c2a01fa5e030b3799fa4dd56
        '500':
          $ref: '#/components/responses/Error'
      callbacks:
        onCoverGenerated:
          '{$request.body#/callBackUrl}':
            post:
              summary: Cover generation completion callback
              description: >-
                When Cover generation is complete, the system will send a POST
                request to the provided callback URL to notify results
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                        - type: object
                          properties:
                            code:
                              type: integer
                              enum:
                                - 200
                                - 500
                              description: >-
                                Response status code


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

                                - **500**: Internal error - Please try again
                                later.
                            msg:
                              type: string
                              description: Error message when code != 200
                              example: success
                      type: object
                      required:
                        - code
                        - msg
                        - data
                      properties:
                        code:
                          type: integer
                          description: Status code, 200 indicates success
                          example: 200
                        msg:
                          type: string
                          description: Status message
                          example: success
                        data:
                          type: object
                          required:
                            - taskId
                            - images
                          properties:
                            taskId:
                              type: string
                              description: Unique identifier of the generation task
                              example: 21aee3c3c2a01fa5e030b3799fa4dd56
                            images:
                              type: array
                              items:
                                type: string
                              description: >-
                                Array of accessible cover image URLs, valid for
                                14 days
                              example:
                                - >-
                                  https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png
                                - >-
                                  https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png
              responses:
                '200':
                  description: Callback received successfully
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