Skip to main content

API WebSocket de synthèse vocale CosyVoice

Accédez au service de synthèse vocale en temps réel CosyVoice via une connexion WebSocket. Cette rubrique détaille les endpoints du service, les en-têtes de requête et le flux d'interaction client-serveur. Le SDK DashScope prend uniquement en charge Java et Python. Pour les autres langages, utilisez une connexion WebSocket. Limites de taux : Les appels aux modèles sont soumis à des limites de taux. En cas de dépassement, le serveur renvoie l'erreur Requests rate limit exceeded, please try again later. Réduisez votre fréquence de requêtes ou le niveau de concurrence, puis réessayez. Pour consulter les limites applicables à chaque modèle, reportez-vous à la section Limitation du taux.

Endpoints du service

URL WebSocket fixe :
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceRemplacez {WorkspaceId} par votre ID d'espace de travail.

SDK disponibles

Alibaba Cloud Model Studio a publié des domaines spécifiques à chaque espace de travail pour les régions China (Beijing) et Singapore. Ces nouveaux domaines dédiés offrent de meilleures performances et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer vers ces nouveaux domaines :
  • China (Beijing) : passez de dashscope.aliyuncs.com à {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore : passez de dashscope-intl.aliyuncs.com à {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

En-têtes de requête

Incluez les en-têtes suivants dans votre requête :
ParamètreTypeObligatoireDescription
AuthorizationstringOuiFormat : Bearer <API key>. Remplacez <API key> par votre clé API.
user-agentstringNonIdentifiant client pour le suivi des requêtes.
X-DashScope-WorkSpacestringNonID d'espace de travail Alibaba Cloud Model Studio.
X-DashScope-DataInspectionstringNonActive l'inspection des données. Valeur par défaut : enable. Ne définissez cette valeur que si nécessaire.
L'autorisation est vérifiée lors du handshake WebSocket. Si la clé API est invalide ou manquante, le handshake échoue avec une erreur HTTP 401/403.

Flux d'interaction

image
Pour plus de détails sur les événements côté client et côté serveur, consultez les rubriques Événements client et Événements serveur. Séquence d'interaction client-serveur :
  1. Établir une connexion : créez une connexion WebSocket vers le serveur.
  2. Démarrer une tâche : envoyez un événement run-task.
  3. Attendre la confirmation : recevez un événement task-started du serveur avant de poursuivre.
  4. Envoyer le texte à synthétiser : Envoyez séquentiellement un ou plusieurs événements continue-task contenant le texte à synthétiser. Le serveur renvoie un événement result-generated accompagné d'un flux audio après chaque phrase complète. Pour connaître les limites de longueur du texte, consultez le champ text de l'événement continue-task.
    Envoyez plusieurs événements continue-task avec des segments de texte dans l'ordre. Le serveur découpe le texte en phrases :
    • Les phrases complètes sont synthétisées et renvoyées immédiatement sous forme audio.
    • Les phrases incomplètes sont mises en mémoire tampon jusqu'à ce qu'elles soient terminées.
    Un événement finish-task force la synthèse de tout le contenu mis en mémoire tampon.
  5. Réceptionner l'audio : lisez le flux audio depuis le canal binary.
  6. Terminer la tâche : Une fois tout le texte envoyé, émettez un événement finish-task et continuez à recevoir l'audio. Cette étape est obligatoire ; l'omettre risque de produire un fichier audio incomplet.
  7. Recevoir la notification de fin de tâche : Un événement task-finished provenant du serveur confirme que la tâche est terminée.
  8. Fermer la connexion : déconnectez le WebSocket.
Réutilisez la connexion WebSocket pour plusieurs tâches au lieu d'en créer une nouvelle à chaque fois.
Tous les événements d'une même tâche de synthèse (run-task, continue-task, finish-task) doivent partager le même task_id. Générez un nouveau task_id (par exemple un UUID) pour chaque tâche. Des valeurs incohérentes entraînent une corruption de l'audio ou l'échec de la tâche.

Exemples de code

Ces exemples utilisent des bibliothèques WebSocket génériques pour envoyer directement les événements avec cosyvoice-v3-flash et la voix longanyang. Obtenez une clé API, définissez DASHSCOPE_API_KEY et remplacez {WorkspaceId} par l’ID de l’espace de travail de la région. Pour changer de région, changez à la fois l’adresse et la clé API.
  • Java
  • Python
  • Go
  • C#
  • PHP
  • Node.js
Nous vous recommandons d'utiliser le SDK DashScope Java pour vos développements. Consultez la rubrique Qwen-Audio-TTS SDK Java / CosyVoice SDK Java.L'exemple ci-dessous illustre une connexion WebSocket directe en Java. Importez les dépendances suivantes avant l'exécution :
  • Java-WebSocket
  • jackson-databind
Gérez les dépendances avec Maven ou Gradle :
pom.xml
<dependencies>
    <!-- WebSocket Client -->
    <dependency>
        <groupId>org.java-websocket</groupId>
        <artifactId>Java-WebSocket</artifactId>
        <version>1.5.3</version>
    </dependency>

    <!-- JSON Processing -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>2.13.0</version>
    </dependency>
</dependencies>
Code Java :
import com.fasterxml.jackson.databind.ObjectMapper;

import org.java_websocket.client.WebSocketClient;
import org.java_websocket.handshake.ServerHandshake;

import java.io.FileOutputStream;
import java.io.IOException;
import java.net.URI;
import java.nio.ByteBuffer;
import java.util.*;

public class TTSWebSocketClient extends WebSocketClient {
    private final String taskId = UUID.randomUUID().toString();
    private final String outputFile = "output_" + System.currentTimeMillis() + ".mp3";
    private boolean taskFinished = false;

    public TTSWebSocketClient(URI serverUri, Map<String, String> headers) {
        super(serverUri, headers);
    }

    @Override
    public void onOpen(ServerHandshake serverHandshake) {
        System.out.println("Connection established");

        // Send the run-task event
        // If enable_ssml is set to true, only one continue-task event can be sent; otherwise the error "Text request limit violated, expected 1." will be returned
        String runTaskCommand = "{ \"header\": { \"action\": \"run-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"task_group\": \"audio\", \"task\": \"tts\", \"function\": \"SpeechSynthesizer\", \"model\": \"cosyvoice-v3-flash\", \"parameters\": { \"text_type\": \"PlainText\", \"voice\": \"longanyang\", \"format\": \"mp3\", \"sample_rate\": 22050, \"volume\": 50, \"rate\": 1, \"pitch\": 1, \"enable_ssml\": false }, \"input\": {} }}";
        send(runTaskCommand);
    }

    @Override
    public void onMessage(String message) {
        System.out.println("Received message from server: " + message);
        try {
            // Parse JSON message
            Map<String, Object> messageMap = new ObjectMapper().readValue(message, Map.class);

            if (messageMap.containsKey("header")) {
                Map<String, Object> header = (Map<String, Object>) messageMap.get("header");

                if (header.containsKey("event")) {
                    String event = (String) header.get("event");

                    if ("task-started".equals(event)) {
                        System.out.println("Received task-started event from server");

                        List<String> texts = Arrays.asList(
                                "Before my bed, moonlight shines bright,I suspect it\'s frost upon the ground.",
                                "I raise my eyes to gaze at the bright moon,then bow my head, thinking of home."
                        );

                        for (String text : texts) {
                            // Send the continue-task event
                            sendContinueTask(text);
                        }

                        // Send the finish-task event
                        sendFinishTask();
                    } else if ("task-finished".equals(event)) {
                        System.out.println("Received task-finished event from server");
                        taskFinished = true;
                        closeConnection();
                    } else if ("task-failed".equals(event)) {
                        System.out.println("Task failed: " + message);
                        closeConnection();
                    }
                }
            }
        } catch (Exception e) {
            System.err.println("Exception occurred: " + e.getMessage());
        }
    }

    @Override
    public void onMessage(ByteBuffer message) {
        System.out.println("Received binary audio data of size: " + message.remaining());

        try (FileOutputStream fos = new FileOutputStream(outputFile, true)) {
            byte[] buffer = new byte[message.remaining()];
            message.get(buffer);
            fos.write(buffer);
            System.out.println("Audio data written to local file " + outputFile);
        } catch (IOException e) {
            System.err.println("Failed to write audio data to local file: " + e.getMessage());
        }
    }

    @Override
    public void onClose(int code, String reason, boolean remote) {
        System.out.println("Connection closed: " + reason + " (" + code + ")");
    }

    @Override
    public void onError(Exception ex) {
        System.err.println("Error: " + ex.getMessage());
        ex.printStackTrace();
    }

    private void sendContinueTask(String text) {
        String command = "{ \"header\": { \"action\": \"continue-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"input\": { \"text\": \"" + text + "\" } }}";
        send(command);
    }

    private void sendFinishTask() {
        String command = "{ \"header\": { \"action\": \"finish-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"input\": {} }}";
        send(command);
    }

    private void closeConnection() {
        if (!isClosed()) {
            close();
        }
    }

    public static void main(String[] args) {
        try {
            // The API Key differs between the Singapore and Beijing regions. Get your API Key: https://www.alibabacloud.com/help/model-studio/get-api-key
            // If you have not configured the environment variable, replace the next line with your Model Studio API Key: String apiKey = "sk-xxx"
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            if (apiKey == null || apiKey.isEmpty()) {
                System.err.println("Please set the DASHSCOPE_API_KEY environment variable");
                return;
            }

            Map<String, String> headers = new HashMap<>();
            headers.put("Authorization", "bearer " + apiKey);
            // The following is the configuration for the Singapore region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
            TTSWebSocketClient client = new TTSWebSocketClient(new URI("wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference"), headers);

            client.connect();

            while (!client.isClosed() && !client.taskFinished) {
                Thread.sleep(1000);
            }
        } catch (Exception e) {
            System.err.println("Failed to connect to WebSocket service: " + e.getMessage());
            e.printStackTrace();
        }
    }
}