Skip to main content

Panduan akses WebSocket

Topik ini menjelaskan proses interaksi, titik akhir API, dan header permintaan untuk mengakses layanan sintesis suara real-time Qwen-Audio-TTS melalui koneksi WebSocket.

Titik akhir API

API WebSocket menggunakan protokol wss://. Titik akhirnya adalah sebagai berikut:
  • Singapore
  • China (Beijing)
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferenceSaat memanggil API, ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya.

SDK yang tersedia

Alibaba Cloud Model Studio telah merilis domain khusus workspace untuk wilayah China (Beijing) dan Singapore, yang memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan Anda bermigrasi ke domain baru:
  • Wilayah China (Beijing): bermigrasi dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Wilayah Singapore: bermigrasi dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Header permintaan

Tambahkan informasi berikut ke header permintaan:
ParameterTipeWajibDeskripsi
AuthorizationstringYaToken autentikasi dalam format Bearer <your_api_key>. Ganti <your_api_key> dengan API Key Anda yang sebenarnya.
user-agentstringTidakIdentifikasi klien yang membantu server melacak sumber permintaan.
X-DashScope-WorkSpacestringTidakWorkspace ID Alibaba Cloud Model Studio.
X-DashScope-DataInspectionstringTidakApakah fitur pemeriksaan kepatuhan data diaktifkan. Secara default, parameter ini tidak dikirim atau diatur ke enable. Jangan aktifkan parameter ini kecuali diperlukan.
Otentikasi Authorization diverifikasi selama handshake WebSocket. Jika API Key tidak valid atau tidak disertakan, handshake gagal dan error HTTP 401/403 dikembalikan.

Alur interaksi

image
Untuk informasi selengkapnya tentang event klien dan event server, lihat Event klien dan Event server. Secara kronologis, interaksi antara klien dan server adalah sebagai berikut:
  1. Buat koneksi: Klien membuat koneksi WebSocket dengan server.
  2. Mulai tugas: Klien mengirim event run-task untuk memulai tugas.
  3. Tunggu konfirmasi: Klien menerima event task-started yang dikembalikan server, yang menunjukkan bahwa tugas telah berhasil dimulai dan langkah selanjutnya dapat dilanjutkan.
  4. Kirim teks yang akan disintesis: Klien mengirim satu atau beberapa event continue-task yang berisi teks yang akan disintesis ke server secara berurutan. Setelah menerima kalimat lengkap, server mengembalikan event result-generated dan aliran audio (panjang teks dibatasi; untuk detailnya, lihat deskripsi bidang text dalam event continue-task).
    Anda dapat mengirim event continue-task beberapa kali untuk mengirim fragmen teks secara berurutan. Setelah menerima fragmen teks, server otomatis membaginya menjadi kalimat:
    • Kalimat lengkap langsung disintesis, dan klien dapat menerima audio yang dikembalikan server
    • Kalimat yang belum lengkap di-cache hingga lengkap sebelum disintesis; saat sebuah kalimat belum lengkap, server tidak mengembalikan audio
    Saat event finish-task dikirim, server memaksa sintesis semua konten yang di-cache.
  5. Terima audio: Terima aliran audio melalui saluran binary
  6. Beri tahu server untuk mengakhiri tugas: Setelah semua teks dikirim, klien mengirim event finish-task untuk memberi tahu server bahwa tugas harus diakhiri, dan terus menerima aliran audio yang dikembalikan server. Langkah ini tidak dapat dilewati; jika tidak, data suara mungkin tidak lengkap.
  7. Penyelesaian tugas: Klien menerima event task-finished yang dikembalikan server, yang menunjukkan bahwa tugas telah berakhir.
  8. Tutup koneksi: Klien menutup koneksi WebSocket.
Untuk meningkatkan utilisasi resource, kami merekomendasikan menggunakan kembali koneksi WebSocket untuk menangani beberapa tugas, alih-alih membuat koneksi baru untuk setiap tugas.
Dalam tugas sintesis yang sama, run-task, semua continue-task, dan finish-task harus menggunakan task_id yang sama. Hasilkan task_id baru setiap kali Anda memulai tugas baru (misalnya, gunakan UUID). Penggunaan task_id yang berbeda akan mengakibatkan audio tidak berurutan atau kegagalan tugas.

Contoh kode

Contoh berikut menggunakan pustaka WebSocket umum untuk mengirim event protokol secara langsung, dengan model qwen-audio-3.1-tts-flash dan suara longanhuan_v3.1. Pertama, dapatkan API Key dan konfigurasikan variabel lingkungan DASHSCOPE_API_KEY, lalu ganti {WorkspaceId} dengan ID workspace wilayah terkait; saat menggunakan wilayah lain, ganti juga alamat titik akhir dan API Key.
  • Java
  • Python
  • Go
  • C#
  • PHP
  • Node.js
Kami merekomendasikan menggunakan SDK Java DashScope untuk pengembangan. Untuk informasi selengkapnya, lihat SDK Java Qwen-Audio-TTS.Berikut adalah contoh koneksi langsung WebSocket Java. Sebelum menjalankannya, impor dependensi berikut:
  • Java-WebSocket
  • jackson-databind
Kami merekomendasikan menggunakan Maven atau Gradle untuk mengelola dependensi. Konfigurasinya adalah sebagai berikut:
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>
Kode Java adalah sebagai berikut:
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("连接成功");

        // 发送run-task事件
        // 如果enable_ssml设为true,只允许发送一次continue-task事件,否则会报错“Text request limit violated, expected 1.”
        String runTaskCommand = "{ \"header\": { \"action\": \"run-task\", \"task_id\": \"" + taskId + "\", \"streaming\": \"duplex\" }, \"payload\": { \"task_group\": \"audio\", \"task\": \"tts\", \"function\": \"SpeechSynthesizer\", \"model\": \"qwen-audio-3.1-tts-flash\", \"parameters\": { \"text_type\": \"PlainText\", \"voice\": \"longanhuan_v3.1\", \"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("收到服务端返回的消息:" + 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("收到服务端返回的task-started事件");

                        List<String> texts = Arrays.asList(
                                "床前明月光,疑是地上霜",
                                "举头望明月,低头思故乡"
                        );

                        for (String text : texts) {
                            // 发送continue-task事件
                            sendContinueTask(text);
                        }

                        // 发送finish-task事件
                        sendFinishTask();
                    } else if ("task-finished".equals(event)) {
                        System.out.println("收到服务端返回的task-finished事件");
                        taskFinished = true;
                        closeConnection();
                    } else if ("task-failed".equals(event)) {
                        System.out.println("任务失败:" + message);
                        closeConnection();
                    }
                }
            }
        } catch (Exception e) {
            System.err.println("出现异常:" + e.getMessage());
        }
    }

    @Override
    public void onMessage(ByteBuffer message) {
        System.out.println("收到的二进制音频数据大小为:" + message.remaining());

        try (FileOutputStream fos = new FileOutputStream(outputFile, true)) {
            byte[] buffer = new byte[message.remaining()];
            message.get(buffer);
            fos.write(buffer);
            System.out.println("音频数据已写入本地文件" + outputFile + "中");
        } catch (IOException e) {
            System.err.println("音频数据写入本地文件失败:" + e.getMessage());
        }
    }

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

    @Override
    public void onError(Exception ex) {
        System.err.println("报错:" + 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 {
            // 新加坡和北京地域的API Key不同。获取API Key:https://www.alibabacloud.com/help/model-studio/get-api-key
            // 若没有配置环境变量,请用阿里云百炼API Key将下行替换为:String apiKey = "sk-xxx"
            String apiKey = System.getenv("DASHSCOPE_API_KEY");
            if (apiKey == null || apiKey.isEmpty()) {
                System.err.println("请设置 DASHSCOPE_API_KEY 环境变量");
                return;
            }

            Map<String, String> headers = new HashMap<>();
            headers.put("Authorization", "bearer " + apiKey);
            // 以下为新加坡地域的配置,调用时请将"{WorkspaceId}"替换为真实的业务空间ID,各地域的配置不同。
            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("连接WebSocket服务失败:" + e.getMessage());
            e.printStackTrace();
        }
    }
}