Skip to main content

Referência da API de síntese de fala não em tempo real do Qwen-TTS

Parâmetros de requisição e campos de resposta da API de síntese de fala não em tempo real (Qwen-TTS).

Request body

  • Non-streaming output
  • Streaming output
  • Python
  • Java
  • curl
No SDK do DashScope para Python 2.0, a síntese de voz não em tempo real é chamada por meio do recurso client.audio.tts.http.
# Instale a versão mais recente do SDK do DashScope
import os
import dashscope

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # As API Keys das regiões Singapura e China (Pequim) são diferentes. Para obter sua API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    # Se a variável de ambiente não estiver configurada, substitua a linha a seguir pela sua API Key do Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

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."
result = client.audio.tts.http.synthesize(
    text,
    model="qwen3-tts-flash",
    voice="Cherry"
)
print(result.audio_url, result.audio_id, result.expires_at)
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. O comprimento máximo de entrada é de 600 caracteres.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

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 integerCó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 stringIdentificador exclusivo desta requisição. Utilize-o para solução de problemas.
code stringCódigo de erro retornado em caso de falha. Consulte Error codes.
message stringMensagem de erro retornada em caso de falha. Consulte Error codes.
outputobjectSaída do modelo.

Properties

textstringSempre nulo. Ignore este campo.choicesstringSempre nulo. Ignore este campo.finish_reasonstringStatus da geração:
  • null — Geração em andamento.
  • stop — Geração concluída normalmente ou condição de parada atingida.
audio objectSaída de áudio do modelo.

Properties

url stringurl 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 stringDados 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 stringIdentificador exclusivo do áudio.expires_at integerTempo de expiração da url como timestamp Unix.
usage objectUso de caracteres nesta solicitação.

Properties

output_tokens integerQuantidade de tokens consumidos pelo áudio de saída. Para o modelo Qwen3-TTS-Flash, este campo é sempre 0.input_tokens integerQuantidade de tokens consumidos pelo texto de entrada. Para o modelo Qwen3-TTS-Flash, este campo é sempre 0.characters integerNúmero de caracteres no texto de entrada. Retornado apenas pelo modelo Qwen3-TTS-Flash.
request_id stringIdentificador exclusivo desta requisição. Utilize-o para solução de problemas.

Download e reprodução de áudio

Antes de executar os exemplos, obtenha e configure uma chave de API e instale o SDK do DashScope. O exemplo de reprodução em Python também requer PyAudio e NumPy. Consulte os comentários do código para instalar o PyAudio e instale o NumPy com pip install numpy.

Baixar áudio (Java)

Importe a dependência Gson. Adicione-a usando Maven ou Gradle:
  • Maven
  • Gradle
Adicione o seguinte trecho ao arquivo pom.xml:
<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.13.1</version>
</dependency>
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.Constants;

import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.URL;

public class Main {
    private static final String MODEL = "qwen3-tts-flash";
    public static void call() throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // The API Keys for the Singapore and Beijing regions are different. Get an API Key: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                // If you have not configured the environment variable, replace the following line with your Model Studio API Key: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model(MODEL)
                .text("Today is a wonderful day to build something people love!")
                .voice(AudioParameters.Voice.CHERRY)
                .languageType("English") // We recommend matching this with the language of the text for correct pronunciation and natural intonation.
                .build();
        MultiModalConversationResult result = conv.call(param);
        String audioUrl = result.getOutput().getAudio().getUrl();
        System.out.print(audioUrl);

        // Download the audio file to local storage
        try (InputStream in = new URL(audioUrl).openStream();
             FileOutputStream out = new FileOutputStream("downloaded_audio.wav")) {
            byte[] buffer = new byte[1024];
            int bytesRead;
            while ((bytesRead = in.read(buffer)) != -1) {
                out.write(buffer, 0, bytesRead);
            }
            System.out.println("\nAudio file downloaded to: downloaded_audio.wav");
        } catch (Exception e) {
            System.out.println("\nFailed to download audio file: " + e.getMessage());
        }
    }
    public static void main(String[] args) {
        // The following is the configuration for the 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);
    }
}

Reprodução em streaming

  • Python
  • Java
# coding=utf-8
#
# Installation instructions for pyaudio:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   or
#   pip install pyaudio
# CentOS
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows
#   python -m pip install pyaudio

import os
import dashscope
import pyaudio
import time

# A configuração abaixo refere-se à região Singapura. Substitua {WorkspaceId} pelo ID real do seu workspace. O valor de region varia conforme a região.
client = dashscope.Client(
    # As API Keys das regiões Singapura e China (Pequim) são diferentes. Para obter uma API Key, consulte https://www.alibabacloud.com/help/model-studio/get-api-key
    # Se a variável de ambiente não estiver configurada, substitua a linha a seguir pela sua API Key do Model Studio: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

p = pyaudio.PyAudio()
# Cria um stream de áudio
stream = p.open(format=pyaudio.paInt16,
                channels=1,
                rate=24000,
                output=True)

text = "Today is a wonderful day to build something people love!"

for chunk in client.audio.tts.http.stream(
    text,
    model="qwen3-tts-flash",
    voice="Cherry",
    language_type="English",  # Recomendamos alinhar isso com o idioma do texto para uma pronúncia correta e uma entonação natural.
):
    if chunk.audio:
        # Reproduz os dados de áudio diretamente (chunk.audio contém os bytes de áudio já decodificados)
        stream.write(chunk.audio)
    if chunk.is_final:
        print(f"finish at: {chunk.expires_at}")
time.sleep(0.8)
# Libera os recursos
stream.stop_stream()
stream.close()
p.terminate()