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

# 生成音乐封面

> 为生成的音乐创建个性化封面图像。

### 使用指南

* 使用此接口为生成的音乐创建个性化封面图像
* 需要原始音乐任务的taskId
* 每个音乐任务只能生成一次封面；重复请求将返回现有的taskId
* 完成后将通过回调URL通知结果

### 参数详情

* `taskId` 标识原始音乐生成任务的唯一标识符
* `callBackUrl` 接收完成通知的回调地址

### 开发者说明

* 封面图像文件URL将保留14天
* 如果已为此音乐任务生成了封面，将返回400状态码和现有taskId
* 建议在音乐生成完成后调用此接口
* 通常生成2种不同风格的图像供选择


## OpenAPI

````yaml cn/suno-api/suno-api-cn.json POST /api/v1/suno/cover/generate
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/suno/cover/generate:
    post:
      summary: 创建Suno封面任务
      description: |-
        基于原始音乐任务生成个性化封面图像。

        ### 使用指南
        - 使用此接口为生成的音乐创建个性化封面图像
        - 需要原始音乐任务的taskId
        - 每个音乐任务只能生成一次封面；重复请求将返回现有的taskId
        - 完成后将通过回调URL通知结果

        ### 参数详情
        - `taskId` 标识原始音乐生成任务的唯一标识符
        - `callBackUrl` 接收完成通知的回调地址

        ### 开发者说明
        - 封面图像文件URL将保留14天
        - 如果已为此音乐任务生成了封面，将返回400状态码和现有taskId
        - 建议在音乐生成完成后调用此接口
      operationId: generate-cover
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
                - callBackUrl
              properties:
                taskId:
                  type: string
                  description: 原始音乐任务ID，应该是音乐生成接口返回的taskId。
                  example: 73d6128b3523a0079df10da9471017c8
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    用于接收封面生成任务完成更新的URL地址。所有封面生成请求都需要此参数。


                    - 当封面生成完成时，系统将向此URL发送POST请求，包括任务状态和结果

                    - 您的回调端点应该能够接受包含封面图像URL的JSON负载

                    -
                    有关详细回调格式和实施指南，请参阅[封面生成回调](https://docs.sunoapi.org/cn/suno-api/cover-suno-callbacks)

                    - 或者，您可以使用获取封面详情接口来轮询任务状态
                  example: https://api.example.com/callback
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 400
                          - 401
                          - 402
                          - 404
                          - 409
                          - 422
                          - 429
                          - 455
                          - 500
                        description: |-
                          响应状态码

                          - **200**: 成功 - 请求处理成功
                          - **400**: 验证错误 - 此任务已生成封面
                          - **401**: 未授权 - 身份验证凭据缺失或无效
                          - **402**: 积分不足 - 账户没有足够的积分执行此操作
                          - **404**: 未找到 - 请求的资源或端点不存在
                          - **409**: 冲突 - 封面记录已存在
                          - **422**: 验证错误 - 请求参数验证检查失败
                          - **429**: 速率限制 - 您的调用频率过高。请稍后再试。
                          - **455**: 服务不可用 - 系统当前正在维护
                          - **500**: 服务器错误 - 处理请求时发生意外错误
                          构建失败 - 封面图像生成失败
                      msg:
                        type: string
                        description: 代码 != 200 时的错误消息
                        example: success
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                    description: 状态码
                    example: 200
                  msg:
                    type: string
                    description: 状态消息
                    example: success
                  data:
                    type: object
                    properties:
                      taskId:
                        type: string
                        description: 任务ID
                        example: 21aee3c3c2a01fa5e030b3799fa4dd56
              example:
                code: 200
                msg: success
                data:
                  taskId: 21aee3c3c2a01fa5e030b3799fa4dd56
        '500':
          $ref: '#/components/responses/Error'
      callbacks:
        onCoverGenerated:
          '{$request.body#/callBackUrl}':
            post:
              summary: 封面生成完成回调
              description: 当封面生成完成时，系统将向提供的回调URL发送POST请求以通知结果
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      allOf:
                        - type: object
                          properties:
                            code:
                              type: integer
                              enum:
                                - 200
                                - 500
                              description: |-
                                响应状态码

                                - **200**: 成功 - 请求处理成功
                                - **500**: 内部错误 - 请稍后再试。
                            msg:
                              type: string
                              description: 代码 != 200 时的错误消息
                              example: success
                      type: object
                      required:
                        - code
                        - msg
                        - data
                      properties:
                        code:
                          type: integer
                          description: 状态码，200表示成功
                          example: 200
                        msg:
                          type: string
                          description: 状态消息
                          example: success
                        data:
                          type: object
                          required:
                            - taskId
                            - images
                          properties:
                            taskId:
                              type: string
                              description: 生成任务的唯一标识符
                              example: 21aee3c3c2a01fa5e030b3799fa4dd56
                            images:
                              type: array
                              items:
                                type: string
                              description: 可访问的封面图像URL数组，有效期为14天
                              example:
                                - >-
                                  https://tempfile.aiquickdraw.com/s/1753958521_6c1b3015141849d1a9bf17b738ce9347.png
                                - >-
                                  https://tempfile.aiquickdraw.com/s/1753958524_c153143acc6340908431cf0e90cbce9e.png
              responses:
                '200':
                  description: 回调接收成功
              method: post
              type: path
            path: '{$request.body#/callBackUrl}'
components:
  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 泄露，请立即在管理页面重置

````