Skip to main content

Qwen-Audio-TTS client events

Client event reference for Qwen-Audio-TTS: run-task, continue-task, and finish-task fields, event order, and corresponding server events.

Event flow

  1. Send run-task to start and configure the task, then wait for task-started.
  2. After receiving task-started, send text through continue-task while receiving result-generated events and synthesized audio.
  3. After sending all text, send finish-task and keep receiving remaining results and audio until task-finished arrives. A failed task returns task-failed.
result-generated returns sentence metadata. Audio is transmitted separately as binary frames over WebSocket or through an Audio Track over AOQ. For connection setup, authentication, and audio transport, see WebSocket API or AOQ access.

run-task

Immediately after establishing the connection, the client sends run-task to start a speech synthesis task and set the model, voice, sample rate, and other parameters.
Wait for task-started before sending continue-task. run-task only starts and configures the task. Send the text to synthesize through continue-task.
headerobjectRequired
actionstringRequired
The command type. Set to run-task.
task_idstringRequired
A client-generated task ID in UUID format. This ID correlates subsequent events and must match the task_id in the continue-task and finish-task commands.
streamingstringRequired
Set to duplex.
payloadobjectRequired
task_groupstringRequired
The task group. Set to audio.
taskstringRequired
The task type. Set to tts.
functionstringRequired
The function type. Set to SpeechSynthesizer.
modelstringRequired
The model name.
parametersobjectRequired
Speech synthesis parameters.
text_typestringRequired
Set to PlainText.
voicestringRequired
The voice used for speech synthesis.
  • System voices: See Qwen-Audio-TTS voice list
  • Cloned voices: Custom voices created through voice cloning
  • Custom voices: Custom voices created through voice design
formatstringOptional
The audio encoding format.Valid values:
  • pcm
  • wav
  • mp3 (default)
  • opus
sample_rateintegerOptional
The audio sample rate in Hz.Valid values: 8000, 16000, 22050 (default), 24000, 44100, 48000.
volumeintegerOptional
The volume level.Default value: 50.Valid values: [0, 100].
ratefloatOptional
The speech rate.Default value: 1.0.Valid values: [0.5, 2.0].
pitchfloatOptional
The pitch.Default value: 1.0.Valid values: [0.5, 2.0].
bit_rateintegerOptional
The audio bit rate in kbps. When the audio format is mp3 or opus, use bit_rate to adjust the bit rate.Default value: 32.Valid values: [6, 510].
enable_ssmlbooleanOptional
Specifies whether to enable SSML.Default value: false.
When set to true, only one continue-task command is allowed.
For the SSML usage restrictions (supported models, voices, and APIs), see Limitations.
word_timestamp_enabledbooleanOptional
Specifies whether to enable word-level timestamps.Default value: false.
Available only in streaming output mode. Cloned voices are supported. For supported system voices, see Qwen-Audio-TTS voice list.
seedintegerOptional
A random seed for controlling variation in the synthesis output. When the model version, text, voice, and other parameters are unchanged, using the same seed produces identical results.Default value: 0.Valid values: [0, 65535].
language_hintsarray[string]Optional
For the multilingual and dialect voices of qwen-audio-3.1-tts-flash, this parameter specifies the language or dialect. See multilingual and dialect voice settings for details.
Specifies the target language for speech synthesis to improve output quality.When digit pronunciation, abbreviation expansion, symbol reading, or minority-language synthesis doesn't meet expectations, use this parameter. For example:
  • Unexpected digit pronunciation: "hello, this is 110" is read as "hello, this is one one zero" instead of the expected Chinese pronunciation
  • Inaccurate symbol pronunciation: "@" is read as the Chinese equivalent instead of "at"
  • Poor minor language synthesis quality with unnatural results
  • zh: Chinese
  • en: English
  • fr: French
  • de: German
  • ja: Japanese
  • ko: Korean
  • ru: Russian
  • pt: Portuguese
  • th: Thai
  • id: Indonesian
  • vi: Vietnamese
  • es: Spanish
  • it: Italian
  • ms: Malaysian
  • fil: Filipino
  • ar: Arabic
  • other: Other languages (supported by qwen-audio-3.1-tts-flash) Bulgarian, Dutch, Hungarian, Romanian, Danish, Croatian, Greek, Czech, Norwegian, Swedish, Hindi, Slovak, Finnish, Urdu, Serbian, Mexican Spanish, Lithuanian, Latvian, Turkish, Persian, Hebrew, Mongolian, Slovenian, Azerbaijani, Polish, Catalan, Khmer, Brazilian Portuguese, Lao, Georgian, Afrikaans, Nepali, Belarusian, Malayalam, Luxembourgish, Albanian, Tamil, Sinhala, Telugu, Estonian, Cebuano, Bosnian, Burmese, Armenian, Latin, Icelandic, Maltese, Swahili, Kazakh, Seychellois Creole, Ukrainian.
  • This parameter is an array, but the current version only processes the first element. Pass a single value.
  • This parameter specifies the target language for speech synthesis. It's unrelated to the language of the audio sample used in voice cloning. To set the source language for a cloning task, see the voice cloning API reference.
instructionstringOptional
Sets an instruction to control dialect, emotion, or voice character during synthesis. For detailed usage, see Instruction control.
enable_aigc_tagbooleanOptional
Specifies whether to embed an AIGC watermark in the generated audio. When set to true, the watermark is embedded in audio files of supported formats (wav/mp3/opus).Default value: false.
aigc_propagatorstringOptional
Sets the ContentPropagator field in the AIGC watermark, identifying the content propagator. Takes effect only when enable_aigc_tag is true.Default value: Alibaba Cloud UID.
aigc_propagate_idstringOptional
Sets the PropagateID field in the AIGC watermark, uniquely identifying a specific propagation action. Takes effect only when enable_aigc_tag is true.Default value: The request ID of the current speech synthesis request.
hot_fixobjectOptional
Configures pronunciation corrections and text replacements applied before synthesis.Parameters:
  • pronunciation: Custom pronunciation. Specifies pinyin annotations for words to correct inaccurate default pronunciations.
  • replace: Text replacement. Replaces specified words with target text before synthesis. The replaced text is used as the actual synthesis input.
This example uses pinyin to specify the pronunciation of a Chinese word and replaces text before synthesis.
{
  "hot_fix": {
    "pronunciation": [
      {
        "天气": "tian1 qi4"
      }
    ],
    "replace": [
      {
        "今天": "金天"
      }
    ]
  }
}
enable_markdown_filterbooleanOptional
Whether to enable Markdown filtering. When enabled, the service converts Markdown into text suitable for reading aloud before synthesis.Default: false. Set to true to enable.
inputobjectRequired
Set to an empty object {}. Send the text to synthesize through the continue-task command.
Request:
{
  "header": {
    "action": "run-task",
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "streaming": "duplex"
  },
  "payload": {
    "input": {},
    "task_group": "audio",
    "task": "tts",
    "function": "SpeechSynthesizer",
    "model": "qwen-audio-3.1-tts-flash",
    "parameters": {
      "text_type": "PlainText",
      "voice": "longanhuan_v3.1",
      "format": "mp3",
      "sample_rate": 22050
    }
  }
}
Response:
{
  "header": {
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "task_uuid": "573f4010c82040ad90d2a15e7d8afdbd",
    "event": "task-started",
    "attributes": {}
  },
  "payload": {}
}

continue-task

After receiving task-started, the client sends continue-task to submit text for synthesis. Text can be sent all at once or in sequential segments.
headerobjectRequired
actionstringRequired
The command type. Set to continue-task.
task_idstringRequired
The task ID in UUID format. Must match the task_id in run-task.
streamingstringRequired
Set to duplex.
payloadobjectRequired
inputobjectRequired
Contains the text to synthesize.
textstringRequired
The text to synthesize. Maximum of 20,000 characters per message and 200,000 characters cumulatively.
The send interval must not exceed 23 seconds; otherwise, the connection times out.
Request:
{
  "header": {
    "action": "continue-task",
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "streaming": "duplex"
  },
  "payload": {
    "input": {
      "text": "Welcome to the speech synthesis service."
    }
  }
}
Response:
{
  "header": {
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "event": "result-generated",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {
      "sentence": {
        "index": 0,
        "words": []
      },
      "type": "sentence-begin",
      "original_text": "Welcome to the speech synthesis service.",
      "normalized_text": "Welcome to the speech synthesis service."
    }
  }
}

finish-task

Immediately after sending all text, the client sends finish-task to notify the server that text input is complete and request task completion. To cancel the current synthesis turn, set directive to cancel in input.
After sending finish-task, keep receiving remaining synthesis results and audio until task-finished arrives. When a task is cancelled, the server stops outputting subsequent audio and returns task-finished.
headerobjectRequired
actionstringRequired
The command type. Set to finish-task.
task_idstringRequired
The task ID in UUID format. Must match the task_id in run-task.
streamingstringRequired
Set to duplex.
payloadobjectRequired
inputobjectRequired
Set to {} for normal task completion. Include directive to cancel the current synthesis turn.
directivestringOptional
Controls how the task ends. Currently only cancel is supported. When set to cancel, the current synthesis turn is canceled and the server immediately returns a task-finished event without producing further audio.After cancellation, you can start a new synthesis task on the same WebSocket connection by sending a new run-task event without reconnecting.
  • Normal completion
  • Cancel task
Request:
{
  "header": {
    "action": "finish-task",
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "streaming": "duplex"
  },
  "payload": {
    "input": {}
  }
}
Response:
{
  "header": {
    "task_id": "f604f46b-5329-4520-a767-4ede894e0418",
    "event": "task-finished",
    "attributes": {
      "x-dashscope-inner-response-type": "ws"
    }
  },
  "payload": {
    "output": {},
    "usage": {
      "input_tokens": 7,
      "output_tokens": 30,
      "total_tokens": 37,
      "characters": 40
    }
  }
}