Skip to main content

Panduan Akses WebSocket

Artikel ini menjelaskan URL titik akhir, header permintaan, dan alur interaksi untuk mengakses layanan Sintesis Suara Real-time Qwen-TTS-Realtime melalui koneksi WebSocket.

Panduan Pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Sintesis suara real-time API Qwen-TTS Realtime berbasis pada protokol WebSocket. Untuk Java dan Python, disarankan memanggil melalui SDK DashScope, sehingga Anda tidak perlu menangani detail WebSocket; untuk bahasa lain, Anda dapat terhubung langsung menggunakan pustaka WebSocket.

Titik akhir layanan

URL WebSocket bersifat tetap sebagai berikut; tetapkan model yang akan dipanggil melalui parameter kueri model:
  • Singapura
  • Tiongkok (Beijing)
URL WebSocket:wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime?model=qwen3-tts-flash-realtime
URL harus menggunakan protokol wss://. Otorisasi diatur dalam header permintaan (lihat Header permintaan), dan model ditentukan melalui parameter kueri model pada URL.

Header permintaan

Tetapkan header permintaan berikut:

Parameter

Tipe

Wajib

Deskripsi

Authorization

string

Ya

Token otentikasi dengan format Bearer <your_api_key>; ganti <your_api_key> dengan API Key Anda yang sebenarnya.

user-agent

string

Tidak

Identifikasi klien untuk pelacakan sumber di sisi server.

X-DashScope-WorkSpace

string

Tidak

ID Ruang Kerja Alibaba Cloud Model Studio.

Otorisasi diverifikasi selama handshake WebSocket. Kunci API yang tidak valid atau tidak ada akan menyebabkan handshake gagal dengan kode HTTP 401/403.

Alur interaksi

Untuk penjelasan rinci mengenai event klien dan event server, lihat Event klien dan Event server. Dua pola penggunaan didukung:
  • Pola ServerCommit: Server secara cerdas menentukan segmentasi teks dan waktu sintesis, sehingga pengembang tidak perlu menangani pemisahan status internal.
  • Pola Commit: Klien mengontrol kapan setiap bagian teks dikirimkan (commit), dan harus memanggil input_text_buffer.commit secara eksplisit untuk memicu sintesis.
Deskripsi pola:
  • Pada mode ServerCommit, klien memanggil input_text_buffer.append beberapa kali, dan sistem menentukan titik awal sintesis berdasarkan aturan internal.
  • Jika klien secara aktif memanggil input_text_buffer.commit pada mode ServerCommit, konten buffer saat ini akan segera disintesis, dan mode ServerCommit tetap dipertahankan setelahnya.
  • Pada mode Commit, hanya memanggil input_text_buffer.append tidak memicu sintesis; Anda harus memanggil input_text_buffer.commit secara eksplisit.
qwen-tts
Penjelasan proses utama:
  1. Tahap koneksi: Klien memulai koneksi WebSocket, dan server mengembalikan session.created, yang menunjukkan bahwa sesi telah diinisialisasi.
  2. Konfigurasi sesi: Klien mengirim event session.update untuk mengatur parameter seperti voice, format, dan mode.
  3. Tahap input teks: Klien menambahkan teks ke buffer dengan mengirim input_text_buffer.append beberapa kali.
  4. Tahap pemicu sintesis:
    • Pada mode ServerCommit, sistem secara otomatis menentukan waktu sintesis, atau klien memanggil input_text_buffer.commit secara manual untuk memaksa pemicuan.
    • Pada mode Commit, hanya operasi input_text_buffer.commit yang benar-benar memicu proses sintesis suara.
  5. Tahap generasi audio: Server mengirim response.created untuk menunjukkan bahwa tugas telah dimulai, lalu mengembalikan audio secara bertahap melalui response.audio.delta (berkode base64) hingga response.audio.done.
  6. Tahap pengakhiran sesi: Klien secara eksplisit memanggil session.finish untuk memberi tahu server membersihkan status, dan server menutup koneksi setelah mengembalikan session.finished.
Setelah koneksi terbentuk, server mengembalikan event session.created berikut:
{
    "event_id": "event_xxx",
    "type": "session.created",
    "session": {
        "object": "realtime.session",
        "mode": "server_commit",
        "model": "qwen3-tts-flash-realtime",
        "voice": "Cherry",
        "response_format": "pcm",
        "sample_rate": 24000,
        "id": "sess_xxx"
    }
}

Contoh kode

Contoh berikut menyediakan klien Python dan Java serta kedua mode commit. Konfigurasikan DASHSCOPE_API_KEY terlebih dahulu, dan pastikan API Key sesuai dengan wilayah API contoh. Python memerlukan websockets dan pyaudio; Java memerlukan Java-WebSocket dan Gson, serta menggunakan Java Sound untuk memutar audio. Setiap event klien menggunakan UUID terpisah.
Java
<dependencies>
    <dependency>
        <groupId>org.java-websocket</groupId>
        <artifactId>Java-WebSocket</artifactId>
        <version>1.5.3</version>
    </dependency>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>
</dependencies>
  1. Buat klien
    • Java
    • Python
    Buat file Java bernama TTSRealtimeClient.java dan salin kode berikut ke dalam file tersebut:
    import com.google.gson.Gson;
    import com.google.gson.JsonObject;
    import org.java_websocket.client.WebSocketClient;
    import org.java_websocket.handshake.ServerHandshake;
    
    import java.net.URI;
    import java.util.Base64;
    import java.util.HashMap;
    import java.util.Map;
    import java.util.concurrent.CountDownLatch;
    import java.util.function.Consumer;
    
    /**
     * Klien untuk berinteraksi dengan API Realtime TTS.
     *
     * Kelas ini menyediakan metode untuk menghubungkan ke API Realtime TTS, mengirim data teks, mengambil output audio, dan mengelola koneksi WebSocket.
     */
    public class TTSRealtimeClient {
    
        public enum SessionMode {
            SERVER_COMMIT("server_commit"),
            COMMIT("commit");
            private final String value;
            SessionMode(String value) { this.value = value; }
            public String getValue() { return value; }
        }
    
        /**
         * Antarmuka callback audio
         */
        public interface AudioCallback {
            void onAudio(byte[] audioData);
        }
    
        private final String baseUrl;
        private final String apiKey;
        private final String voice;
        private final SessionMode mode;
        private final String languageType;
        private final AudioCallback audioCallback;
        private final Gson gson = new Gson();
    
        private WebSocketClient ws;
        private CountDownLatch responseDoneLatch;
        private CountDownLatch sessionFinishedLatch;
    
        public TTSRealtimeClient(String baseUrl, String apiKey, String voice,
                                 SessionMode mode, AudioCallback audioCallback,
                                 String languageType) {
            this.baseUrl = baseUrl;
            this.apiKey = apiKey;
            this.voice = voice;
            this.mode = mode;
            this.audioCallback = audioCallback;
            this.languageType = languageType;
        }
    
        public TTSRealtimeClient(String baseUrl, String apiKey, String voice,
                                 SessionMode mode, AudioCallback audioCallback) {
            this(baseUrl, apiKey, voice, mode, audioCallback, "Auto");
        }
    
        /**
         * Buat koneksi WebSocket ke API Realtime TTS.
         */
        public void connect() throws Exception {
            Map<String, String> headers = new HashMap<>();
            headers.put("Authorization", "Bearer " + apiKey);
    
            responseDoneLatch = new CountDownLatch(0);
            sessionFinishedLatch = new CountDownLatch(1);
    
            ws = new WebSocketClient(new URI(baseUrl), headers) {
                @Override
                public void onOpen(ServerHandshake handshake) {
                    System.out.println("Koneksi WebSocket berhasil");
                    // Kirim konfigurasi sesi default
                    JsonObject session = new JsonObject();
                    session.addProperty("mode", mode.getValue());
                    session.addProperty("voice", TTSRealtimeClient.this.voice);
                    session.addProperty("language_type", languageType);
                    session.addProperty("response_format", "pcm");
                    session.addProperty("sample_rate", 24000);
                    updateSession(session);
                }
    
                @Override
                public void onMessage(String message) {
                    JsonObject event = gson.fromJson(message, JsonObject.class);
                    String eventType = event.has("type") ? event.get("type").getAsString() : "";
    
                    if (!"response.audio.delta".equals(eventType)) {
                        System.out.println("Event diterima: " + eventType);
                    }
    
                    switch (eventType) {
                        case "error":
                            System.err.println("Error: " + event.get("error"));
                            break;
                        case "session.created":
                            System.out.println("Sesi dibuat, ID: " +
                                event.getAsJsonObject("session").get("id").getAsString());
                            break;
                        case "session.updated":
                            System.out.println("Sesi diperbarui, ID: " +
                                event.getAsJsonObject("session").get("id").getAsString());
                            break;
                        case "input_text_buffer.committed":
                            System.out.println("Buffer teks di-commit, ID item: " + event.get("item_id"));
                            break;
                        case "input_text_buffer.cleared":
                            System.out.println("Buffer teks dihapus");
                            break;
                        case "response.created":
                            System.out.println("Respons dibuat, ID: " +
                                event.getAsJsonObject("response").get("id").getAsString());
                            responseDoneLatch = new CountDownLatch(1);
                            break;
                        case "response.output_item.added":
                            System.out.println("Item output ditambahkan, ID: " +
                                event.getAsJsonObject("item").get("id").getAsString());
                            break;
                        case "response.audio.delta":
                            if (audioCallback != null) {
                                byte[] audioBytes = Base64.getDecoder().decode(
                                    event.get("delta").getAsString());
                                audioCallback.onAudio(audioBytes);
                            }
                            break;
                        case "response.audio.done":
                            System.out.println("Generasi audio selesai");
                            break;
                        case "response.done":
                            System.out.println("Respons selesai");
                            responseDoneLatch.countDown();
                            break;
                        case "session.finished":
                            System.out.println("Sesi selesai");
                            sessionFinishedLatch.countDown();
                            break;
                    }
                }
    
                @Override
                public void onClose(int code, String reason, boolean remote) {
                    System.out.println("Koneksi ditutup: " + reason);
                }
    
                @Override
                public void onError(Exception ex) {
                    System.err.println("Error WebSocket: " + ex.getMessage());
                }
            };
            ws.connectBlocking();
        }
    
        /**
         * Kirim event ke server.
         */
        public void sendEvent(JsonObject event) {
            String eventId = "event_" + java.util.UUID.randomUUID().toString();
            event.addProperty("event_id", eventId);
            System.out.println("Mengirim event: type=" + event.get("type").getAsString()
                + ", event_id=" + eventId);
            ws.send(gson.toJson(event));
        }
    
        /**
         * Perbarui konfigurasi sesi.
         */
        public void updateSession(JsonObject config) {
            JsonObject event = new JsonObject();
            event.addProperty("type", "session.update");
            event.add("session", config);
            System.out.println("Memperbarui konfigurasi sesi: " + event);
            sendEvent(event);
        }
    
        /**
         * Kirim data teks ke API.
         */
        public void appendText(String text) {
            JsonObject event = new JsonObject();
            event.addProperty("type", "input_text_buffer.append");
            event.addProperty("text", text);
            sendEvent(event);
        }
    
        /**
         * Commit buffer teks untuk memicu pemrosesan.
         */
        public void commitTextBuffer() {
            JsonObject event = new JsonObject();
            event.addProperty("type", "input_text_buffer.commit");
            sendEvent(event);
        }
    
        /**
         * Hapus buffer teks.
         */
        public void clearTextBuffer() {
            JsonObject event = new JsonObject();
            event.addProperty("type", "input_text_buffer.clear");
            sendEvent(event);
        }
    
        /**
         * Akhiri sesi.
         */
        public void finishSession() {
            JsonObject event = new JsonObject();
            event.addProperty("type", "session.finish");
            sendEvent(event);
        }
    
        /**
         * Tunggu event response.done.
         */
        public void waitForResponseDone() throws InterruptedException {
            responseDoneLatch.await();
        }
    
        /**
         * Tunggu event session.finished.
         */
        public void waitForSessionFinished() throws InterruptedException {
            sessionFinishedLatch.await();
        }
    
        /**
         * Tutup koneksi WebSocket.
         */
        public void close() {
            if (ws != null) {
                ws.close();
            }
        }
    }
    

SDK yang tersedia

  1. Pilih mode sintesis suara API Realtime mendukung dua mode berikut:
    • server_commit mode Server menangani segmentasi teks dan waktu sintesis secara otomatis. Klien hanya mengirim teks. Cocok untuk skenario latensi rendah (seperti navigasi GPS).
    • commit mode Klien menambahkan teks ke buffer dan secara eksplisit memicu sintesis. Cocok untuk skenario yang memerlukan kontrol segmentasi kalimat yang tepat (seperti siaran berita).
    • mode server_commit
    • commit mode
    • Java
    • Python
    Di direktori yang sama dengan TTSRealtimeClient.java, buat file Java lain bernama ServerCommit.java dan salin kode berikut ke dalam file tersebut:
    import javax.sound.sampled.*;
    import java.io.*;
    import java.util.ArrayList;
    import java.util.List;
    import java.util.concurrent.ConcurrentLinkedQueue;
    import java.util.concurrent.atomic.AtomicBoolean;
    
    public class ServerCommit {
        // Berikut ini adalah konfigurasi untuk wilayah Singapura.
        private static final String URL = "wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime?model=qwen3-tts-flash-realtime";
        // API Key berbeda antara wilayah Singapura dan Beijing. Dapatkan API Key Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
        // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan API Key Model Studio China Anda: private static final String API_KEY = "sk-xxx";
        private static final String API_KEY = System.getenv("DASHSCOPE_API_KEY");
        private static final int SAMPLE_RATE = 24000;
    
        // Cache data audio
        private static final List<byte[]> audioChunks = new ArrayList<>();
        // Antrian pemutaran real-time
        private static final ConcurrentLinkedQueue<byte[]> playbackQueue = new ConcurrentLinkedQueue<>();
        private static final AtomicBoolean playing = new AtomicBoolean(true);
    
        public static void main(String[] args) throws Exception {
            if (API_KEY == null || API_KEY.isEmpty()) {
                throw new IllegalStateException("Harap atur variabel lingkungan DASHSCOPE_API_KEY");
            }
    
            // Inisialisasi pemutaran audio
            AudioFormat format = new AudioFormat(SAMPLE_RATE, 16, 1, true, false);
            DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
            SourceDataLine audioLine = (SourceDataLine) AudioSystem.getLine(info);
            audioLine.open(format);
            audioLine.start();
    
            // Mulai thread pemutaran
            Thread playerThread = new Thread(() -> {
                while (playing.get() || !playbackQueue.isEmpty()) {
                    byte[] chunk = playbackQueue.poll();
                    if (chunk != null) {
                        audioLine.write(chunk, 0, chunk.length);
                    } else {
                        try { Thread.sleep(10); } catch (InterruptedException ignored) {}
                    }
                }
            });
            playerThread.start();
    
            // Buat klien TTS
            TTSRealtimeClient client = new TTSRealtimeClient(
                URL, API_KEY, "Cherry",
                TTSRealtimeClient.SessionMode.SERVER_COMMIT,
                audioData -> {
                    playbackQueue.add(audioData);
                    audioChunks.add(audioData);
                    System.out.println("Data audio diterima: " + audioData.length + " byte");
                }
            );
    
            client.connect();
    
            // Kirim fragmen teks
            String[] textFragments = {
                "Alibaba Cloud's large language model platform, Model Studio, is an all-in-one platform for developing and building large language model applications.",
                "Both developers and business users can deeply participate in the design and development of large language model applications.",
                "You can develop a large language model application in five minutes using a simple interface,",
                "or train a dedicated model in a few hours, allowing you to focus more energy on application innovation."
            };
    
            System.out.println("Mulai mengirim teks...");
            for (String text : textFragments) {
                System.out.println("Mengirim fragmen: " + text);
                client.appendText(text);
                Thread.sleep(100);
            }
    
            Thread.sleep(1000);
            client.finishSession();
    
            // Tunggu respons selesai
            client.waitForResponseDone();
            client.waitForSessionFinished();
            client.close();
    
            // Tunggu pemutaran selesai
            playing.set(false);
            playerThread.join();
            audioLine.drain();
            audioLine.close();
    
            // Simpan file audio
            saveWav("output.wav");
            System.out.println("Selesai");
        }
    
        private static void saveWav(String filename) throws IOException {
            if (audioChunks.isEmpty()) {
                System.out.println("Tidak ada data audio untuk disimpan");
                return;
            }
            ByteArrayOutputStream bos = new ByteArrayOutputStream();
            for (byte[] chunk : audioChunks) {
                bos.write(chunk);
            }
            byte[] allAudio = bos.toByteArray();
            AudioFormat format = new AudioFormat(SAMPLE_RATE, 16, 1, true, false);
            AudioInputStream ais = new AudioInputStream(
                new ByteArrayInputStream(allAudio), format, allAudio.length / 2);
            new File("outputs").mkdirs();
            AudioSystem.write(ais, AudioFileFormat.Type.WAVE,
                new File("outputs/" + filename));
            System.out.println("Audio disimpan ke: outputs/" + filename);
        }
    }
    
    Kompilasi dan jalankan ServerCommit.java untuk mendengar audio yang dihasilkan oleh API Realtime secara real-time.