> ## Documentation Index
> Fetch the complete documentation index at: https://docs.api.box/llms.txt
> Use this file to discover all available pages before exploring further.

# 添加伴奏

> 通过为上传的音频文件添加伴奏元素，生成现有音乐曲目的伴奏版本

### 使用指南

* 此接口通过添加伴奏元素来增强现有的音频曲目
* 接受上传的音频文件，并根据您的规格生成伴奏版本
* 上传的音频必须可公开访问且采用支持的格式（MP3、WAV等）

### 参数详情

* **必需字段**：`uploadUrl`、`title`、`negativeTags`、`tags`、`callBackUrl`
* **uploadUrl**：必须是有效的、可公开访问的音频文件URL
* **title**：用作生成的伴奏曲目的标题
* **tags**：描述伴奏曲目所需的风格、情绪和乐器
* **negativeTags**：要从生成的伴奏中排除的音乐风格或特征

### 可选参数

<Note>
  以下字段是此接口可用的可选控制：

  * <b>vocalGender</b> (string)：任何人声元素的首选性别。允许的值：`m`（男性）、`f`（女性）
  * <b>styleWeight</b> (number)：范围0-1的风格权重（建议两位小数）
  * <b>weirdnessConstraint</b> (number)：范围0-1的创意/新颖性约束（建议两位小数）
  * <b>audioWeight</b> (number)：范围0-1的音频一致性相对权重（建议两位小数）
  * <b>model</b> (string)：用于生成的模型版本。可选值：`V4_5PLUS`（默认）、`V5`、`V5_5`
</Note>

### 开发者注意事项

* 回调过程有三个阶段：`text`（文本生成）、`first`（第一轨道完成）、`complete`（所有轨道完成）
* 在某些情况下，`text`和`first`阶段可能被跳过，直接返回`complete`
* 详细回调格式请参见[添加伴奏回调](./add-instrumental-callbacks)
* 使用[获取音乐生成详情](./get-music-generation-details)监控任务进度


## OpenAPI

````yaml cn/suno-api/suno-api-cn.json POST /api/v1/generate/add-instrumental
openapi: 3.0.0
info:
  title: intro
  description: 这是生成音频的API接口文档
  version: 1.0.0
  contact:
    name: 技术支持
    email: support@api.box
servers:
  - url: https://apibox.erweima.ai
    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: 用于账户和积分管理的接口
  - name: Audio Enhancement
    description: 用于增强和修改现有音频的伴奏和人声元素的接口
paths:
  /api/v1/generate/add-instrumental:
    post:
      tags:
        - Audio Enhancement
      summary: 添加伴奏
      operationId: add-instrumental
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - uploadUrl
                - title
                - negativeTags
                - tags
                - callBackUrl
              properties:
                uploadUrl:
                  type: string
                  format: uri
                  description: >-
                    要添加伴奏的上传音乐文件的URL。必须是系统可以访问的有效音频文件URL。上传的音频应该采用支持的格式（MP3、WAV等）。
                  example: https://example.com/music.mp3
                title:
                  type: string
                  description: 音乐曲目的标题。这将作为生成的伴奏曲目的标题。
                  example: 轻松钢琴
                negativeTags:
                  type: string
                  description: 要从生成的伴奏中排除的音乐风格或特征。用于避免伴奏版本中的特定风格或乐器。
                  example: 重金属, 激进鼓声
                tags:
                  type: string
                  description: 伴奏的音乐风格和特征。描述伴奏曲目所需的风格、情绪和乐器。
                  example: 轻松钢琴, 环境音乐, 平静
                callBackUrl:
                  type: string
                  format: uri
                  description: >-
                    当伴奏生成完成时接收任务完成通知的URL。回调过程分为三个阶段：text、first、complete。在某些情况下，text和first阶段可能被跳过，直接返回complete。
                  example: https://api.example.com/callback
                vocalGender:
                  type: string
                  description: 任何人声元素的首选性别。可选。允许的值：m（男性）、f（女性）。
                  enum:
                    - m
                    - f
                  example: m
                styleWeight:
                  type: number
                  description: 风格权重。可选。范围：0-1。建议保留两位小数。
                  minimum: 0
                  maximum: 1
                  multipleOf: 0.01
                  example: 0.61
                weirdnessConstraint:
                  type: number
                  description: 创意/新颖性约束。可选。范围：0-1。建议保留两位小数。
                  minimum: 0
                  maximum: 1
                  multipleOf: 0.01
                  example: 0.72
                audioWeight:
                  type: number
                  description: 音频一致性与其他控制的相对权重。可选。范围：0-1。建议保留两位小数。
                  minimum: 0
                  maximum: 1
                  multipleOf: 0.01
                  example: 0.65
                model:
                  type: string
                  description: 用于生成的模型版本。可选。默认值：V4_5PLUS。
                  enum:
                    - V4_5PLUS
                    - V5
                    - V5_5
                  default: V4_5PLUS
                  example: V4_5PLUS
      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'
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://api.box/api-key) 获取您的 API Key

        ## 使用方式

        在请求头中添加：

        ```
        Authorization: Bearer YOUR_API_KEY
        ```

        > **⚠️ 注意：**
        > - 请妥善保管您的 API Key，不要泄露给他人
        > - 如果怀疑 API Key 泄露，请立即在管理页面重置

````