Qwen-Audio-TTS client events

run-task

Starts a speech synthesis task and configures the model, voice, sample rate, and other parameters. When to send: Immediately after the WebSocket connection is established. Response event: The server returns a task-started event. Wait for this event before sending subsequent commands.

{
    "header": {
        "action": "run-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "tts",
        "function": "SpeechSynthesizer",
        "model": "qwen-audio-3.0-tts-flash",
        "parameters": {
            "text_type": "PlainText",
            "voice": "longanlingxi",
            "format": "mp3",
            "sample_rate": 22050,
            "volume": 50,
            "rate": 1.0,
            "pitch": 1.0,
            "enable_ssml": false
        },
        "input": {}
    }
}

Parameter	Type	Description
header	object	(required)
header.action	string	(required) The command type. Set to `run-task`.
header.task_id	string	(required) 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.
header.streaming	string	(required) Set to `duplex`.
payload	object	(required)
payload.task_group	string	(required) The task group. Set to `audio`.
payload.task	string	(required) The task type. Set to `tts`.
payload.function	string	(required) The function type. Set to `SpeechSynthesizer`.
payload.model	string	(required) The model name.
payload.input	object	(required) Set to an empty object `{}`. Send the text to synthesize through the continue-task command.
payload.parameters	object	(required) Speech synthesis parameters.
payload.parameters.text_type	string	(required) Set to `PlainText`.
payload.parameters.voice	string	(required) 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
payload.parameters.format	string	(optional) The audio encoding format. Valid values: pcm wav mp3 (default) opus
payload.parameters.sample_rate	integer	(optional) The audio sample rate in Hz. Valid values: 8000, 16000, 22050 (default), 24000, 44100, 48000.
payload.parameters.volume	integer	(optional) The volume level. Default value: 50. Valid values: [0, 100].
payload.parameters.rate	float	(optional) The speech rate. Default value: 1.0. Valid values: [0.5, 2.0].
payload.parameters.pitch	float	(optional) The pitch. Default value: 1.0. Valid values: [0.5, 2.0].
payload.parameters.bit_rate	integer	(optional) 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].
payload.parameters.enable_ssml	boolean	(optional) 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.
payload.parameters.word_timestamp_enabled	boolean	(optional) 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.
payload.parameters.seed	integer	(optional) 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].
payload.parameters.language_hints	array[string]	(optional) Tip: - 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. 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 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
payload.parameters.instruction	string	(optional) Sets an instruction to control dialect, emotion, or voice character during synthesis. For detailed usage, see Instruction control.
payload.parameters.enable_aigc_tag	boolean	(optional) 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.
payload.parameters.aigc_propagator	string	(optional) Sets the `ContentPropagator` field in the AIGC watermark, identifying the content propagator. Takes effect only when `enable_aigc_tag` is `true`. Default value: QwenCloud account ID.
payload.parameters.aigc_propagate_id	string	(optional) 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.
payload.parameters.hot_fix	object	(optional) 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. Example:

"hot_fix": {
  "pronunciation": [
    {"weather": "tian1 qi4"}
  ],
  "replace": [
    {"today": "gold day"}
  ]
}

continue-task

Sends the text to synthesize. The text can be sent all at once or in multiple segments. When to send: After receiving the task-started event from the server. Limits:

Maximum of 20,000 characters per message
Maximum of 200,000 characters cumulatively
The send interval must not exceed 23 seconds; otherwise, the connection times out.

{
    "header": {
        "action": "continue-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {
            "text": "Before my bed, moonlight shines bright, I suspect it's frost upon the ground."
        }
    }
}

Parameter	Type	Description
header.action	string	(required) The command type. Set to `continue-task`.
header.streaming	string	(required) Set to `duplex`.
header.task_id	string	(required) The task ID in UUID format. Must match the task_id in run-task.
payload.input	object	(required) Contains the text to synthesize.
payload.text	string	(required) The text to synthesize. Maximum of 20,000 characters per message and 200,000 characters cumulatively.

finish-task

Notifies the server that all text has been sent and requests task completion. When to send: Immediately after all text has been sent. Response event: The server returns a task-finished event.

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {}
    }
}

Cancel task example :

{
    "header": {
        "action": "finish-task",
        "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
        "streaming": "duplex"
    },
    "payload": {
        "input": {
            "directive": "cancel"
        }
    }
}

Parameter	Type	Description
header.action	string	(required) The command type. Set to `finish-task`.
header.task_id	string	(required) The task ID in UUID format. Must match the task_id in run-task.
header.streaming	string	(required) Set to `duplex`.
payload.input	object	(required) Set to `{}` for normal task completion. Include `directive` to cancel the current synthesis turn.
payload.directive	string	(optional) 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.

​run-task

​continue-task

​finish-task

run-task

continue-task

finish-task