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

# 创建音乐视频

> 为音乐曲目生成带有可视化效果的MP4视频。

### 用法指南

* 此接口为您的音乐曲目创建MP4视频格式的可视化表示。
* 需要同时提供 `taskId` 和 `audioId` 来识别具体曲目。
* 可选的 `author` 和 `domainName` 参数可用于添加品牌信息。

### 开发者说明

1. 生成的视频文件将保留15天。
2. 视频包含与音乐同步的视觉效果。
3. 此功能非常适合社交媒体分享、音乐推广或创建视觉内容。
4. 视频保持与原始音轨相同的音频质量。


## OpenAPI

````yaml cn/suno-api/suno-api-cn.json POST /api/v1/mp4/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/mp4/generate:
    post:
      summary: 创建音乐视频
      operationId: create-music-video
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - taskId
                - audioId
                - callBackUrl
              properties:
                taskId:
                  type: string
                  description: |-
                    音乐生成任务的任务ID。
                    - 必填。用于标识包含待转换为视频的音频的任务。
                    - 需要同时提供 `taskId` 和 `audioId` 以识别确切的音轨。
                  example: taskId_774b9aa0422f
                audioId:
                  type: string
                  description: |-
                    要转换为视频的具体音轨ID。
                    - 必填。用于标识任务中要转换的具体音轨。
                    - 需要同时提供 `taskId` 和 `audioId` 以识别确切的音轨。
                  example: e231****-****-****-****-****8cadc7dc
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    接收视频生成完成通知的URL。

                    - 必填。

                    - 回调将包含生成的MP4视频的单个可下载URL。

                    - 详细的回调格式和实现指南，请参见
                    [音乐视频生成回调](https://docs.sunoapi.org/cn/suno-api/create-music-video-callbacks)

                    - 或者，您也可以使用获取音乐视频详情接口来轮询任务状态
                  example: https://api.example.com/callback
                author:
                  type: string
                  maxLength: 50
                  description: |-
                    显示在视频上的艺术家或创作者名称。
                    - 可选。
                    - 将在视频中显著展示，通常在开头。
                    - 最长50个字符。
                  example: Suno Artist
                domainName:
                  type: string
                  maxLength: 50
                  description: |-
                    作为水印显示的网站或品牌。
                    - 可选。
                    - 将作为微妙的水印出现在视频底部。
                    - 最长50个字符。
                  example: music.example.com
      responses:
        '200':
          description: 请求成功
          content:
            application/json:
              schema:
                allOf:
                  - type: object
                    properties:
                      code:
                        type: integer
                        enum:
                          - 200
                          - 400
                          - 401
                          - 404
                          - 405
                          - 409
                          - 413
                          - 429
                          - 430
                          - 455
                          - 500
                        description: |-
                          # 状态码

                          - ✅ 200 - 请求成功
                          - ⚠️ 400 - 无效参数
                          - ⚠️ 401 - 未授权访问
                          - ⚠️ 404 - 无效的请求方法或路径
                          - ⚠️ 405 - 超出速率限制
                          - ⚠️ 409 - 冲突 - Mp4 记录已存在
                          - ⚠️ 413 - 主题或提示词过长
                          - ⚠️ 429 - 积分不足
                          - ⚠️ 430 - 您的调用频率过高，请稍后重试
                          - ⚠️ 455 - 系统维护中
                          - ❌ 500 - 服务器错误
                      msg:
                        type: string
                        description: 当 code != 200 时，展示错误信息
                        example: success
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          taskId:
                            type: string
                            description: 任务ID，用于后续查询任务状态
                            example: taskId_774b9aa0422f
        '500':
          $ref: '#/components/responses/Error'
      callbacks:
        mp4Generated:
          '{$request.body#/callBackUrl}':
            post:
              description: |-
                当MP4视频生成完成时，系统会调用此回调通知结果。

                ### 回调示例
                ```json
                {
                  "code": 200,
                  "msg": "MP4 generated successfully.",
                  "data": {
                    "task_id": "taskId_774b9aa0422f",
                    "video_url": "https://example.com/videos/video_847715e66259.mp4"
                  }
                }
                ```
              requestBody:
                content:
                  application/json:
                    schema:
                      type: object
                      properties:
                        code:
                          type: integer
                          description: 状态码
                          example: 200
                        msg:
                          type: string
                          description: 返回消息
                          example: MP4 generated successfully.
                        data:
                          type: object
                          properties:
                            task_id:
                              type: string
                              description: 任务ID
                            video_url:
                              type: string
                              description: 生成的MP4视频URL
              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 泄露，请立即在管理页面重置

````