> ## 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.

# 生成歌词

> 使用AI模型创建歌词内容，无需生成音频轨道。

### 使用指南

* 此接口仅根据您的提示生成歌词内容
* 将返回多个歌词变体供您选择
* 生成的歌词通常包含歌曲结构标记（例如\[Verse]、\[Chorus]）

### 开发者注意事项

1. 生成的歌词将保留15天
2. 回调只有一个阶段：complete（生成完成）
3. 当您只需要创建歌词而不需要音乐时使用此接口
4. 结果可以作为自定义模式下生成音乐接口的输入


## OpenAPI

````yaml cn/suno-api/suno-api-cn.json POST /api/v1/lyrics
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/lyrics:
    post:
      summary: 生成歌词
      operationId: generate-lyrics
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - callBackUrl
              properties:
                prompt:
                  type: string
                  description: |-
                    详细描述期望的歌词内容。  
                    - 具体说明您想要的主题、情绪、风格和歌曲结构。  
                    - 提示越详细，生成的歌词就越符合您的构想。  
                    - 最大字符限制为200字符。
                  example: 一首关于城市宁静夜晚的歌
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    接收歌词生成结果的URL。  

                    - 必填。  

                    - 与音乐生成不同，歌词回调只有一个阶段：`complete`（生成完成）。

                    - 详细的回调格式和实现指南，请参见
                    [歌词生成回调](https://docs.sunoapi.org/cn/suno-api/generate-lyrics-callbacks)

                    - 或者，您也可以使用获取歌词生成详情接口来轮询任务状态
                  example: https://api.example.com/callback
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ApiResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: 任务ID，用于后续查询任务状态
                            example: 5c79****be8e
        '500':
          $ref: '#/components/responses/Error'
      callbacks:
        audioLyricsGenerated:
          '{$request.body#/callBackUrl}':
            post:
              description: |-
                当歌词生成完成时，系统会调用此回调通知结果。

                ### 回调示例
                ```json
                {
                  "code": 200,
                  "msg": "All generated successfully.",
                  "data": {
                    "callbackType": "complete",
                    "taskId": "11dc****8b0f",
                    "data": [
                      {
                        "text": "[Verse]\n我穿越城市黑暗夜\n心中燃烧梦想的烈火",
                        "title": "钢铁侠",
                        "status": "complete",
                        "errorMessage": ""
                      },
                      {
                        "text": "[Verse]\n风在呼唤我名字\n钢铁盔甲闪得刺眼",
                        "title": "钢铁侠",
                        "status": "complete",
                        "errorMessage": ""
                      }
                    ]
                  }
                }
                ```
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        code:
                          type: integer
                          description: 状态码
                          example: 200
                        msg:
                          type: string
                          description: 返回消息
                          example: All generated successfully
                        data:
                          type: object
                          properties:
                            callbackType:
                              type: string
                              description: 回调类型，固定为 complete
                              enum:
                                - complete
                              example: complete
                            taskId:
                              type: string
                              description: 任务ID
                            data:
                              type: array
                              description: 生成的歌词列表
                              items:
                                type: object
                                properties:
                                  text:
                                    type: string
                                    description: 歌词内容
                                  title:
                                    type: string
                                    description: 歌词标题
                                  status:
                                    type: string
                                    description: 生成状态
                                    enum:
                                      - complete
                                      - failed
                                  errorMessage:
                                    type: string
                                    description: 错误信息，仅当状态为 failed 时有值
              responses:
                '200':
                  description: 回调接收成功
              method: post
              type: path
            path: '{$request.body#/callBackUrl}'
components:
  schemas:
    ApiResponse:
      type: object
      properties:
        code:
          type: integer
          description: |-
            # 状态码说明

            - ✅ 200 - 请求成功
            - ⚠️ 400 - 参数错误
            - ⚠️ 401 - 没有访问权限
            - ⚠️ 404 - 请求方式或者路径错误
            - ⚠️ 405 - 调用超过限制
            - ⚠️ 413 - 主题或者prompt过长
            - ⚠️ 429 - 积分不足
            - ⚠️ 430 - 您的调用频率过高，请稍后再试。
            - ⚠️ 455 - 网站维护
            - ❌ 500 - 服务器异常
          example: 200
          enum:
            - 200
            - 400
            - 401
            - 404
            - 405
            - 413
            - 429
            - 430
            - 455
            - 500
        msg:
          type: string
          description: 当 code != 200 时，展示错误信息
          example: success
  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 泄露，请立即在管理页面重置

````