BRASILTradução de apoio para consulta. Código e identificadores técnicos preservados. Consultar referência original ↗
Síntese de fala
Qwen3-TTS Referência da API
O SDK DashScope Python usa MultiModalConversation em vez de SpeechSynthesizer. O uso e os parâmetros são idênticos.
OpenAPI
openapi: 3.1.0
info:
title: CosyVoice Speech Synthesis API
description: API reference for the Qwen speech synthesis model (CosyVoice, Qwen3-TTS-Flash, cosyvoice-v3.5-plus). Supports streaming and non-streaming output.
version: 1.0.0
servers:
- url: https://maas.qwencloudapi.com
description: Singapore
security:
- bearer: []
paths:
/api/v1/services/aigc/multimodal-generation/generation:
post:
operationId: createTTSSpeech
summary: Synthesize speech (CosyVoice)
description: "Call the Qwen speech synthesis model using the DashScope API. Supports CosyVoice and Qwen3-TTS-Flash model families. Set `X-DashScope-SSE: enable` header for streaming output via HTTP."
security:
- bearer: []
parameters:
- name: X-DashScope-SSE
in: header
required: false
description: Set to `enable` for streaming output via HTTP. The Python SDK uses the `stream` parameter instead. The Java SDK uses the `streamCall` interface instead.
schema:
type: string
enum:
- enable
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/TTSRequest"
responses:
"200":
description: Successful response
content:
application/json:
schema:
$ref: "#/components/schemas/TTSResponse"
x-codeSamples:
- lang: python
label: Non-streaming
source: |-
# Install the latest version of the DashScope SDK
import os
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
text = "Let me recommend a T-shirt to everyone. This one is really super nice. The color is very elegant, and it's also a perfect item to match. Everyone can buy it without hesitation. It's truly beautiful and very forgiving on the figure. No matter what body type you have, it will look great. I recommend everyone to place an order."
# SpeechSynthesizer interface usage: dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
response = dashscope.MultiModalConversation.call(
# To use the instruction control feature, replace the model with cosyvoice-v3.5-plus
model="qwen3-tts-flash",
# If the environment variable is not configured, replace the following line with your API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
text=text,
voice="Cherry"
# To use the instruction control feature, uncomment the following line and replace the model with cosyvoice-v3.5-plus
# instructions='Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.',
# optimize_instructions=True
)
print(response)
- lang: python
label: Streaming
source: |-
# DashScope SDK version 1.24.5 or later
import os
import dashscope
dashscope.base_http_api_url = 'https://maas.qwencloudapi.com/api/v1'
text = "Let me recommend a T-shirt to you. This one is truly stunning. Its color highlights your elegance and makes it an ideal match for any outfit. You can buy it without hesitation - it looks great on everyone. It flatters all body types. Whether you're tall, short, slim, or curvy, this T-shirt suits you perfectly. We highly recommend ordering it."
# Use SpeechSynthesizer as follows: dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
response = dashscope.MultiModalConversation.call(
# To use instruction control, set model to cosyvoice-v3.5-plus
model="qwen3-tts-flash",
# If you have not set an environment variable, replace the next line with: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
text=text,
voice="Cherry",
# To use instruction control, uncomment the lines below and set model to cosyvoice-v3.5-plus
# instructions='Speak quickly with a clear rising intonation, suitable for promoting fashion items.',
# optimize_instructions=True,
stream=True
)
for chunk in response:
print(chunk)
- lang: java
label: Non-streaming
source: |-
// Install the latest version of the DashScope SDK
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
import com.alibaba.dashscope.utils.Constants;
public class Main {
// To use the instruction control feature, replace MODEL with cosyvoice-v3.5-plus
private static final String MODEL = "qwen3-tts-flash";
public static void call() throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.model(MODEL)
// If the environment variable is not configured, replace the following line with your API key: apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.text("Today is a wonderful day to build something people love!")
.voice(AudioParameters.Voice.CHERRY)
.parameter("language_type", "English")
// To use the instruction control feature, uncomment the following line and replace the model with cosyvoice-v3.5-plus
// .parameter("instructions","Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.")
// .parameter("optimize_instructions",true)
.build();
MultiModalConversationResult result = conv.call(param);
System.out.println(JsonUtils.toJson(result));
}
public static void main(String[] args) {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
- lang: java
label: Streaming
source: |-
// DashScope SDK version 2.19.0 or later
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.JsonUtils;
import io.reactivex.Flowable;
import com.alibaba.dashscope.utils.Constants;
public class Main {
// To use instruction control, set MODEL to cosyvoice-v3.5-plus
private static final String MODEL = "qwen3-tts-flash";
public static void streamCall() throws ApiException, NoApiKeyException, UploadFileException {
MultiModalConversation conv = new MultiModalConversation();
MultiModalConversationParam param = MultiModalConversationParam.builder()
.model(MODEL)
// If you have not set an environment variable, replace the next line with: .apiKey("sk-xxx")
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.text("Today is a wonderful day to build something people love!")
.voice(AudioParameters.Voice.CHERRY)
.parameter("language_type", "English")
// To use instruction control, uncomment the lines below and set model to cosyvoice-v3.5-plus
// .parameter("instructions","Speak quickly with a clear rising intonation, suitable for promoting fashion items.")
// .parameter("optimize_instructions",true)
.build();
Flowable<MultiModalConversationResult> result = conv.streamCall(param);
result.blockingForEach(r -> {System.out.println(JsonUtils.toJson(r));
});
}
public static void main(String[] args) {
Constants.baseHttpApiUrl = "https://maas.qwencloudapi.com/api/v1";
try {
streamCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
- lang: bash
label: Non-streaming
source: |-
curl -X POST 'https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3-tts-flash",
"input": {
"text": "Let me recommend a T-shirt to everyone. This one is really super nice. The color is very elegant, and it'\''s also a perfect item to match. Everyone can buy it without hesitation. It'\''s truly beautiful and very forgiving on the figure. No matter what body type you have, it will look great. I recommend everyone to place an order.",
"voice": "Cherry"
}
}'
- lang: bash
label: Streaming
source: |-
curl -X POST 'https://maas.qwencloudapi.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-SSE: enable' \
-d '{
"model": "qwen3-tts-flash",
"input": {
"text": "Let me recommend a T-shirt to you. This one is truly stunning. Its color highlights your elegance and makes it an ideal match for any outfit. You can buy it without hesitation - it looks great on everyone. It flatters all body types. Whether you'\''re tall, short, slim, or curvy, this T-shirt suits you perfectly. We highly recommend ordering it.",
"voice": "Cherry"
}
}'
components:
securitySchemes:
bearer:
type: http
scheme: bearer
description: DashScope API key. Get your API key from [QwenCloud console](https://home.qwencloud.com/api-keys).
schemas:
TTSRequest:
type: object
required:
- model
- input
properties:
model:
type: string
description: The model name.
examples:
- qwen3-tts-flash
- cosyvoice-v3.5-plus
input:
type: object
required:
- text
- voice
description: The input for speech synthesis.
properties:
text:
type: string
description: The text to synthesize. Mixed-language input is supported. CosyVoice supports a maximum input of 512 tokens. Other models support a maximum input of 600 characters.
voice:
type: string
description: The voice to use. See [Supported voices](/developer-guides/speech/voice-list/qwen-tts).
language_type:
type: string
description: "Specify the language of the synthesized audio. Default: `Auto`. When the text is in a single language, specifying the language significantly improves synthesis quality over `Auto`."
default: Auto
enum:
- Auto
- Chinese
- English
- German
- Italian
- Portuguese
- Spanish
- Japanese
- Korean
- French
- Russian
instructions:
type: string
description: "Provide instructions to guide speech synthesis. Defaults to `None`. Length limit: must not exceed 1600 tokens. Supported languages: Chinese and English only. This feature applies only to the cosyvoice-v3.5-plus model series."
optimize_instructions:
type: boolean
description: "Optimize the `instructions` to improve the naturalness and expressiveness of speech synthesis. Default: `false`. When set to `true`, the system semantically enhances and rewrites the content of `instructions` to generate internal instructions better suited for speech synthesis. Enable this for high-quality, fine-grained speech expression. This parameter depends on `instructions` being set. This feature applies only to the cosyvoice-v3.5-plus model series."
default: false
stream:
type: boolean
description: |-
Stream the response. Default: `false`. When `false`, returns the URL of the audio after the model finishes generating. When `true`, outputs Base64-encoded audio data as it is generated.
**Note:** The `stream` parameter is supported only by the Python SDK. To achieve streaming output with the Java SDK, call the `streamCall` interface. To achieve streaming output with HTTP, specify `X-DashScope-SSE` as `enable` in the header.
default: false
TTSResponse:
type: object
properties:
status_code:
type: integer
description: "HTTP status code. Examples: `200` (success), `400` (client error), `401` (unauthorized), `404` (not found), `500` (server error)."
example: 200
request_id:
type: string
description: The unique ID of the request. Use it to locate and troubleshoot issues.
example: 5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx
code:
type: string
description: Displays the error code when the request fails. See [Error codes](/api-reference/preparation/error-messages).
example: ""
message:
type: string
description: Displays the error message when the request fails. See [Error codes](/api-reference/preparation/error-messages).
example: ""
output:
type: object
description: The model's output.
properties:
text:
type: string
nullable: true
description: Always null. Ignore this field.
example: null
choices:
nullable: true
description: Always null. Ignore this field.
example: null
finish_reason:
type: string
description: '`null` while generation is in progress. `"stop"` when the model output ends naturally or a stop condition is triggered.'
enum:
- stop
- null
example: stop
audio:
type: object
description: Audio information from the model's output.
properties:
url:
type: string
description: The URL of the complete audio file, valid for 24 hours. In non-streaming mode, returned directly in the response. In streaming mode, only returned in the last chunk of the SSE stream (intermediate chunks do not contain this field).
example: https://example.oss.aliyuncs.com/audio-result.wav?Expires=1766113409&OSSAccessKeyId=LTAIxxxx&Signature=xxxx
data:
type: string
description: Base64-encoded audio data. In non-streaming mode, this field is always an empty string (use `url` to get the complete audio file). In streaming mode, intermediate chunks contain Base64-encoded audio segments, while the last chunk returns an empty string (use `url` to get the complete audio).
example: ""
id:
type: string
description: The ID corresponding to the audio information output by the model.
example: audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx
expires_at:
type: integer
description: The UNIX timestamp when the URL expires.
example: 1766113409
usage:
type: object
description: Token or character consumption information. CosyVoice returns token consumption. Qwen3-TTS-Flash returns character consumption.
properties:
input_tokens:
type: integer
description: The number of tokens consumed by the input text. For Qwen3-TTS-Flash, this field is always 0.
example: 0
output_tokens:
type: integer
description: The number of tokens consumed by the output audio. For Qwen3-TTS-Flash, this field is always 0.
example: 0
total_tokens:
type: integer
description: The total number of tokens consumed by this request. Only CosyVoice returns this field.
example: 1121
characters:
type: integer
description: The number of characters in the input text. Only Qwen3-TTS-Flash returns this field.
example: 195
input_tokens_details:
type: object
description: Token consumption for the input text. Only CosyVoice returns this field.
properties:
text_tokens:
type: integer
description: The number of tokens consumed by the input text.
example: 76
output_tokens_details:
type: object
description: Token consumption for the output. Only CosyVoice returns this field.
properties:
audio_tokens:
type: integer
description: Tokens consumed by output audio.
example: 1045
text_tokens:
type: integer
description: Tokens consumed by output text (currently fixed at 0).
example: 0
examples:
- summary: Qwen3-TTS-Flash response
value:
status_code: 200
request_id: 5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx
code: ""
message: ""
output:
text: null
finish_reason: stop
choices: null
audio:
data: ""
url: https://example.oss.aliyuncs.com/audio-result.wav?Expires=1766113409&OSSAccessKeyId=LTAIxxxx&Signature=xxxx
id: audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx
expires_at: 1766113409
usage:
input_tokens: 0
output_tokens: 0
characters: 195
- summary: CosyVoice response
value:
status_code: 200
request_id: f4e8139b-3203-4887-92cb-xxxxxxxxxxxx
code: ""
message: ""
output:
text: null
finish_reason: stop
choices: null
audio:
data: ""
url: https://example.oss.aliyuncs.com/audio-result.wav?Expires=1766116806&OSSAccessKeyId=LTAIxxxx&Signature=xxxx
id: audio_f4e8139b-3203-4887-92cb-xxxxxxxxxxxx
expires_at: 1766116806
usage:
input_tokens: 76
output_tokens: 1045
characters: 0
input_tokens_details:
text_tokens: 76
output_tokens_details:
audio_tokens: 1045
text_tokens: 0
total_tokens: 1121