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

# 生成声音

> 创建 Sounds 生成任务，支持循环、BPM、调性和歌词字幕抓取等参数。

用于创建声音生成任务（Sounds Task）。支持设置循环播放、节奏（BPM）、调性（Key）以及歌词字幕抓取等能力。

## 🚀 使用指南

* 使用该接口可以基于输入的 `prompt` 生成对应的音频内容。
* 支持设置循环播放效果，适用于背景音乐、环境音等场景。
* 支持指定 BPM（每分钟节拍数）和 Key（调性），便于控制生成结果的风格。
* 可选开启歌词字幕抓取，便于后续展示或处理歌词内容。
* 支持通过回调地址异步接收任务完成通知。

## 📌 适用场景

* 🎧 背景音乐创作
* 🎮 游戏音效或循环环境声生成
* 🌐 音频内容平台与创作工具集成


## OpenAPI

````yaml /cn/suno-api/suno-api-cn.json POST /api/v1/generate/sounds
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/generate/sounds:
    post:
      summary: 生成声音
      description: |-
        用于创建声音生成任务（Sounds Task）。支持设置循环播放、节奏（BPM）、调性（Key）以及歌词字幕抓取等能力。

        ### 使用指南
        - 基于输入 `prompt` 生成对应音频内容
        - 支持循环播放，适用于背景音乐与环境音场景
        - 支持设置 BPM 和 Key，便于控制生成风格
        - 可选开启歌词字幕抓取
        - 支持通过回调地址异步接收完成通知
      operationId: generate-sounds
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
                - model
              properties:
                prompt:
                  type: string
                  description: sounds 任务提示词，最多 500 字符。
                  maxLength: 500
                  example: 轻柔的雨声环境音，带有远处雷声和微风
                model:
                  type: string
                  description: 模型名称。sounds 任务类型仅支持 `V5`。
                  enum:
                    - V5
                  example: V5
                soundLoop:
                  type: boolean
                  description: 是否循环播放。
                  default: false
                  example: false
                soundTempo:
                  type: integer
                  description: BPM（每分钟节拍数），不传则为 Auto。
                  minimum: 1
                  maximum: 300
                  nullable: true
                  example: 120
                soundKey:
                  type: string
                  description: Key（调性），默认 `Any`。
                  default: Any
                  enum:
                    - Any
                    - Cm
                    - C#m
                    - Dm
                    - D#m
                    - Em
                    - Fm
                    - F#m
                    - Gm
                    - G#m
                    - Am
                    - A#m
                    - Bm
                    - C
                    - C#
                    - D
                    - D#
                    - E
                    - F
                    - F#
                    - G
                    - G#
                    - A
                    - A#
                    - B
                  example: Any
                grabLyrics:
                  type: boolean
                  description: 是否抓取歌词字幕。任务完成后可调用接口获取歌词字幕。
                  example: false
                callBackUrl:
                  type: string
                  format: uri
                  description: 回调地址，用于异步接收任务完成通知。
                  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: a1b2****c3d4
        '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://sunoapi.org/api-key) 获取您的 API Key

        ## 使用方式

        在请求头中添加：

        ```
        Authorization: Bearer YOUR_API_KEY
        ```

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

````