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

# 提交音乐生成任务

> 提交 QW Music 音乐生成任务。支持文生曲（prompt 模式）和自定义歌词模式。

<Beta />

提交 QW Music 音乐生成任务。支持以下模式：

* **文生曲**（custom\_mode=false）：通过自然语言 prompt 描述生成音乐
* **自定义歌词**（custom\_mode=true）：指定 style + lyrics 精确控制歌词和风格
* **翻唱/改编**：携带 `media` 参考音频，可在上述任一模式下使用


## OpenAPI

````yaml openapi/cn/qwmusic.json POST /qwm/api/v1/services/aigc/audio-generation/audio-synthesis
openapi: 3.1.0
info:
  title: QW Music API
  description: QW Music 官转透传 API，与 DashScope 官方完全一致的请求体 / 返回体 / 路径。网关只做鉴权 + 计费，其余原样透传。
  version: 1.0.0
servers:
  - url: https://api.ttapi.io
security: []
paths:
  /qwm/api/v1/services/aigc/audio-generation/audio-synthesis:
    post:
      summary: 提交音乐生成任务
      description: 提交 QW Music 音乐生成任务。支持文生曲（prompt 模式）和自定义歌词模式。
      operationId: qwmAudioSynthesis
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AudioSynthesisRequest'
      responses:
        '200':
          description: 提交成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AudioSynthesisResponse'
components:
  schemas:
    AudioSynthesisRequest:
      type: object
      required:
        - model
      properties:
        model:
          type: string
          description: 模型名称。固定值：`pre-qwen-music-async-dev`。
          default: pre-qwen-music-async-dev
          example: pre-qwen-music-async-dev
        input:
          type: object
          description: 输入信息。根据 custom_mode 不同，必填字段不同。
          properties:
            prompt:
              type: string
              description: 自然语言提示词。custom_mode=false 时必填。
            lyrics:
              type: string
              description: >-
                歌词内容。custom_mode=true 时必填，支持 `[intro]`、`[chorus]`、`[inst]`
                等段落标记。
            style:
              type: string
              description: 风格描述。custom_mode=true 时必填。
            media:
              type: array
              description: 参考音频列表。携带 media 即为翻唱/改编模式，与 custom_mode 无关。
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: 参考音频类型。固定值：`melody`。
                    enum:
                      - melody
                  url:
                    type: string
                    description: 参考音频 URL。时长 ≤10 分钟，文件大小 ≤100MB。
        parameters:
          type: object
          description: 生成参数。
          properties:
            custom_mode:
              type: boolean
              description: >-
                自定义歌词模式。false（默认）为提示词模式，仅需 prompt；true 为自定义歌词模式，需 style +
                lyrics。
              default: false
            return_candidate_audio:
              type: boolean
              description: 是否返回次优音频。
            return_post_info:
              type: boolean
              description: 是否返回 refine 后的 style/lyrics。
            output_audio_settings:
              type: object
              description: 输出音频设置。
              properties:
                format:
                  type: string
                  description: 输出音频格式。
                  enum:
                    - wav
                    - mp3
                    - flac
                  default: wav
                sample_rate:
                  type: integer
                  description: 采样率。
                  default: 48000
        hook_url:
          type: string
          description: 回调地址（网关扩展字段，官方无此字段）。任务完成后网关会回调该地址，转发官方前会剔除此字段。
    AudioSynthesisResponse:
      type: object
      properties:
        request_id:
          type: string
          description: 请求 ID。
        output:
          type: object
          properties:
            task_id:
              type: string
              description: 任务 ID，用于后续查询。
            task_status:
              type: string
              description: 任务状态。
              enum:
                - PENDING
                - RUNNING
                - SUCCEEDED
                - FAILED

````