Skip to main content

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

Paramètres de requête et champs de réponse de l'API de synthèse vocale en différé (Qwen-TTS).

Corps de la requête

  • Sortie non streaming
  • Sortie streaming
  • Python
  • Java
  • curl
Dans le SDK Python DashScope 2.0, la synthèse vocale non temps réel s'effectue via la ressource client.audio.tts.http.
# Install the latest version of the DashScope SDK
import os
import dashscope

# Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Les API Key des régions Singapour et Pékin sont différentes. Obtenez votre API Key : https://www.alibabacloud.com/help/model-studio/get-api-key
    # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de 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(obligatoire)Nom du modèle. Pour plus de détails, consultez Modèles pris en charge.
inputobject(obligatoire)Paramètres d'entrée.

Propriétés

text string (obligatoire)Texte à synthétiser. Prend en charge les entrées mixtes multilingues. La longueur maximale d'entrée est de 600 caractères.voice string (obligatoire)Voix à utiliser. Consultez Voix système prises en charge.language_type string (facultatif)Langue de l'audio synthétisé. La valeur par défaut est Auto.
  • Auto : À utiliser lorsque l'entrée contient plusieurs langues ou que la langue ne peut être déterminée. Le modèle adapte automatiquement la prononciation pour chaque segment linguistique, bien que la précision ne soit pas garantie.
  • Langue spécifique : À utiliser pour un texte monolingue. Spécifier la langue améliore considérablement la qualité de la synthèse et produit généralement de meilleurs résultats que Auto. Valeurs valides :
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian

Objet de réponse (les formats streaming et non streaming sont identiques)

{
    "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 integerCode de statut HTTP tel que défini dans la RFC 9110. Valeurs courantes :
• 200 : Requête réussie.
• 400 : Paramètres de requête invalides.
• 401 : Non autorisé.
• 404 : Ressource introuvable.
• 500 : Erreur interne du serveur.

request_id stringIdentifiant unique de cette requête. Utilisez-le pour le dépannage.
code stringCode d'erreur retourné en cas d'échec. Consultez Codes d'erreur.
message stringMessage d'erreur retourné en cas d'échec. Consultez Codes d'erreur.
outputobjectSortie du modèle.

Propriétés

textstringToujours null. Ignorez ce champ.choicesstringToujours null. Ignorez ce champ.finish_reasonstringÉtat de la génération :
  • null — Génération en cours.
  • stop — Génération terminée normalement ou condition d'arrêt atteinte.
audio objectSortie audio du modèle.

Propriétés

url stringURL du fichier audio complet, valable 24 heures. En mode non streaming, elle est retournée directement dans la réponse. En mode streaming, elle n'est retournée que dans le dernier chunk du flux SSE (les chunks intermédiaires ne contiennent pas ce champ).data stringDonnées audio encodées en Base64. En mode non streaming, ce champ est toujours une chaîne vide (utilisez url pour obtenir le fichier audio complet). En mode streaming, les chunks intermédiaires contiennent des segments audio encodés en Base64, tandis que le dernier chunk retourne une chaîne vide (utilisez url pour obtenir l'audio complet).id stringIdentifiant unique de l'audio.expires_at integerHeure d'expiration de l'URL sous forme de timestamp Unix.
usage objectUtilisation des caractères pour cette requête.

Propriétés

output_tokens integerNombre de tokens consommés par l'audio de sortie. Pour le modèle Qwen3-TTS-Flash, ce champ est toujours égal à 0.input_tokens integerNombre de tokens consommés par le texte d'entrée. Pour le modèle Qwen3-TTS-Flash, ce champ est toujours égal à 0.characters integerNombre de caractères dans le texte d'entrée. Retourné uniquement par le modèle Qwen3-TTS-Flash.
request_id stringIdentifiant unique de cette requête. Utilisez-le pour le dépannage.

Téléchargement et lecture audio

Avant d’exécuter les exemples, obtenez et configurez une clé API et installez le SDK DashScope. L’exemple de lecture en Python nécessite également PyAudio et NumPy. Consultez les commentaires du code pour installer PyAudio et installez NumPy avec pip install numpy.

Télécharger un fichier audio (Java)

L'importation de la dépendance Gson est requise. Utilisez Maven ou Gradle pour l'ajouter :
  • Maven
  • Gradle
Ajoutez cet extrait à votre fichier 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);
    }
}

Lecture en 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

# Voici la configuration de la région de Singapour. Remplacez {WorkspaceId} par l'ID de votre workspace. La valeur de region varie selon la région.
client = dashscope.Client(
    # Les API Key des régions Singapour et Pékin sont différentes. Obtenez votre API Key : https://www.alibabacloud.com/help/model-studio/get-api-key
    # Si la variable d'environnement n'est pas configurée, remplacez la ligne suivante par votre API Key de Model Studio : api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

p = pyaudio.PyAudio()
# Créez un flux audio
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",  # Il est recommandé de l'adapter à la langue du texte pour une prononciation correcte et une intonation naturelle.
):
    if chunk.audio:
        # Lisez directement les données audio (chunk.audio contient les octets audio décodés)
        stream.write(chunk.audio)
    if chunk.is_final:
        print(f"finish at: {chunk.expires_at}")
time.sleep(0.8)
# Libérez les ressources
stream.stop_stream()
stream.close()
p.terminate()