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

# Submit Music Generation Task

> Submit a QW Music generation task. Supports text-to-music (prompt mode) and custom lyrics mode.

<Beta />

Submit a QW Music generation task. Supports the following modes:

* **Text-to-music** (custom\_mode=false): Generate music via natural language prompt
* **Custom lyrics** (custom\_mode=true): Specify style + lyrics for precise control
* **Cover/Remix**: Carry `media` reference audio, usable in either mode above


## OpenAPI

````yaml openapi/en/qwmusic.json POST /qwm/api/v1/services/aigc/audio-generation/audio-synthesis
openapi: 3.1.0
info:
  title: QW Music API
  description: >-
    QW Music passthrough API, fully consistent with DashScope official
    request/response bodies and paths. The gateway only handles authentication
    and billing; everything else is passed through as-is.
  version: 1.0.0
servers:
  - url: https://api.ttapi.io
security: []
paths:
  /qwm/api/v1/services/aigc/audio-generation/audio-synthesis:
    post:
      summary: Submit Music Generation Task
      description: >-
        Submit a QW Music generation task. Supports text-to-music (prompt mode)
        and custom lyrics mode.
      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: 'Model name. Fixed value: `pre-qwen-music-async-dev`.'
          default: pre-qwen-music-async-dev
          example: pre-qwen-music-async-dev
        input:
          type: object
          description: Input information. Required fields vary based on custom_mode.
          properties:
            prompt:
              type: string
              description: Natural language prompt. Required when custom_mode=false.
            lyrics:
              type: string
              description: >-
                Lyrics content. Required when custom_mode=true, supports section
                markers like `[intro]`, `[chorus]`, `[inst]`.
            style:
              type: string
              description: Style description. Required when custom_mode=true.
            media:
              type: array
              description: >-
                Reference audio list. Carrying media enables cover/remix mode,
                independent of custom_mode.
              items:
                type: object
                properties:
                  type:
                    type: string
                    description: 'Reference audio type. Fixed value: `melody`.'
                    enum:
                      - melody
                  url:
                    type: string
                    description: Reference audio URL. Duration ≤10 min, file size ≤100MB.
        parameters:
          type: object
          description: Generation parameters.
          properties:
            custom_mode:
              type: boolean
              description: >-
                Custom lyrics mode. false (default) for prompt mode requiring
                only prompt; true for custom lyrics mode requiring style +
                lyrics.
              default: false
            return_candidate_audio:
              type: boolean
              description: Whether to return the secondary best audio.
            return_post_info:
              type: boolean
              description: Whether to return refined style/lyrics.
            output_audio_settings:
              type: object
              description: Output audio settings.
              properties:
                format:
                  type: string
                  description: Output audio format.
                  enum:
                    - wav
                    - mp3
                    - flac
                  default: wav
                sample_rate:
                  type: integer
                  description: Sample rate.
                  default: 48000
        hook_url:
          type: string
          description: >-
            Callback URL (gateway extension field, not in official API). The
            gateway will call this URL upon task completion and strips this
            field before forwarding to the official API.
    AudioSynthesisResponse:
      type: object
      properties:
        request_id:
          type: string
          description: Request ID.
        output:
          type: object
          properties:
            task_id:
              type: string
              description: Task ID, used for subsequent queries.
            task_status:
              type: string
              description: Task status.
              enum:
                - PENDING
                - RUNNING
                - SUCCEEDED
                - FAILED

````