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/lyrics:
    post:
      summary: Generate Lyrics
      description: >-
        Generate creative lyrics content based on a text prompt.


        ### Usage Guide

        - Use this endpoint to create lyrics for music composition

        - Multiple variations of lyrics will be generated for each request

        - Each generated lyric set includes title and structured verse/chorus
        sections


        ### Parameter Details

        - `prompt` should describe the theme, style, or subject of the desired
        lyrics

        - A detailed prompt yields more targeted and relevant lyrics


        ### Developer Notes

        - Generated lyrics are retained for 14 days

        - Callback occurs once with all generated variations when complete

        - Typically returns 2-3 different lyric variations per request

        - Each lyric set is formatted with standard section markers ([Verse],
        [Chorus], etc.)
      operationId: generate-lyrics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - callBackUrl
              properties:
                prompt:
                  type: string
                  description: >-
                    Description of the desired lyrics content. Be specific about
                    theme, mood, style, or story elements you want in the
                    lyrics. More detailed prompts yield better results. The
                    maximum word limit is 200 words.
                  example: >-
                    A nostalgic song about childhood memories and growing up in
                    a small town
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    The URL to receive lyrics generation task completion
                    updates. Required for all lyrics generation requests.


                    - System will POST task status and results to this URL when
                    lyrics generation completes

                    - Callback includes all generated lyrics variations with
                    titles and structured content

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

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

                    - Alternatively, use the Get Lyrics Details endpoint to poll
                    task status
                  example: https://api.example.com/callback
      responses:
        '200':
          description: Request successful
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 400
                          - 401
                          - 404
                          - 405
                          - 413
                          - 429
                          - 430
                          - 455
                          - 500
                        description: >-
                          Response status code


                          - **200**: Request successful

                          - **400**: Invalid parameters

                          - **401**: Unauthorized access

                          - **404**: Invalid request method or path

                          - **405**: Rate limit exceeded

                          - **413**: Theme or prompt too long

                          - **429**: Insufficient credits

                          - **430**: Your call frequency is too high. Please try
                          again later.

                          - **455**: System maintenance

                          - **500**: Server error
                      msg:
                        type: string
                        description: Error message when code != 200
                        example: success
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: Task ID for tracking task status
                            example: 5c79****be8e
        '500':
          $ref: '#/components/responses/Error'
      callbacks:
        audioLyricsGenerated:
          '{$request.body#/callBackUrl}':
            post:
              description: >-
                System will call this callback when lyrics generation is
                complete.


                ### Callback Example

                ```json

                {
                  "code": 200,
                  "data": {
                    "callbackType": "complete",
                    "data": [
                      {
                        "error_message": "",
                        "status": "complete",
                        "text": "[Verse]\n月光洒满了窗台\n星星跳舞不分开\n夜风偷偷织梦来\n心里压抑全抛开\n\n[Verse 2]\n灯火映在你的眼\n像流星划过了天\n世界静止就一瞬间\n追逐未来不管多远\n\n[Chorus]\n星夜梦中找未来\n跳脱平凡别徘徊\n所有的梦都会盛开\n别害怕追去期待\n\n[Verse 3]\n脚步踏着影子走\n黑夜舞曲化解愁\n无声的美比喧嚣\n随心漂流是追求\n\n[Bridge]\n别让时钟锁住天\n别让怀疑把梦编\n逆着风也会更鲜艳\n陪你走过所有难关\n\n[Chorus]\n星夜梦中找未来\n跳脱平凡别徘徊\n所有的梦都会盛开\n别害怕追去期待",
                        "title": "星夜狂想"
                      },
                      {
                        "error_message": "",
                        "status": "complete",
                        "text": "[Verse]\n天边的云跳舞在风里\n追逐梦想越过山和溪\n每一步都写下新的故事\n心中燃烧永不熄的信念\n\n[Verse 2]\n城市的灯照亮午夜的街\n人潮散开我依旧不妥协\n破碎的梦拼凑新的世界\n每一次失败都是一种体验\n\n[Chorus]\n你好你好未来的自己\n你会感激今天的努力\n跌倒再站起笑对这天地\n燃烧吧青春像烈火不息\n\n[Verse 3]\n窗外的雨敲打着玻璃\n像是为我撑起一片绿地\n彷徨的路透过心的指引\n找到方向我无所畏惧\n\n[Bridge]\n耳边风吹散记忆的灰\n让过去成为最美的点缀\n未来的路上脚步更坚定\n看清自己的模样多么耀眼\n\n[Chorus]\n你好你好未来的自己\n你会感激今天的努力\n跌倒再站起笑对这天地\n燃烧吧青春像烈火不息",
                        "title": "你好"
                      }
                    ],
                    "task_id": "3b66882fde0a5d398bd269cab6d9542b"
                  },
                  "msg": "All generated successfully."
                }

                ```
              requestBody:
                content:
                  application/json:
                    schema:
                      allOf:
                        - type: object
                          properties:
                            code:
                              type: integer
                              enum:
                                - 200
                                - 400
                                - 500
                              description: >-
                                Response status code


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

                                - **400**: Please try rephrasing   with more
                                specific details or using a different approach.

                                Song Description contained artist name

                                Song Description flagged for moderation

                                Unable to generate lyrics from song  
                                description

                                - **500**: Internal Error - Please try again
                                later.
                            msg:
                              type: string
                              description: Error message when code != 200
                              example: success
                        - type: object
                          properties:
                            data:
                              type: object
                              properties:
                                taskId:
                                  type: string
                                  description: Task ID for tracking task status
                                  example: 5c79****be8e
                      type: object
                      properties:
                        code:
                          type: integer
                          description: Status code
                          example: 200
                        msg:
                          type: string
                          description: Response message
                          example: All generated successfully
                        data:
                          type: object
                          properties:
                            callbackType:
                              type: string
                              description: Callback type, fixed as complete
                              enum:
                                - complete
                              example: complete
                            task_id:
                              type: string
                              description: Task ID
                            data:
                              type: array
                              description: Generated lyrics list
                              items:
                                type: object
                                properties:
                                  text:
                                    type: string
                                    description: Lyrics content
                                  title:
                                    type: string
                                    description: Lyrics title
                                  status:
                                    type: string
                                    description: Generation status
                                    enum:
                                      - complete
                                      - failed
                                  error_message:
                                    type: string
                                    description: Error message, valid when status is failed
              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