Use the Java SDK to call the Qwen-Audio-TTS speech synthesis API in non-streaming or streaming mode.
Prerequisites
- An Obtain an API key, configured as an environment variable
- The DashScope Java SDK, version 2.22.15 or later. Install the latest version.
HttpSpeechSynthesizer class
Package: com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesizer
Description: HTTP-based speech synthesis that supports non-streaming and streaming modes.
Constructor
DASHSCOPE_API_KEY environment variable. If that variable is not set, it falls back to Constants.apiKey.
callAndReturnAudio() — non-streaming (returns audio data)
Method signature:
| Parameter | Type | Description |
|---|---|---|
param | HttpSpeechSynthesisParam | The speech synthesis parameter object that contains model, text, voice, and other configurations. |
ByteBuffer containing the complete audio data. Call remaining() to get the audio size in bytes.
call() — non-streaming (returns audio URL)
Method signature:
| Parameter | Type | Description |
|---|---|---|
param | HttpSpeechSynthesisParam | The speech synthesis parameter object. |
HttpSpeechSynthesisResult object. Call getAudioInfo().getUrl() to get the audio download URL. The URL expires after a fixed period. Call getAudioInfo().getExpiresAt() to get the expiration time.
streamCall() — streaming
Method signature:
| Parameter | Type | Description |
|---|---|---|
param | HttpSpeechSynthesisParam | The speech synthesis parameter object. |
callback | ResultCallback<HttpSpeechSynthesisResult> | The callback object. Implement onEvent (receives audio chunks), onComplete (synthesis finished), and onError (error handling). |
com.alibaba.dashscope.common.ResultCallback is a generic callback interface provided by the DashScope SDK. Implement the following three methods:
| Method | Parameter | Description |
|---|---|---|
onEvent | HttpSpeechSynthesisResult result | Triggered on each audio chunk. Call result.hasAudioData() to check for audio data and result.getAudioDataSize() to get the chunk size. |
onComplete | None | Triggered when synthesis completes and all audio chunks have been received. |
onError | Exception e | Triggered on synthesis error. Call e.getMessage() to get the error details. |
HttpSpeechSynthesisParam class
Package: com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesisParam
Use the Builder pattern to construct parameter objects.
Some parameters don't have dedicated Builder methods. Set them using the parameter(String key, Object value) method or the parameters(Map<String, Object>) method inherited from the parent class.
| Method | Type | Required | Description |
|---|---|---|---|
| model(String) | String | Yes | The speech synthesis model. |
| text(String) | String | Yes | The text to synthesize. SSML and LaTeX format inputs are supported. Replace the text content with the corresponding format.
|
| voice(String) | String | Yes | The voice for synthesis. Valid values:
|
| format(String) | String | No | The audio format. Default value: mp3. Valid values:
|
| sampleRate(int) | int | No | The audio sample rate in Hz. Valid values: 8000, 16000, 22050 (default), 24000, 44100, 48000. |
| volume(int) | int | No | The volume level. Default value: 50. Valid values: [0, 100]. |
| rate(float) | float | No | The speech rate. Default value: 1.0. Valid values: [0.5, 2.0]. |
| pitch(float) | float | No | The pitch. Default value: 1.0. Valid values: [0.5, 2.0]. |
enable_ssml | boolean | No | Enables SSML. When set to true, pass SSML-formatted text in the text parameter. For supported SSML tags and usage, see SSML. For the SSML usage restrictions (supported models, voices, and APIs), see Limitations. Default: false. Set enable_ssml using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 1 below See Example 2 below |
word_timestamp_enabled | boolean | No | 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. Set word_timestamp_enabled using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 3 below See Example 4 below |
seed | int | No | The random seed for synthesis. Different seeds produce different outputs. With identical model version, text, voice, and other parameters, the same seed reproduces the same output. Default value: 0. Valid values: [0, 65535]. Set seed using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 5 below See Example 6 below |
language_hints | List | No | Tip: - This parameter is an array, but the current version processes only the first element. Pass a single value.
language_hints using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 7 below See Example 8 below |
instruction | String | No | An instruction that controls the synthesis behavior, such as dialect, emotion, or role. For usage details, see Non-real-time speech synthesis. Set instruction using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 9 below See Example 10 below |
bit_rate | int | No | The audio bitrate in kbps. Default value: 32. Valid values: [6, 510]. Tip: This parameter is supported only when format is set to opus. Set bit_rate using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 11 below See Example 12 below |
enable_aigc_tag | boolean | No | 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. Set enable_aigc_tag using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 13 below See Example 14 below |
aigc_propagator | String | No | 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. Set aigc_propagator using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 15 below See Example 16 below |
aigc_propagate_id | String | No | 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. Set aigc_propagate_id using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 17 below See Example 18 below |
hot_fix | Map | No | Text hot-fix configuration. Customizes the pronunciation of specified words or substitutes text before speech synthesis. Parameters:
hot_fix using the HttpSpeechSynthesisParam instance's parameter method or parameters method: See Example 20 below See Example 21 below |
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Using parameter
Using parameters
Code examples
The following examples show non-streaming and streaming calls using the Qwen-Audio-TTS speech synthesis API. Before running the examples, set the DASHSCOPE_API_KEY environment variable.
Use a voice that matches the model and supports the target language. When switching models, update the voice accordingly. See Qwen-Audio-TTS voice list.
- Non-streaming
- Streaming