Qwen-TTS non-real-time speech synthesis API reference

Para instruções de uso, consulte Non-real-time speech synthesis .

Request body

Non-streaming output
Streaming output

Python
Java
curl

The SpeechSynthesizer interface in the DashScope Python SDK is now unified under MultiModalConversation. Its usage and parameters remain fully consistent.

# instale the latest version of the DashScope SDK
    import os
    import dashscope
    # Singapore region
    dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.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 qwen3-tts-instruct-flash
        model="qwen3-tts-flash",
        # The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
        # If the environment variable is not configured, replace the following line with your Model Studio 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 qwen3-tts-instruct-flash
        # instructions='Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True
    )
    print(response)

// instale 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 qwen3-tts-instruct-flash
        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)
                    // The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                    // If the environment variable is not configured, replace the following line with your Model Studio 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 lines and replace MODEL with qwen3-tts-instruct-flash
                    // .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) {
            // Singapore region
            Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
            try {
                call();
            } catch (ApiException | NoApiKeyException | UploadFileException e) {
                System.out.println(e.getMessage());
            }
            System.exit(0);
        }
    }

# ======= IMPORTANT NOTE =======
    # Singapore region
    # The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If the environment variable is not configured, replace $DASHSCOPE_API_KEY with your Model Studio API key: sk-xxx.
    # === exclua THIS COMMENT WHEN EXECUTING ===

    curl -X POST 'https://dashscope-intl.aliyuncs.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",
            "language_type": "English"
        }
    }'

Python
Java
curl

The SpeechSynthesizer interface in the DashScope Python SDK is now unified under MultiModalConversation. To switch to the new interface, simply replace the name — all other parameters are fully compatible.

# DashScope SDK version 1.24.5 or later required
    import os
    import dashscope
    # Singapore region
    dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.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 qwen3-tts-instruct-flash
        model="qwen3-tts-flash",
        # The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
        # If the environment variable is not configured, replace the following line with your Model Studio 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 lines and replace the model with qwen3-tts-instruct-flash
        # instructions='Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.',
        # optimize_instructions=True,
        stream=True
    )
    for chunk in response:
        print(chunk)

// DashScope SDK version 2.19.0 or later required
    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;
    import io.reactivex.Flowable;
    public class Main {
        // To use the instruction control feature, replace MODEL with qwen3-tts-instruct-flash
        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)
                    // The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
                    // If the environment variable is not configured, replace the following line with your Model Studio 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 lines and replace MODEL with qwen3-tts-instruct-flash
                    // .parameter("instructions","Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.")
                    // .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) {
            // Singapore region
            Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
            try {
                streamCall();
            } catch (ApiException | NoApiKeyException | UploadFileException e) {
                System.out.println(e.getMessage());
            }
            System.exit(0);
        }
    }

# ======= IMPORTANT NOTE =======
    # Singapore region
    # The API keys for Singapore and Beijing regions are different. Get your API Key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If the environment variable is not configured, replace $DASHSCOPE_API_KEY with your Model Studio API key: sk-xxx.
    # === exclua THIS COMMENT WHEN EXECUTING ===

    curl -X POST 'https://dashscope-intl.aliyuncs.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",
            "language_type": "English"
        }
    }'

To play Base64-encoded audio in real time, see Speech synthesis - Qwen.

modelstring(required)Nome do modelo. Para mais detalhes, consulte Supported models.

inputobject(required)Parâmetros de entrada.

Properties

text string (required)Texto a sintetizar. Aceita entrada mista multilíngue. Comprimento máximo: 512 tokens (modelo Qwen-TTS) ou 600 caracteres (outros modelos).voice string (required)Voz a utilizar. Consulte Supported system voices.language_type string (optional)Idioma do áudio sintetizado. O padrão é Auto.

Auto: Utilize quando a entrada contiver vários idiomas ou quando o idioma não puder ser determinado. O modelo ajusta automaticamente a pronúncia para cada segmento de idioma, embora a precisão não seja garantida.
Idioma específico: Recomendado para textos monolíngues. Especificar o idioma melhora significativamente a qualidade da síntese e geralmente produz resultados superiores aos do modo Auto. Valores válidos:
- Chinese
- English
- German
- Italian
- Portuguese
- Spanish
- Japanese
- Korean
- French
- Russian

instructionsstring(optional)Instruções para síntese de fala. Consulte Instruction control.Padrão: Nenhum.Comprimento máximo: 1.600 tokens.Idiomas suportados: Apenas chinês e inglês.Escopo: Aplica-se exclusivamente aos modelos da série Qwen3-TTS-Instruct-Flash.optimize_instructionsboolean(optional)Quando ativado, otimiza semanticamente as instructions para melhorar a naturalidade e a expressividade da fala sintetizada.Padrão: false.Comportamento: Quando definido como true, o sistema reescreve semanticamente as instructions para gerar diretivas mais adequadas à síntese de fala.Utilize este parâmetro quando for necessário controle preciso sobre a entonação da fala.Depende do parâmetro instructions. Não surte efeito se instructions estiver vazio.Escopo: Aplica-se exclusivamente aos modelos da série Qwen3-TTS-Instruct-Flash.

Response object (formatos streaming e non-streaming são idênticos)	{ "status_code": 200, "request_id": "5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx", "code": "", "message": "", "output": { "text": null, "finish_reason": "stop", "choices": null, "audio": { "data": "", "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1d/ab/20251218/d2033070/39b6d8f2-c0db-4daa-9073-5d27bfb66b78.wav?Expires=1766113409&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE", "id": "audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx", "expires_at": 1766113409 } }, "usage": { "input_tokens": 0, "output_tokens": 0, "characters": 195 } }
status_code `integer`Código de status HTTP conforme definido na RFC 9110. Valores comuns: • `200`: Requisição bem-sucedida. • `400`: Parâmetros de requisição inválidos. • `401`: Não autorizado. • `404`: Recurso não encontrado. • `500`: Erro interno do servidor.
request_id `string`Identificador exclusivo desta requisição. Utilize-o para solução de problemas.
code `string`Código de erro retornado em caso de falha. Consulte Error codes.
message `string`Mensagem de erro retornada em caso de falha. Consulte Error codes.
output`object`Saída do modelo. Properties text`string`Sempre nulo. Ignore este campo.choices`string`Sempre nulo. Ignore este campo.finish_reason`string`Status da geração: `null` — Geração em andamento. `stop` — Geração concluída normalmente ou condição de parada atingida. audio `object`Saída de áudio do modelo. Properties url `string`url do arquivo de áudio completo, válida por 24 horas. No modo non-streaming, retorna diretamente na resposta. No modo streaming, fornece apenas no último chunk do fluxo SSE (chunks intermediários não contêm este campo).data `string`Dados de áudio codificados em Base64. No modo non-streaming, este campo é sempre uma string vazia (utilize `url` para obter o arquivo de áudio completo). No modo streaming, os chunks intermediários contêm segmentos de áudio codificados em Base64, enquanto o último chunk retorna uma string vazia (utilize `url` para obter o áudio completo).id `string`Identificador exclusivo do áudio.expires_at `integer`Tempo de expiração da url como timestamp Unix.
usage `object`Uso de tokens ou caracteres nesta requisição. O Qwen-TTS retorna o uso de tokens; o Qwen3-TTS-Flash retorna o uso de caracteres. Properties input_tokens_details `object`Detalhes do uso de tokens para o texto de entrada. Retornado apenas pelo modelo Qwen-TTS. Properties text_tokens `integer`Quantidade de tokens consumidos pelo texto de entrada. total_tokens `integer`Total de tokens consumidos por esta requisição. Retornado apenas pelo modelo Qwen-TTS.output_tokens `integer`Quantidade de tokens consumidos pelo áudio de saída. Para o modelo Qwen3-TTS-Flash, este campo é sempre 0.input_tokens `integer`Quantidade de tokens consumidos pelo texto de entrada. Para o modelo Qwen3-TTS-Flash, este campo é sempre 0.output_tokens_details `object`Detalhes do uso de tokens para a saída. Retornado apenas pelo modelo Qwen-TTS. Properties audio_tokens `integer`Quantidade de tokens consumidos pelo áudio de saída.text_tokens `integer`Quantidade de tokens consumidos pelo texto de saída. Atualmente sempre 0. characters `integer`Número de caracteres no texto de entrada. Retornado apenas pelo modelo Qwen3-TTS-Flash.
request_id `string`Identificador exclusivo desta requisição. Utilize-o para solução de problemas.

Request body

Response object (formatos streaming e non-streaming são idênticos)