Referensi API desain suara Qwen - Alibaba Cloud Model Studio

Desain suara menghasilkan suara kustom berdasarkan deskripsi teks. Layanan ini mendukung definisi fitur suara multi-bahasa dan multi-dimensi, serta cocok untuk aplikasi seperti pengisi suara iklan, pembuatan karakter, dan produksi konten audio. Desain suara dan sintesis suara merupakan dua langkah berurutan. Dokumen ini berfokus pada parameter dan detail antarmuka desain suara. Untuk sintesis suara, lihat Sintesis Suara Real-time - Qwen atau Sintesis Suara - Qwen.

Panduan pengguna: Untuk pengenalan model dan rekomendasi pemilihan, lihat Sintesis Suara Real-time - Qwen atau Sintesis Suara - Qwen.

Dukungan bahasa

Layanan desain suara mendukung pembuatan suara dan sintesis ucapan dalam berbagai bahasa, termasuk: Bahasa Tiongkok (zh), Bahasa Inggris (en), Bahasa Jerman (de), Bahasa Italia (it), Bahasa Portugis (pt), Bahasa Spanyol (es), Bahasa Jepang (ja), Bahasa Korea (ko), Bahasa Prancis (fr), dan Bahasa Rusia (ru).

Menulis deskripsi suara

Persyaratan dan batasan

Saat menulis deskripsi suara (voice_prompt), ikuti batasan teknis berikut:

Batas panjang: Konten voice_prompt tidak boleh melebihi 2.048 karakter.
Bahasa yang didukung: Teks deskripsi hanya mendukung Bahasa Tiongkok dan Bahasa Inggris.

Prinsip inti

Deskripsi suara berkualitas tinggi (voice_prompt) merupakan kunci untuk menciptakan suara ideal Anda. Deskripsi ini berperan sebagai cetak biru desain suara dan secara langsung memandu model menghasilkan suara dengan fitur spesifik.

Ikuti prinsip inti berikut saat mendeskripsikan suara:

Bersifat spesifik, bukan samar. Gunakan kata-kata yang menggambarkan kualitas suara konkret, seperti "berat", "jernih", atau "cepat". Hindari istilah subjektif dan tidak informatif seperti "bagus" atau "normal".
Gunakan beberapa dimensi, bukan hanya satu. Deskripsi yang baik menggabungkan berbagai dimensi, seperti jenis kelamin, usia, dan emosi, sebagaimana dijelaskan di bawah. Deskripsi satu dimensi, seperti "suara perempuan", terlalu luas untuk menghasilkan suara yang khas.
Bersifat objektif, bukan subjektif. Fokus pada fitur fisik dan persepsi suara, bukan preferensi pribadi. Misalnya, gunakan "tinggi dan energetik" alih-alih "suara favorit saya".
Bersifat orisinal, bukan imitatif. Gambarkan kualitas suara alih-alih meminta peniruan orang tertentu, seperti selebriti atau aktor. Permintaan semacam itu berisiko melanggar hak cipta dan tidak didukung oleh model.
Bersifat ringkas, bukan redundan. Pastikan setiap kata memiliki tujuan. Hindari penggunaan sinonim atau penguat tak berarti, seperti "suara yang sangat, sangat bagus".

Dimensi deskripsi

Dimensi	Contoh
Jenis kelamin	Laki-laki, perempuan, netral
Usia	Anak (5–12 tahun), remaja (13–18 tahun), dewasa muda (19–35 tahun), paruh baya (36–55 tahun), lansia (55+ tahun)
Pitch	Tinggi, sedang, rendah, bernada tinggi, bernada rendah
Kecepatan	Cepat, sedang, lambat, berkecepatan tinggi, berkecepatan rendah
Emosi	Ceria, tenang, lembut, serius, hidup, tenang, menenangkan
Karakteristik	Magnetis, jernih, serak, hangat, manis, kaya, kuat
Kasus penggunaan	Siaran berita, pengisi suara iklan, buku audio, karakter animasi, asisten suara, narasi dokumenter

Perbandingan contoh

✅ Direkomendasikan

"Suara perempuan muda yang hidup, dengan kecepatan cepat dan infleksi naik yang jelas, cocok untuk memperkenalkan produk fesyen."
Analisis: Menggabungkan usia, kepribadian, kecepatan, dan intonasi, serta menentukan skenario yang sesuai, sehingga menciptakan profil yang lengkap.
"Suara laki-laki paruh baya yang tenang, dengan kecepatan lambat dan nada berat yang magnetis, cocok untuk membaca berita atau narasi dokumenter."
Analisis: Mendefinisikan jenis kelamin, kelompok usia, kecepatan, karakteristik vokal, dan domain aplikasi secara jelas.
"Suara anak lucu, sekitar 8 tahun, berbicara dengan nada agak kekanak-kanakan, cocok untuk pengisi suara karakter animasi."
Analisis: Spesifik hingga usia tertentu dan kualitas vokal (kekanak-kanakan), dengan tujuan yang jelas.
"Suara perempuan intelektual yang lembut, sekitar 30 tahun, dengan nada tenang, cocok untuk narasi buku audio."
Analisis: Kata-kata seperti "intelektual" dan "tenang" secara efektif menyampaikan emosi dan gaya suara.

❌ Tidak direkomendasikan

Contoh	Masalah utama	Perbaikan
Suara yang bagus	Terlalu samar, sangat subjektif, dan tidak memiliki fitur yang dapat ditindaklanjuti.	Tambahkan dimensi spesifik, seperti: "Suara perempuan muda dengan garis vokal jernih dan nada lembut."
Suara seperti selebriti tertentu	Karena risiko hak cipta, model tidak dapat meniru secara langsung.	Ambil dan gambarkan karakteristik suaranya, seperti: "Suara laki-laki dewasa yang magnetis dengan kecepatan tenang."
Suara perempuan yang sangat, sangat, sangat bagus	Informasi redundan. Kata-kata berulang tidak membantu mendefinisikan suara.	Hapus kata berulang dan tambahkan deskripsi efektif, seperti: "Suara perempuan, usia 20–24 tahun, dengan nada ringan, pitch hidup, dan kualitas manis."
123456	Input tidak valid. Tidak dapat diurai sebagai fitur suara.	Berikan deskripsi teks yang bermakna. Lihat contoh yang direkomendasikan di atas.

Memulai: Dari desain suara hingga sintesis suara

1. Alur kerja

Desain suara dan sintesis suara adalah dua langkah terpisah namun saling terkait yang mengikuti alur kerja "buat dulu, gunakan kemudian":

Persiapkan deskripsi suara dan teks pratinjau yang diperlukan untuk desain suara.
- Deskripsi suara (voice_prompt): Menentukan fitur suara target. Untuk informasi cara menulis deskripsi suara, lihat "Menulis deskripsi suara".
- Teks pratinjau (preview_text): Konten yang akan dibacakan oleh audio pratinjau suara target, misalnya "Halo semuanya, selamat datang."
Panggil API Buat suara untuk membuat suara kustom dan mendapatkan nama suara beserta audio pratinjau.
Pada langkah ini, Anda harus menentukan target_model untuk menyatakan model sintesis suara mana yang akan menggerakkan suara yang dibuat.
Dengarkan audio pratinjau untuk menentukan apakah sesuai ekspektasi. Jika ya, lanjutkan ke langkah berikutnya. Jika tidak, rancang ulang suaranya.
Jika Anda sudah memiliki suara yang dibuat (panggil API Kueri daftar suara untuk memeriksa), Anda dapat melewati langkah ini dan melanjutkan ke langkah berikutnya.
Gunakan suara untuk (sintesis suara).
Panggil API sintesis suara dan masukkan suara yang diperoleh pada langkah sebelumnya. Model sintesis suara yang ditentukan pada langkah ini harus sama dengan target_model dari langkah sebelumnya.

2. Konfigurasi model dan persiapan

Pilih model yang sesuai dan selesaikan persiapannya.

Konfigurasi model

Tentukan dua model berikut untuk desain suara:

Model desain suara: qwen-voice-design
Model sintesis suara berbasis suara terbagi menjadi dua kategori:
- Qwen3-TTS-VD-Realtime (lihat Sintesis Suara Real-time - Qwen):
  - qwen3-tts-vd-realtime-2026-01-15
  - qwen3-tts-vd-realtime-2025-12-16
- Qwen3-TTS-VD (lihat Sintesis Suara - Qwen):
  - qwen3-tts-vd-2026-01-26

Persiapan

Dapatkan Kunci API: Dapatkan Kunci API. Untuk keamanan, kami merekomendasikan mengonfigurasi Kunci API sebagai Variabel lingkungan.
Instal SDK: Pastikan Anda telah menginstal versi terbaru SDK DashScope.

3. Contoh kode

Sintesis streaming dua arah

Ini berlaku untuk rangkaian model Qwen3-TTS-VC-Realtime. Untuk informasi lebih lanjut, lihat Sintesis Suara Real-time - Qwen.

Hasilkan suara kustom dan pratinjau hasilnya. Jika Anda puas dengan hasilnya, lanjutkan ke langkah berikutnya. Jika tidak, hasilkan kembali.

Python

import requests
import base64
import os

def create_voice_and_play():
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    if not api_key:
        print("Error: Variabel lingkungan DASHSCOPE_API_KEY tidak ditemukan. Harap atur Kunci API terlebih dahulu.")
        return None, None, None
    
    # Siapkan data permintaan
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "qwen-voice-design",
        "input": {
            "action": "create",
            "target_model": "qwen3-tts-vd-realtime-2026-01-15",
            "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
            "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
            "preferred_name": "announcer",
            "language": "en"
        },
        "parameters": {
            "sample_rate": 24000,
            "response_format": "wav"
        }
    }
    
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    
    try:
        # Kirim permintaan
        response = requests.post(
            url,
            headers=headers,
            json=data,
            timeout=60  # Tambahkan pengaturan timeout
        )
        
        if response.status_code == 200:
            result = response.json()
            
            # Dapatkan nama suara
            voice_name = result["output"]["voice"]
            print(f"Nama suara: {voice_name}")
            
            # Dapatkan data audio pratinjau
            base64_audio = result["output"]["preview_audio"]["data"]
            
            # Dekode data audio Base64
            audio_bytes = base64.b64decode(base64_audio)
            
            # Simpan file audio secara lokal
            filename = f"{voice_name}_preview.wav"
            
            # Tulis data audio ke file lokal
            with open(filename, 'wb') as f:
                f.write(audio_bytes)
            
            print(f"Audio disimpan ke file lokal: {filename}")
            print(f"Jalur file: {os.path.abspath(filename)}")
            
            return voice_name, audio_bytes, filename
        else:
            print(f"Permintaan gagal dengan kode status: {response.status_code}")
            print(f"Konten respons: {response.text}")
            return None, None, None
            
    except requests.exceptions.RequestException as e:
        print(f"Terjadi kesalahan permintaan jaringan: {e}")
        return None, None, None
    except KeyError as e:
        print(f"Kesalahan format data respons, bidang wajib tidak ditemukan: {e}")
        print(f"Konten respons: {response.text if 'response' in locals() else 'No response'}")
        return None, None, None
    except Exception as e:
        print(f"Terjadi kesalahan tidak diketahui: {e}")
        return None, None, None

if __name__ == "__main__":
    print("Mulai membuat suara...")
    voice_name, audio_data, saved_filename = create_voice_and_play()
    
    if voice_name:
        print(f"\nBerhasil membuat suara '{voice_name}'")
        print(f"File audio disimpan sebagai: '{saved_filename}'")
        print(f"Ukuran file: {os.path.getsize(saved_filename)} byte")
    else:
        print("\nPembuatan suara gagal")

Java

Anda perlu mengimpor dependensi Gson. Jika menggunakan Maven atau Gradle, tambahkan dependensi sebagai berikut:

Maven

Tambahkan konten berikut ke 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>

Gradle

Tambahkan konten berikut ke build.gradle:

// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class Main {
    public static void main(String[] args) {
        Main example = new Main();
        example.createVoice();
    }

    public void createVoice() {
        // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Buat string body permintaan JSON
        String jsonBody = "{\n" +
                "    \"model\": \"qwen-voice-design\",\n" +
                "    \"input\": {\n" +
                "        \"action\": \"create\",\n" +
                "        \"target_model\": \"qwen3-tts-vd-realtime-2026-01-15\",\n" +
                "        \"voice_prompt\": \"A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.\",\n" +
                "        \"preview_text\": \"Dear listeners, hello everyone. Welcome to the evening news.\",\n" +
                "        \"preferred_name\": \"announcer\",\n" +
                "        \"language\": \"en\"\n" +
                "    },\n" +
                "    \"parameters\": {\n" +
                "        \"sample_rate\": 24000,\n" +
                "        \"response_format\": \"wav\"\n" +
                "    }\n" +
                "}";

        HttpURLConnection connection = null;
        try {
            // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
            URL url = new URL("https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization");
            connection = (HttpURLConnection) url.openConnection();

            // Atur metode dan header permintaan
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Bearer " + apiKey);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);
            connection.setDoInput(true);

            // Kirim body permintaan
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = jsonBody.getBytes("UTF-8");
                os.write(input, 0, input.length);
                os.flush();
            }

            // Dapatkan respons
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // Baca konten respons
                StringBuilder response = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }
                }

                // Uraikan respons JSON
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();
                JsonObject outputObj = jsonResponse.getAsJsonObject("output");
                JsonObject previewAudioObj = outputObj.getAsJsonObject("preview_audio");

                // Dapatkan nama suara
                String voiceName = outputObj.get("voice").getAsString();
                System.out.println("Nama suara: " + voiceName);

                // Dapatkan data audio dalam format Base64
                String base64Audio = previewAudioObj.get("data").getAsString();

                // Dekode data audio Base64
                byte[] audioBytes = Base64.getDecoder().decode(base64Audio);

                // Simpan audio ke file lokal
                String filename = voiceName + "_preview.wav";
                saveAudioToFile(audioBytes, filename);

                System.out.println("Audio disimpan ke file lokal: " + filename);

            } else {
                // Baca respons kesalahan
                StringBuilder errorResponse = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getErrorStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        errorResponse.append(responseLine.trim());
                    }
                }

                System.out.println("Permintaan gagal dengan kode status: " + responseCode);
                System.out.println("Respons kesalahan: " + errorResponse.toString());
            }

        } catch (Exception e) {
            System.err.println("Terjadi kesalahan selama permintaan: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    private void saveAudioToFile(byte[] audioBytes, String filename) {
        try {
            File file = new File(filename);
            try (FileOutputStream fos = new FileOutputStream(file)) {
                fos.write(audioBytes);
            }
            System.out.println("Audio disimpan ke: " + file.getAbsolutePath());
        } catch (IOException e) {
            System.err.println("Terjadi kesalahan saat menyimpan file audio: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Gunakan suara kustom yang dihasilkan pada langkah sebelumnya untuk sintesis suara.

Contoh ini merujuk pada contoh kode "mode commit server" dari SDK DashScope untuk sintesis suara dengan suara sistem. Parameter voice diganti dengan suara kustom yang dihasilkan oleh desain suara.

Prinsip utama: Model yang digunakan untuk desain suara (target_model) harus sama dengan model yang digunakan untuk sintesis suara selanjutnya (model). Jika tidak, sintesis akan gagal.

Python

# coding=utf-8
# Petunjuk instalasi pyaudio:
# APPLE Mac OS X
#   brew install portaudio
#   pip install pyaudio
# Debian/Ubuntu
#   sudo apt-get install python-pyaudio python3-pyaudio
#   atau
#   pip install pyaudio
# CentOS
#   sudo yum install -y portaudio portaudio-devel && pip install pyaudio
# Microsoft Windows
#   python -m pip install pyaudio

import pyaudio
import os
import base64
import threading
import time
import dashscope  # Versi SDK Python DashScope harus 1.23.9 atau lebih baru
from dashscope.audio.qwen_tts_realtime import QwenTtsRealtime, QwenTtsRealtimeCallback, AudioFormat

# ======= Konfigurasi Konstan =======
TEXT_TO_SYNTHESIZE = [
    'Right? I really like this kind of supermarket,',
    'especially during the New Year.',
    'Going to the supermarket',
    'just makes me feel',
    'super, super happy!',
    'I want to buy so many things!'
]

def init_dashscope_api_key():
    """
    Inisialisasi Kunci API untuk SDK DashScope.
    """
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")

# ======= Kelas Callback =======
class MyCallback(QwenTtsRealtimeCallback):
    """
    Callback streaming TTS kustom.
    """
    def __init__(self):
        self.complete_event = threading.Event()
        self._player = pyaudio.PyAudio()
        self._stream = self._player.open(
            format=pyaudio.paInt16, channels=1, rate=24000, output=True
        )

    def on_open(self) -> None:
        print('[TTS] Koneksi berhasil dibuat')

    def on_close(self, close_status_code, close_msg) -> None:
        self._stream.stop_stream()
        self._stream.close()
        self._player.terminate()
        print(f'[TTS] Koneksi ditutup, kode={close_status_code}, pesan={close_msg}')

    def on_event(self, response: dict) -> None:
        try:
            event_type = response.get('type', '')
            if event_type == 'session.created':
                print(f'[TTS] Sesi dimulai: {response["session"]["id"]}')
            elif event_type == 'response.audio.delta':
                audio_data = base64.b64decode(response['delta'])
                self._stream.write(audio_data)
            elif event_type == 'response.done':
                print(f'[TTS] Respons selesai, ID Respons: {qwen_tts_realtime.get_last_response_id()}')
            elif event_type == 'session.finished':
                print('[TTS] Sesi selesai')
                self.complete_event.set()
        except Exception as e:
            print(f'[Error] Pengecualian saat memproses event callback: {e}')

    def wait_for_finished(self):
        self.complete_event.wait()

# ======= Logika Eksekusi Utama =======
if __name__ == '__main__':
    init_dashscope_api_key()
    print('[Sistem] Menginisialisasi Qwen TTS Realtime ...')

    callback = MyCallback()
    qwen_tts_realtime = QwenTtsRealtime(
        # Gunakan model yang sama untuk desain suara dan sintesis suara
        model="qwen3-tts-vd-realtime-2026-01-15",
        callback=callback,
        # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: wss://dashscope.aliyuncs.com/api-ws/v1/realtime
        url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime'
    )
    qwen_tts_realtime.connect()
    
    qwen_tts_realtime.update_session(
        voice="myvoice", # Ganti parameter voice dengan suara kustom yang dihasilkan oleh desain suara
        response_format=AudioFormat.PCM_24000HZ_MONO_16BIT,
        mode='server_commit'
    )

    for text_chunk in TEXT_TO_SYNTHESIZE:
        print(f'[Mengirim teks]: {text_chunk}')
        qwen_tts_realtime.append_text(text_chunk)
        time.sleep(0.1)

    qwen_tts_realtime.finish()
    callback.wait_for_finished()

    print(f'[Metrik] session_id={qwen_tts_realtime.get_session_id()}, '
          f'delay_audio_pertama={qwen_tts_realtime.get_first_audio_delay()}s')

Java

import com.alibaba.dashscope.audio.qwen_tts_realtime.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;

import javax.sound.sampled.*;
import java.io.*;
import java.util.Base64;
import java.util.Queue;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.atomic.AtomicBoolean;

public class Main {
    // ===== Definisi Konstan =====
    private static String[] textToSynthesize = {
            "Right? I really like this kind of supermarket,",
            "especially during the New Year.",
            "Going to the supermarket",
            "just makes me feel",
            "super, super happy!",
            "I want to buy so many things!"
    };

    // Kelas pemutar audio real-time
    public static class RealtimePcmPlayer {
        private int sampleRate;
        private SourceDataLine line;
        private AudioFormat audioFormat;
        private Thread decoderThread;
        private Thread playerThread;
        private AtomicBoolean stopped = new AtomicBoolean(false);
        private Queue<String> b64AudioBuffer = new ConcurrentLinkedQueue<>();
        private Queue<byte[]> RawAudioBuffer = new ConcurrentLinkedQueue<>();

        // Konstruktor menginisialisasi format audio dan jalur audio
        public RealtimePcmPlayer(int sampleRate) throws LineUnavailableException {
            this.sampleRate = sampleRate;
            this.audioFormat = new AudioFormat(this.sampleRate, 16, 1, true, false);
            DataLine.Info info = new DataLine.Info(SourceDataLine.class, audioFormat);
            line = (SourceDataLine) AudioSystem.getLine(info);
            line.open(audioFormat);
            line.start();
            decoderThread = new Thread(new Runnable() {
                @Override
                public void run() {
                    while (!stopped.get()) {
                        String b64Audio = b64AudioBuffer.poll();
                        if (b64Audio != null) {
                            byte[] rawAudio = Base64.getDecoder().decode(b64Audio);
                            RawAudioBuffer.add(rawAudio);
                        } else {
                            try {
                                Thread.sleep(100);
                            } catch (InterruptedException e) {
                                throw new RuntimeException(e);
                            }
                        }
                    }
                }
            });
            playerThread = new Thread(new Runnable() {
                @Override
                public void run() {
                    while (!stopped.get()) {
                        byte[] rawAudio = RawAudioBuffer.poll();
                        if (rawAudio != null) {
                            try {
                                playChunk(rawAudio);
                            } catch (IOException e) {
                                throw new RuntimeException(e);
                            } catch (InterruptedException e) {
                                throw new RuntimeException(e);
                            }
                        } else {
                            try {
                                Thread.sleep(100);
                            } catch (InterruptedException e) {
                                throw new RuntimeException(e);
                            }
                        }
                    }
                }
            });
            decoderThread.start();
            playerThread.start();
        }

        // Memutar chunk audio dan memblokir hingga pemutaran selesai
        private void playChunk(byte[] chunk) throws IOException, InterruptedException {
            if (chunk == null || chunk.length == 0) return;

            int bytesWritten = 0;
            while (bytesWritten < chunk.length) {
                bytesWritten += line.write(chunk, bytesWritten, chunk.length - bytesWritten);
            }
            int audioLength = chunk.length / (this.sampleRate*2/1000);
            // Tunggu hingga audio dalam buffer selesai diputar
            Thread.sleep(audioLength - 10);
        }

        public void write(String b64Audio) {
            b64AudioBuffer.add(b64Audio);
        }

        public void cancel() {
            b64AudioBuffer.clear();
            RawAudioBuffer.clear();
        }

        public void waitForComplete() throws InterruptedException {
            while (!b64AudioBuffer.isEmpty() || !RawAudioBuffer.isEmpty()) {
                Thread.sleep(100);
            }
            line.drain();
        }

        public void shutdown() throws InterruptedException {
            stopped.set(true);
            decoderThread.join();
            playerThread.join();
            if (line != null && line.isRunning()) {
                line.drain();
                line.close();
            }
        }
    }

    public static void main(String[] args) throws Exception {
        QwenTtsRealtimeParam param = QwenTtsRealtimeParam.builder()
                // Gunakan model yang sama untuk desain suara dan sintesis suara
                .model("qwen3-tts-vd-realtime-2026-01-15")
                // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: wss://dashscope.aliyuncs.com/api-ws/v1/realtime
                .url("wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime")
                // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
                // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: .apikey("sk-xxx")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        AtomicReference<CountDownLatch> completeLatch = new AtomicReference<>(new CountDownLatch(1));
        final AtomicReference<QwenTtsRealtime> qwenTtsRef = new AtomicReference<>(null);

        // Buat instance pemutar audio real-time
        RealtimePcmPlayer audioPlayer = new RealtimePcmPlayer(24000);

        QwenTtsRealtime qwenTtsRealtime = new QwenTtsRealtime(param, new QwenTtsRealtimeCallback() {
            @Override
            public void onOpen() {
                // Penanganan saat koneksi berhasil dibuat
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        // Penanganan saat sesi dibuat
                        break;
                    case "response.audio.delta":
                        String recvAudioB64 = message.get("delta").getAsString();
                        // Putar audio secara real-time
                        audioPlayer.write(recvAudioB64);
                        break;
                    case "response.done":
                        // Penanganan saat respons selesai
                        break;
                    case "session.finished":
                        // Penanganan saat sesi selesai
                        completeLatch.get().countDown();
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                // Penanganan saat koneksi ditutup
            }
        });
        qwenTtsRef.set(qwenTtsRealtime);
        try {
            qwenTtsRealtime.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }
        QwenTtsRealtimeConfig config = QwenTtsRealtimeConfig.builder()
                .voice("myvoice") // Ganti parameter voice dengan suara kustom yang dihasilkan oleh desain suara
                .responseFormat(QwenTtsRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
                .mode("server_commit")
                .build();
        qwenTtsRealtime.updateSession(config);
        for (String text:textToSynthesize) {
            qwenTtsRealtime.appendText(text);
            Thread.sleep(100);
        }
        qwenTtsRealtime.finish();
        completeLatch.get().await();

        // Tunggu hingga pemutaran audio selesai dan matikan pemutar
        audioPlayer.waitForComplete();
        audioPlayer.shutdown();
        System.exit(0);
    }
}

Sintesis non-streaming/streaming satu arah

Ini berlaku untuk rangkaian model Qwen3-TTS-VC. Untuk informasi lebih lanjut, lihat Sintesis Suara - Qwen.

Hasilkan suara kustom dan pratinjau hasilnya. Jika Anda puas dengan hasilnya, lanjutkan ke langkah berikutnya. Jika tidak, hasilkan kembali.

Python

import requests
import base64
import os

def create_voice_and_play():
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    if not api_key:
        print("Error: Variabel lingkungan DASHSCOPE_API_KEY tidak ditemukan. Harap atur Kunci API terlebih dahulu.")
        return None, None, None
    
    # Siapkan data permintaan
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "qwen-voice-design",
        "input": {
            "action": "create",
            "target_model": "qwen3-tts-vd-2026-01-26",
            "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
            "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
            "preferred_name": "announcer",
            "language": "en"
        },
        "parameters": {
            "sample_rate": 24000,
            "response_format": "wav"
        }
    }
    
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    
    try:
        # Kirim permintaan
        response = requests.post(
            url,
            headers=headers,
            json=data,
            timeout=60  # Tambahkan pengaturan timeout
        )
        
        if response.status_code == 200:
            result = response.json()
            
            # Dapatkan nama suara
            voice_name = result["output"]["voice"]
            print(f"Nama suara: {voice_name}")
            
            # Dapatkan data audio pratinjau
            base64_audio = result["output"]["preview_audio"]["data"]
            
            # Dekode data audio Base64
            audio_bytes = base64.b64decode(base64_audio)
            
            # Simpan file audio secara lokal
            filename = f"{voice_name}_preview.wav"
            
            # Tulis data audio ke file lokal
            with open(filename, 'wb') as f:
                f.write(audio_bytes)
            
            print(f"Audio disimpan ke file lokal: {filename}")
            print(f"Jalur file: {os.path.abspath(filename)}")
            
            return voice_name, audio_bytes, filename
        else:
            print(f"Permintaan gagal dengan kode status: {response.status_code}")
            print(f"Konten respons: {response.text}")
            return None, None, None
            
    except requests.exceptions.RequestException as e:
        print(f"Terjadi kesalahan permintaan jaringan: {e}")
        return None, None, None
    except KeyError as e:
        print(f"Kesalahan format data respons, bidang wajib tidak ditemukan: {e}")
        print(f"Konten respons: {response.text if 'response' in locals() else 'No response'}")
        return None, None, None
    except Exception as e:
        print(f"Terjadi kesalahan tidak diketahui: {e}")
        return None, None, None

if __name__ == "__main__":
    print("Mulai membuat suara...")
    voice_name, audio_data, saved_filename = create_voice_and_play()
    
    if voice_name:
        print(f"\nBerhasil membuat suara '{voice_name}'")
        print(f"File audio disimpan sebagai: '{saved_filename}'")
        print(f"Ukuran file: {os.path.getsize(saved_filename)} byte")
    else:
        print("\nPembuatan suara gagal")

Java

Anda perlu mengimpor dependensi Gson. Jika menggunakan Maven atau Gradle, tambahkan dependensi sebagai berikut:

Maven

Tambahkan konten berikut ke 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>

Gradle

Tambahkan konten berikut ke build.gradle:

// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")

Penting

Saat menggunakan suara kustom yang dihasilkan oleh desain suara untuk sintesis suara, Anda harus mengatur suara sebagai berikut:

MultiModalConversationParam param = MultiModalConversationParam.builder()
                .parameter("voice", "your_voice") // Ganti parameter voice dengan suara kustom yang dihasilkan oleh desain suara
                .build();

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class Main {
    public static void main(String[] args) {
        Main example = new Main();
        example.createVoice();
    }

    public void createVoice() {
        // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Buat string body permintaan JSON
        String jsonBody = "{\n" +
                "    \"model\": \"qwen-voice-design\",\n" +
                "    \"input\": {\n" +
                "        \"action\": \"create\",\n" +
                "        \"target_model\": \"qwen3-tts-vd-2026-01-26\",\n" +
                "        \"voice_prompt\": \"A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.\",\n" +
                "        \"preview_text\": \"Dear listeners, hello everyone. Welcome to the evening news.\",\n" +
                "        \"preferred_name\": \"announcer\",\n" +
                "        \"language\": \"en\"\n" +
                "    },\n" +
                "    \"parameters\": {\n" +
                "        \"sample_rate\": 24000,\n" +
                "        \"response_format\": \"wav\"\n" +
                "    }\n" +
                "}";

        HttpURLConnection connection = null;
        try {
            // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
            URL url = new URL("https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization");
            connection = (HttpURLConnection) url.openConnection();

            // Atur metode dan header permintaan
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Bearer " + apiKey);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);
            connection.setDoInput(true);

            // Kirim body permintaan
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = jsonBody.getBytes("UTF-8");
                os.write(input, 0, input.length);
                os.flush();
            }

            // Dapatkan respons
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // Baca konten respons
                StringBuilder response = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }
                }

                // Uraikan respons JSON
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();
                JsonObject outputObj = jsonResponse.getAsJsonObject("output");
                JsonObject previewAudioObj = outputObj.getAsJsonObject("preview_audio");

                // Dapatkan nama suara
                String voiceName = outputObj.get("voice").getAsString();
                System.out.println("Nama suara: " + voiceName);

                // Dapatkan data audio dalam format Base64
                String base64Audio = previewAudioObj.get("data").getAsString();

                // Dekode data audio Base64
                byte[] audioBytes = Base64.getDecoder().decode(base64Audio);

                // Simpan audio ke file lokal
                String filename = voiceName + "_preview.wav";
                saveAudioToFile(audioBytes, filename);

                System.out.println("Audio disimpan ke file lokal: " + filename);

            } else {
                // Baca respons kesalahan
                StringBuilder errorResponse = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getErrorStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        errorResponse.append(responseLine.trim());
                    }
                }

                System.out.println("Permintaan gagal dengan kode status: " + responseCode);
                System.out.println("Respons kesalahan: " + errorResponse.toString());
            }

        } catch (Exception e) {
            System.err.println("Terjadi kesalahan selama permintaan: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    private void saveAudioToFile(byte[] audioBytes, String filename) {
        try {
            File file = new File(filename);
            try (FileOutputStream fos = new FileOutputStream(file)) {
                fos.write(audioBytes);
            }
            System.out.println("Audio disimpan ke: " + file.getAbsolutePath());
        } catch (IOException e) {
            System.err.println("Terjadi kesalahan saat menyimpan file audio: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Gunakan suara kustom yang dihasilkan pada langkah sebelumnya untuk sintesis suara non-streaming.

Contoh ini merujuk pada contoh kode "keluaran non-streaming" dari SDK DashScope untuk sintesis suara dengan suara sistem. Parameter voice diganti dengan suara kustom yang dihasilkan oleh desain suara. Untuk sintesis streaming satu arah, lihat Sintesis Suara - Qwen.

Prinsip utama: Model yang digunakan untuk desain suara (target_model) harus sama dengan model yang digunakan untuk sintesis suara selanjutnya (model). Jika tidak, sintesis akan gagal.

Python

import os
import dashscope


if __name__ == '__main__':
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1
    dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

    text = "How is the weather today?"
    # Cara menggunakan antarmuka SpeechSynthesizer: dashscope.audio.qwen_tts.SpeechSynthesizer.call(...)
    response = dashscope.MultiModalConversation.call(
        model="qwen3-tts-vd-2026-01-26",
        # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        text=text,
        voice="myvoice", # Ganti parameter voice dengan suara kustom yang dihasilkan oleh desain suara
        stream=False
    )
    print(response)

Java

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-vd-2026-01-26";
    public static void call() throws ApiException, NoApiKeyException, UploadFileException {
        MultiModalConversation conv = new MultiModalConversation();
        MultiModalConversationParam param = MultiModalConversationParam.builder()
                // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
                // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: .apiKey("sk-xxx")
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .model(MODEL)
                .text("Today is a wonderful day to build something people love!")
                .parameter("voice", "myvoice") // Ganti parameter voice dengan suara kustom yang dihasilkan oleh desain suara
                .build();
        MultiModalConversationResult result = conv.call(param);
        String audioUrl = result.getOutput().getAudio().getUrl();
        System.out.print(audioUrl);

        // Unduh file audio secara lokal
        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("\nFile audio diunduh ke lokal: downloaded_audio.wav");
        } catch (Exception e) {
            System.out.println("\nKesalahan mengunduh file audio: " + e.getMessage());
        }
    }
    public static void main(String[] args) {
        try {
            // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1
            Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
            call();
        } catch (ApiException | NoApiKeyException | UploadFileException e) {
            System.out.println(e.getMessage());
        }
        System.exit(0);
    }
}

Referensi API

Saat menggunakan API berbeda, pastikan menggunakan akun yang sama untuk semua operasi.

Buat suara

Membuat suara kustom dengan menyediakan deskripsi suara dan teks pratinjau.

URL

Tiongkok Daratan:

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

Internasional:

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

Header Permintaan

Parameter	Jenis	Wajib	Deskripsi
Authorization	string	Didukung	Token autentikasi dalam format `Bearer <your_api_key>`. Saat menggunakannya, ganti "`<your_api_key>`" dengan Kunci API aktual Anda.
Content-Type	string	Didukung	Tipe media data yang ditransfer dalam body permintaan. Nilai ini tetap `application/json`.

Isi Pesan

Body permintaan berisi semua parameter permintaan seperti di bawah ini. Anda dapat menghilangkan bidang opsional sesuai kebutuhan bisnis Anda.

Penting

Perhatikan perbedaan antara parameter berikut:

model: Model desain suara, tetap qwen-voice-design.
target_model: Model sintesis suara yang menggerakkan suara. Harus sama dengan model sintesis suara yang digunakan saat memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal.

{
    "model": "qwen-voice-design",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "preferred_name": "announcer",
        "language": "zh"
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}

Parameter permintaan

Parameter	Tipe	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model desain suara, tetap `qwen-voice-design`.
action	string	-	Didukung	Tipe operasi, tetap `create`.
target_model	string	-	Ya	Model sintesis suara yang menggerakkan suara. Model yang didukung meliputi (dua tipe): Qwen3-TTS-VD-Realtime (lihat Sintesis Suara Real-time - Qwen): qwen3-tts-vd-realtime-2026-01-15 qwen3-tts-vd-realtime-2025-12-16 Qwen3-TTS-VD (lihat Sintesis Suara - Qwen): qwen3-tts-vd-2026-01-26 Harus sama dengan model sintesis suara yang digunakan saat memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal.
voice_prompt	string	-	Didukung	Deskripsi suara. Panjang maksimum: 2048 karakter. Hanya mendukung Bahasa Tiongkok dan Bahasa Inggris. Untuk informasi cara menulis deskripsi suara, lihat "Menulis deskripsi suara".
preview_text	string	-	Didukung	Teks yang sesuai dengan audio pratinjau. Panjang maksimum: 1024 karakter. Mendukung Bahasa Tiongkok (zh), Bahasa Inggris (en), Bahasa Jerman (de), Bahasa Italia (it), Bahasa Portugis (pt), Bahasa Spanyol (es), Bahasa Jepang (ja), Bahasa Korea (ko), Bahasa Prancis (fr), dan Bahasa Rusia (ru).
preferred_name	string	-	Didukung	Berikan nama yang mudah dikenali untuk suara tersebut (hanya angka, huruf Inggris, dan garis bawah yang diizinkan, maksimal 16 karakter). Kami merekomendasikan menggunakan pengenal yang terkait dengan karakter atau skenario. Kata kunci ini akan muncul dalam nama suara yang dirancang. Misalnya, jika kata kuncinya "announcer", nama suara akhir akan menjadi "qwen-tts-vd-announcer-voice-20251201102800-a1b2".
language	string	zh	Tidak	Kode bahasa, yang menentukan preferensi bahasa untuk suara yang dihasilkan. Parameter ini memengaruhi fitur bahasa dan kecenderungan pelafalan suara yang dihasilkan. Kami merekomendasikan memilih kode bahasa yang sesuai berdasarkan kasus penggunaan aktual Anda. Jika Anda menggunakan parameter ini, bahasa yang Anda atur harus sesuai dengan bahasa `preview_text`. Nilai yang valid: `zh` (Bahasa Tiongkok), `en` (Bahasa Inggris), `de` (Bahasa Jerman), `it` (Bahasa Italia), `pt` (Bahasa Portugis), `es` (Bahasa Spanyol), `ja` (Bahasa Jepang), `ko` (Bahasa Korea), `fr` (Bahasa Prancis), `ru` (Bahasa Rusia).
sample_rate	int	24000	Tidak didukung	Laju sampel (dalam Hz) audio pratinjau yang dihasilkan oleh desain suara. Nilai yang valid: 8000 16000 24000 48000
response_format	string	wav	Tidak didukung	Format audio pratinjau yang dihasilkan oleh desain suara. Nilai yang valid: pcm wav mp3 opus

Parameter respons

Klik untuk melihat contoh respons

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice": "yourVoice"
    },
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Parameter berikut adalah:

Parameter	Tipe	Deskripsi
voice	string	Nama suara, yang dapat digunakan langsung untuk parameter `voice` dalam API sintesis suara.
data	string	Data audio pratinjau yang dihasilkan oleh desain suara, dikembalikan sebagai string yang dienkripsi Base64.
sample_rate	int	Laju sampel (dalam Hz) audio pratinjau yang dihasilkan oleh desain suara. Sesuai dengan laju sampel yang diatur saat pembuatan suara, default 24000 Hz jika tidak ditentukan.
response_format	string	Format audio pratinjau yang dihasilkan oleh desain suara. Sesuai dengan format audio yang diatur saat pembuatan suara, default wav jika tidak ditentukan.
target_model	string	Model sintesis suara yang menggerakkan suara. Model yang didukung meliputi (dua tipe): Qwen3-TTS-VD-Realtime (lihat Sintesis Suara Real-time - Qwen): qwen3-tts-vd-realtime-2026-01-15 qwen3-tts-vd-realtime-2025-12-16 Qwen3-TTS-VD (lihat Sintesis Suara - Qwen): qwen3-tts-vd-2026-01-26 Harus sama dengan model sintesis suara yang digunakan saat memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal.
request_id	string	ID permintaan.
count	integer	Jumlah operasi "buat suara" yang ditagih untuk permintaan ini. Biaya untuk permintaan ini adalah $ $co u n t \times 0.2$ Saat membuat suara, count selalu 1.

Contoh kode

Penting

Perhatikan perbedaan antara parameter berikut:

model: Model desain suara, tetap qwen-voice-design.
target_model: Model sintesis suara yang menggerakkan suara. Harus sama dengan model sintesis suara yang digunakan saat memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal.

cURL

Jika Anda belum mengonfigurasi Kunci API sebagai variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan Kunci API aktual Anda.

https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization<a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="28f184e9f7vq7">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization</a># ======= Catatan Penting =======
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
# === Hapus komentar ini sebelum eksekusi ===

curl -X POST <a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="28f184e9f7vq7">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization</a> \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "preferred_name": "announcer",
        "language": "zh"
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

Python

import requests
import base64
import os

def create_voice_and_play():
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    if not api_key:
        print("Error: Variabel lingkungan DASHSCOPE_API_KEY tidak ditemukan. Harap atur Kunci API terlebih dahulu.")
        return None, None, None
    
    # Siapkan data permintaan
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "qwen-voice-design",
        "input": {
            "action": "create",
            "target_model": "qwen3-tts-vd-realtime-2026-01-15",
            "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
            "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
            "preferred_name": "announcer",
            "language": "en"
        },
        "parameters": {
            "sample_rate": 24000,
            "response_format": "wav"
        }
    }
    
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    
    try:
        # Kirim permintaan
        response = requests.post(
            url,
            headers=headers,
            json=data,
            timeout=60  # Tambahkan pengaturan timeout
        )
        
        if response.status_code == 200:
            result = response.json()
            
            # Dapatkan nama suara
            voice_name = result["output"]["voice"]
            print(f"Nama suara: {voice_name}")
            
            # Dapatkan data audio pratinjau
            base64_audio = result["output"]["preview_audio"]["data"]
            
            # Dekode data audio Base64
            audio_bytes = base64.b64decode(base64_audio)
            
            # Simpan file audio secara lokal
            filename = f"{voice_name}_preview.wav"
            
            # Tulis data audio ke file lokal
            with open(filename, 'wb') as f:
                f.write(audio_bytes)
            
            print(f"Audio disimpan ke file lokal: {filename}")
            print(f"Jalur file: {os.path.abspath(filename)}")
            
            return voice_name, audio_bytes, filename
        else:
            print(f"Permintaan gagal dengan kode status: {response.status_code}")
            print(f"Konten respons: {response.text}")
            return None, None, None
            
    except requests.exceptions.RequestException as e:
        print(f"Terjadi kesalahan permintaan jaringan: {e}")
        return None, None, None
    except KeyError as e:
        print(f"Kesalahan format data respons, bidang wajib tidak ditemukan: {e}")
        print(f"Konten respons: {response.text if 'response' in locals() else 'No response'}")
        return None, None, None
    except Exception as e:
        print(f"Terjadi kesalahan tidak diketahui: {e}")
        return None, None, None

if __name__ == "__main__":
    print("Mulai membuat suara...")
    voice_name, audio_data, saved_filename = create_voice_and_play()
    
    if voice_name:
        print(f"\nBerhasil membuat suara '{voice_name}'")
        print(f"File audio disimpan sebagai: '{saved_filename}'")
        print(f"Ukuran file: {os.path.getsize(saved_filename)} byte")
    else:
        print("\nPembuatan suara gagal")

Java

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class Main {
    public static void main(String[] args) {
        Main example = new Main();
        example.createVoice();
    }

    public void createVoice() {
        // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Buat string body permintaan JSON
        String jsonBody = "{\n" +
                "    \"model\": \"qwen-voice-design\",\n" +
                "    \"input\": {\n" +
                "        \"action\": \"create\",\n" +
                "        \"target_model\": \"qwen3-tts-vd-realtime-2026-01-15\",\n" +
                "        \"voice_prompt\": \"A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.\",\n" +
                "        \"preview_text\": \"Dear listeners, hello everyone. Welcome to the evening news.\",\n" +
                "        \"preferred_name\": \"announcer\",\n" +
                "        \"language\": \"en\"\n" +
                "    },\n" +
                "    \"parameters\": {\n" +
                "        \"sample_rate\": 24000,\n" +
                "        \"response_format\": \"wav\"\n" +
                "    }\n" +
                "}";

        HttpURLConnection connection = null;
        try {
            // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
            URL url = new URL("https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization");
            connection = (HttpURLConnection) url.openConnection();

            // Atur metode dan header permintaan
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Bearer " + apiKey);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);
            connection.setDoInput(true);

            // Kirim body permintaan
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = jsonBody.getBytes("UTF-8");
                os.write(input, 0, input.length);
                os.flush();
            }

            // Dapatkan respons
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // Baca konten respons
                StringBuilder response = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }
                }

                // Uraikan respons JSON
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();
                JsonObject outputObj = jsonResponse.getAsJsonObject("output");
                JsonObject previewAudioObj = outputObj.getAsJsonObject("preview_audio");

                // Dapatkan nama suara
                String voiceName = outputObj.get("voice").getAsString();
                System.out.println("Nama suara: " + voiceName);

                // Dapatkan data audio dalam format Base64
                String base64Audio = previewAudioObj.get("data").getAsString();

                // Dekode data audio Base64
                byte[] audioBytes = Base64.getDecoder().decode(base64Audio);

                // Simpan audio ke file lokal
                String filename = voiceName + "_preview.wav";
                saveAudioToFile(audioBytes, filename);

                System.out.println("Audio disimpan ke file lokal: " + filename);

            } else {
                // Baca respons kesalahan
                StringBuilder errorResponse = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getErrorStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        errorResponse.append(responseLine.trim());
                    }
                }

                System.out.println("Permintaan gagal dengan kode status: " + responseCode);
                System.out.println("Respons kesalahan: " + errorResponse.toString());
            }

        } catch (Exception e) {
            System.err.println("Terjadi kesalahan selama permintaan: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    private void saveAudioToFile(byte[] audioBytes, String filename) {
        try {
            File file = new File(filename);
            try (FileOutputStream fos = new FileOutputStream(file)) {
                fos.write(audioBytes);
            }
            System.out.println("Audio disimpan ke: " + file.getAbsolutePath());
        } catch (IOException e) {
            System.err.println("Terjadi kesalahan saat menyimpan file audio: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Kueri daftar suara

Menjalankan kueri terpaginasi untuk daftar suara yang telah dibuat.

URL

Tiongkok Daratan:

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

Internasional:

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

Header Permintaan

Parameter	Tipe	Wajib	Deskripsi
Authorization	string	Didukung	Token autentikasi dalam format `Bearer <your_api_key>`. Ganti "`<your_api_key>`" dengan Kunci API aktual Anda.
Content-Type	string	Didukung	Tipe media data yang ditransmisikan dalam body permintaan. Tetap `application/json`.

Body permintaan
Body permintaan berisi semua parameter permintaan seperti di bawah ini. Hilangkan bidang opsional sesuai kebutuhan bisnis Anda.
Penting
model: Model desain suara, tetap qwen-voice-design. Jangan ubah nilai ini.
```
{
    "model": "qwen-voice-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}
```

Parameter permintaan

Parameter	Type	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model desain suara, tetap `qwen-voice-design`.
action	string	-	Didukung	Tipe operasi, tetap `list`.
page_index	integer	0	Tidak didukung	Indeks nomor halaman. Rentang: [0, 200].
page_size	integer	10	Tidak didukung	Entri per halaman. Nilainya harus lebih besar dari 0.

Parameter respons

Klik untuk melihat contoh respons

{
    "output": {
        "page_index": 0,
        "page_size": 2,
        "total_count": 26,
        "voice_list": [
            {
                "gmt_create": "2025-12-10 17:04:54",
                "gmt_modified": "2025-12-10 17:04:54",
                "language": "zh",
                "preview_text": "Dear listeners, hello everyone. Welcome to today's program.",
                "target_model": "qwen3-tts-vd-realtime-2026-01-15",
                "voice": "yourVoice1",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary., deep and magnetic, with a steady pace"
            },
            {
                "gmt_create": "2025-12-10 15:31:35",
                "gmt_modified": "2025-12-10 15:31:35",
                "language": "zh",
                "preview_text": "Dear listeners, hello everyone",
                "target_model": "qwen3-tts-vd-realtime-2026-01-15",
                "voice": "yourVoice2",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
            }
        ]
    },
    "usage": {},
    "request_id": "yourRequestId"
}

Parameter berikut adalah:

Parameter	Tipe	Deskripsi
voice	string	Nama suara, yang dapat digunakan langsung untuk parameter `voice` dalam API sintesis suara.
target_model	string	Model sintesis suara yang menggerakkan suara. Model yang didukung meliputi (dua tipe): Qwen3-TTS-VD-Realtime (lihat Sintesis Suara Real-time - Qwen): qwen3-tts-vd-realtime-2026-01-15 qwen3-tts-vd-realtime-2025-12-16 Qwen3-TTS-VD (lihat Sintesis Suara - Qwen): qwen3-tts-vd-2026-01-26 Harus sama dengan model sintesis suara yang digunakan saat memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal.
language	string	Kode bahasa. Nilai yang valid: `zh` (Bahasa Tiongkok), `en` (Bahasa Inggris), `de` (Bahasa Jerman), `it` (Bahasa Italia), `pt` (Bahasa Portugis), `es` (Bahasa Spanyol), `ja` (Bahasa Jepang), `ko` (Bahasa Korea), `fr` (Bahasa Prancis), `ru` (Bahasa Rusia).
voice_prompt	string	Deskripsi suara.
preview_text	string	Teks pratinjau.
gmt_create	string	Waktu suara dibuat.
gmt_modified	string	Waktu suara dimodifikasi.
page_index	integer	Indeks nomor halaman.
page_size	integer	Entri per halaman.
total_count	integer	Jumlah total entri data yang ditemukan.
request_id	string	ID permintaan.

Contoh kode

Penting

model: Model desain suara, tetap qwen-voice-design. Jangan ubah nilai ini.

cURL

Jika Anda belum mengonfigurasi Kunci API sebagai variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan Kunci API aktual Anda.

# ======= Catatan Penting =======
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
# === Hapus komentar ini sebelum eksekusi ===

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

Python

import os
import requests

# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
# Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key = os.getenv("DASHSCOPE_API_KEY")
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"

payload = {
    "model": "qwen-voice-design", # Jangan ubah nilai ini
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print("Kode Status HTTP:", response.status_code)

if response.status_code == 200:
    data = response.json()
    voice_list = data["output"]["voice_list"]

    print("Daftar suara yang dikueri:")
    for item in voice_list:
        print(f"- Suara: {item['voice']}  Waktu Pembuatan: {item['gmt_create']}  Model: {item['target_model']}")
else:
    print("Permintaan gagal:", response.text)

Java

import com.google.gson.Gson;
import com.google.gson.JsonArray;
import com.google.gson.JsonObject;

import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {
    public static void main(String[] args) {
        // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
        String apiUrl = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization";

        // Body permintaan JSON (versi Java lama tidak memiliki string multiline """")
        String jsonPayload =
                "{"
                        + "\"model\": \"qwen-voice-design\"," // Jangan ubah nilai ini
                        + "\"input\": {"
                        +     "\"action\": \"list\","
                        +     "\"page_size\": 10,"
                        +     "\"page_index\": 0"
                        + "}"
                        + "}";

        try {
            HttpURLConnection con = (HttpURLConnection) new URL(apiUrl).openConnection();
            con.setRequestMethod("POST");
            con.setRequestProperty("Authorization", "Bearer " + apiKey);
            con.setRequestProperty("Content-Type", "application/json");
            con.setDoOutput(true);

            try (OutputStream os = con.getOutputStream()) {
                os.write(jsonPayload.getBytes("UTF-8"));
            }

            int status = con.getResponseCode();
            BufferedReader br = new BufferedReader(new InputStreamReader(
                    status >= 200 && status < 300 ? con.getInputStream() : con.getErrorStream(), "UTF-8"));

            StringBuilder response = new StringBuilder();
            String line;
            while ((line = br.readLine()) != null) {
                response.append(line);
            }
            br.close();

            System.out.println("Kode Status HTTP: " + status);
            System.out.println("JSON yang Dikembalikan: " + response.toString());

            if (status == 200) {
                Gson gson = new Gson();
                JsonObject jsonObj = gson.fromJson(response.toString(), JsonObject.class);
                JsonArray voiceList = jsonObj.getAsJsonObject("output").getAsJsonArray("voice_list");

                System.out.println("\n Daftar suara yang dikueri:");
                for (int i = 0; i < voiceList.size(); i++) {
                    JsonObject voiceItem = voiceList.get(i).getAsJsonObject();
                    String voice = voiceItem.get("voice").getAsString();
                    String gmtCreate = voiceItem.get("gmt_create").getAsString();
                    String targetModel = voiceItem.get("target_model").getAsString();

                    System.out.printf("- Suara: %s  Waktu Pembuatan: %s  Model: %s\n",
                            voice, gmtCreate, targetModel);
                }
            }

        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Kueri suara tertentu

Mendapatkan informasi detail tentang suara tertentu berdasarkan namanya.

URL

Tiongkok Daratan:

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

Internasional:

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

Header Permintaan

Parameter	Tipe	Wajib	Deskripsi
Authorization	string	Didukung	Token autentikasi dalam format `Bearer <your_api_key>`. Ganti "`<your_api_key>`" dengan Kunci API aktual Anda.
Content-Type	string	Didukung	Tipe media data yang ditransmisikan dalam body permintaan. Tetap `application/json`.

Isi permintaan
Body permintaan berisi semua parameter permintaan seperti di bawah ini. Hilangkan bidang opsional sesuai kebutuhan bisnis Anda.
Penting
model: Model desain suara, tetap qwen-voice-design. Jangan ubah nilai ini.
```
{
    "model": "qwen-voice-design",
    "input": {
        "action": "query",
        "voice": "voiceName"
    }
}
```
Parameter permintaan
Parameter
Tipe
Bawaan
Wajib
Deskripsi
model
string
-
Didukung
Model desain suara, tetap qwen-voice-design.
action
string
-
Didukung
Tipe operasi, tetap query.
voice
string
-
Didukung
Nama suara yang akan dikueri.

Parameter respons

Klik untuk melihat contoh respons

Data ditemukan

{
    "output": {
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "language": "zh",
        "preview_text": "Dear listeners, hello everyone",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice": "yourVoice",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
    },
    "usage": {},
    "request_id": "yourRequestId"
}

Data tidak ditemukan

Saat suara yang dikueri tidak ada, API mengembalikan kode status HTTP 400, dan body respons berisi kode kesalahan VoiceNotFound.

{
    "request_id":"yourRequestId",
    "code":"VoiceNotFound",
    "message":"Voice not found: qwen-tts-vd-announcer-voice-xxxx"
}

Parameter berikut adalah:

Parameter	Tipe	Deskripsi
voice	string	Nama suara, yang dapat digunakan langsung untuk parameter `voice` dalam API sintesis suara.
target_model	string	Model sintesis suara yang menggerakkan suara. Model yang didukung meliputi (dua tipe): Qwen3-TTS-VD-Realtime (lihat Sintesis Suara Real-time - Qwen): qwen3-tts-vd-realtime-2026-01-15 qwen3-tts-vd-realtime-2025-12-16 Qwen3-TTS-VD (lihat Sintesis Suara - Qwen): qwen3-tts-vd-2026-01-26 Harus sama dengan model sintesis suara yang digunakan saat memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal.
language	string	Kode bahasa. Nilai yang valid: `zh` (Bahasa Tiongkok), `en` (Bahasa Inggris), `de` (Bahasa Jerman), `it` (Bahasa Italia), `pt` (Bahasa Portugis), `es` (Bahasa Spanyol), `ja` (Bahasa Jepang), `ko` (Bahasa Korea), `fr` (Bahasa Prancis), `ru` (Bahasa Rusia).
voice_prompt	string	Deskripsi suara.
preview_text	string	Teks pratinjau.
gmt_create	string	Waktu suara dibuat.
gmt_modified	string	Waktu suara dimodifikasi.
request_id	string	ID permintaan.

Contoh kode

Penting

model: Model desain suara, tetap qwen-voice-design. Jangan ubah nilai ini.

cURL

Jika Anda belum mengonfigurasi Kunci API sebagai variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan Kunci API aktual Anda.

# ======= Catatan Penting =======
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
# === Hapus komentar ini sebelum eksekusi ===

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "query",
        "voice": "voiceName"
    }
}'

Python

import requests
import os

def query_voice(voice_name):
    """
    Kueri informasi untuk suara tertentu.
    :param voice_name: Nama suara.
    :return: Dictionary berisi informasi suara, atau None jika tidak ditemukan.
    """
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    # Siapkan data permintaan
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "qwen-voice-design",
        "input": {
            "action": "query",
            "voice": voice_name
        }
    }
    
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    # Kirim permintaan
    response = requests.post(
        url,
        headers=headers,
        json=data
    )
    
    if response.status_code == 200:
        result = response.json()
        
        # Periksa pesan kesalahan
        if "code" in result and result["code"] == "VoiceNotFound":
            print(f"Suara tidak ditemukan: {voice_name}")
            print(f"Pesan kesalahan: {result.get('message', 'Suara tidak ditemukan')}")
            return None
        
        # Dapatkan informasi suara
        voice_info = result["output"]
        print(f"Berhasil mengkueri informasi suara:")
        print(f"  Nama Suara: {voice_info.get('voice')}")
        print(f"  Waktu Pembuatan: {voice_info.get('gmt_create')}")
        print(f"  Waktu Modifikasi: {voice_info.get('gmt_modified')}")
        print(f"  Bahasa: {voice_info.get('language')}")
        print(f"  Teks Pratinjau: {voice_info.get('preview_text')}")
        print(f"  Model: {voice_info.get('target_model')}")
        print(f"  Deskripsi Suara: {voice_info.get('voice_prompt')}")
        
        return voice_info
    else:
        print(f"Permintaan gagal dengan kode status: {response.status_code}")
        print(f"Konten respons: {response.text}")
        return None

def main():
    # Contoh: Kueri suara
    voice_name = "myvoice"  # Ganti dengan nama suara aktual yang ingin Anda kueri
    
    print(f"Mengkueri suara: {voice_name}")
    voice_info = query_voice(voice_name)
    
    if voice_info:
        print("\nKueri suara berhasil!")
    else:
        print("\nKueri suara gagal atau suara tidak ada.")

if __name__ == "__main__":
    main()

Java

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {

    public static void main(String[] args) {
        Main example = new Main();
        // Contoh: Kueri suara
        String voiceName = "myvoice"; // Ganti dengan nama suara aktual yang ingin Anda kueri
        System.out.println("Mengkueri suara: " + voiceName);
        example.queryVoice(voiceName);
    }

    public void queryVoice(String voiceName) {
        // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Buat string body permintaan JSON
        String jsonBody = "{\n" +
                "    \"model\": \"qwen-voice-design\",\n" +
                "    \"input\": {\n" +
                "        \"action\": \"query\",\n" +
                "        \"voice\": \"" + voiceName + "\"\n" +
                "    }\n" +
                "}";

        HttpURLConnection connection = null;
        try {
            // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
            URL url = new URL("https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization");
            connection = (HttpURLConnection) url.openConnection();

            // Atur metode dan header permintaan
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Bearer " + apiKey);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);
            connection.setDoInput(true);

            // Kirim body permintaan
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = jsonBody.getBytes("UTF-8");
                os.write(input, 0, input.length);
                os.flush();
            }

            // Dapatkan respons
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // Baca konten respons
                StringBuilder response = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }
                }

                // Uraikan respons JSON
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();

                // Periksa pesan kesalahan
                if (jsonResponse.has("code") && "VoiceNotFound".equals(jsonResponse.get("code").getAsString())) {
                    String errorMessage = jsonResponse.has("message") ?
                            jsonResponse.get("message").getAsString() : "Suara tidak ditemukan";
                    System.out.println("Suara tidak ditemukan: " + voiceName);
                    System.out.println("Pesan kesalahan: " + errorMessage);
                    return;
                }

                // Dapatkan informasi suara
                JsonObject outputObj = jsonResponse.getAsJsonObject("output");

                System.out.println("Berhasil mengkueri informasi suara:");
                System.out.println("  Nama Suara: " + outputObj.get("voice").getAsString());
                System.out.println("  Waktu Pembuatan: " + outputObj.get("gmt_create").getAsString());
                System.out.println("  Waktu Modifikasi: " + outputObj.get("gmt_modified").getAsString());
                System.out.println("  Bahasa: " + outputObj.get("language").getAsString());
                System.out.println("  Teks Pratinjau: " + outputObj.get("preview_text").getAsString());
                System.out.println("  Model: " + outputObj.get("target_model").getAsString());
                System.out.println("  Deskripsi Suara: " + outputObj.get("voice_prompt").getAsString());

            } else {
                // Baca respons kesalahan
                StringBuilder errorResponse = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getErrorStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        errorResponse.append(responseLine.trim());
                    }
                }

                System.out.println("Permintaan gagal dengan kode status: " + responseCode);
                System.out.println("Respons kesalahan: " + errorResponse.toString());
            }

        } catch (Exception e) {
            System.err.println("Terjadi kesalahan selama permintaan: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }
}

Hapus suara

Menghapus suara dan melepaskan kuota yang sesuai.

URL

Tiongkok Daratan:

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

Internasional:

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

Header Permintaan

Parameter	Tipe	Wajib	Deskripsi
Authorization	string	Didukung	Token autentikasi dalam format `Bearer <your_api_key>`. Ganti "`<your_api_key>`" dengan Kunci API aktual Anda.
Content-Type	string	Didukung	Tipe media data yang ditransmisikan dalam body permintaan. Tetap `application/json`.

Body permintaan
Body permintaan berisi semua parameter permintaan seperti di bawah ini. Hilangkan bidang opsional sesuai kebutuhan bisnis Anda:
Penting
model: Model desain suara, tetap qwen-voice-design. Jangan ubah nilai ini.
```
{
    "model": "qwen-voice-design",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}
```
Parameter permintaan
Parameter
Jenis
Bawaan
Wajib
Deskripsi
model
string
-
Didukung
Model desain suara, tetap qwen-voice-design.
action
string
-
Didukung
Tipe operasi, tetap delete.
voice
string
-
Ya
Suara yang akan dihapus.
Parameter respons
Klik untuk melihat contoh respons
```
{
    "output": {
        "voice": "yourVoice"
    },
    "usage": {},
    "request_id": "yourRequestId"
}
```
Parameter berikut adalah:
Parameter
Tipe
Deskripsi
request_id
string
ID permintaan.
voice
string
Suara yang dihapus.

Contoh kode

Penting

model: Model desain suara, tetap qwen-voice-design. Jangan ubah nilai ini.

cURL

Jika Anda belum mengonfigurasi Kunci API sebagai variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan Kunci API aktual Anda.

# ======= Catatan Penting =======
# Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
# === Hapus komentar ini sebelum eksekusi ===

curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

Python

import requests
import os

def delete_voice(voice_name):
    """
    Hapus suara yang ditentukan.
    :param voice_name: Nama suara.
    :return: True jika penghapusan berhasil atau suara tidak ada tetapi permintaan berhasil, False jika operasi gagal.
    """
    # Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    # Siapkan data permintaan
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "qwen-voice-design",
        "input": {
            "action": "delete",
            "voice": voice_name
        }
    }
    
    # Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    # Kirim permintaan
    response = requests.post(
        url,
        headers=headers,
        json=data
    )
    
    if response.status_code == 200:
        result = response.json()
        
        # Periksa apakah ada pesan kesalahan
        if "code" in result and "VoiceNotFound" in result["code"]:
            print(f"Suara tidak ada: {voice_name}")
            print(f"Pesan kesalahan: {result.get('message', 'Suara tidak ditemukan')}")
            return True  # Jika suara tidak ada, operasi dianggap berhasil (karena target sudah hilang)
        
        # Periksa apakah penghapusan berhasil
        if "usage" in result:
            print(f"Suara berhasil dihapus: {voice_name}")
            print(f"ID Permintaan: {result.get('request_id', 'N/A')}")
            return True
        else:
            print(f"Format respons dari operasi penghapusan tidak terduga: {result}")
            return False
    else:
        print(f"Permintaan penghapusan suara gagal dengan kode status: {response.status_code}")
        print(f"Konten respons: {response.text}")
        return False

def main():
    # Contoh: Hapus suara
    voice_name = "myvoice"  # Ganti dengan nama suara aktual yang ingin Anda hapus
    
    print(f"Menghapus suara: {voice_name}")
    success = delete_voice(voice_name)
    
    if success:
        print(f"\nPenghapusan suara '{voice_name}' selesai!")
    else:
        print(f"\nPenghapusan suara '{voice_name}' gagal!")

if __name__ == "__main__":
    main()

Java

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

public class Main {

    public static void main(String[] args) {
        Main example = new Main();
        // Contoh: Hapus suara
        String voiceName = "myvoice"; // Ganti dengan nama suara aktual yang ingin Anda hapus
        System.out.println("Menghapus suara: " + voiceName);
        example.deleteVoice(voiceName);
    }

    public void deleteVoice(String voiceName) {
        // Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/model-studio/get-api-key
        // Jika variabel lingkungan belum diatur, ganti baris berikut dengan Kunci API Model Studio Anda: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Buat string body permintaan JSON
        String jsonBody = "{\n" +
                "    \"model\": \"qwen-voice-design\",\n" +
                "    \"input\": {\n" +
                "        \"action\": \"delete\",\n" +
                "        \"voice\": \"" + voiceName + "\"\n" +
                "    }\n" +
                "}";

        HttpURLConnection connection = null;
        try {
            // Berikut ini adalah URL untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
            URL url = new URL("https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization");
            connection = (HttpURLConnection) url.openConnection();

            // Atur metode dan header permintaan
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Bearer " + apiKey);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);
            connection.setDoInput(true);

            // Kirim body permintaan
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = jsonBody.getBytes("UTF-8");
                os.write(input, 0, input.length);
                os.flush();
            }

            // Dapatkan respons
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // Baca konten respons
                StringBuilder response = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }
                }

                // Uraikan respons JSON
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();

                // Periksa apakah ada pesan kesalahan
                if (jsonResponse.has("code") && jsonResponse.get("code").getAsString().contains("VoiceNotFound")) {
                    String errorMessage = jsonResponse.has("message") ?
                            jsonResponse.get("message").getAsString() : "Suara tidak ditemukan";
                    System.out.println("Suara tidak ada: " + voiceName);
                    System.out.println("Pesan kesalahan: " + errorMessage);
                    // Jika suara tidak ada, operasi dianggap berhasil (karena target sudah hilang)
                } else if (jsonResponse.has("usage")) {
                    // Periksa apakah penghapusan berhasil
                    System.out.println("Suara berhasil dihapus: " + voiceName);
                    String requestId = jsonResponse.has("request_id") ?
                            jsonResponse.get("request_id").getAsString() : "N/A";
                    System.out.println("ID Permintaan: " + requestId);
                } else {
                    System.out.println("Format respons dari operasi penghapusan tidak terduga: " + response.toString());
                }

            } else {
                // Baca respons kesalahan
                StringBuilder errorResponse = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getErrorStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        errorResponse.append(responseLine.trim());
                    }
                }

                System.out.println("Permintaan penghapusan suara gagal dengan kode status: " + responseCode);
                System.out.println("Respons kesalahan: " + errorResponse.toString());
            }

        } catch (Exception e) {
            System.err.println("Terjadi kesalahan selama permintaan: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }
}

Sintesis suara

Untuk mensintesis ucapan personalisasi menggunakan suara yang dibuat oleh desain suara, lihat Memulai: Dari desain suara hingga sintesis suara.

Model sintesis suara desain suara (seperti qwen3-tts-vd-realtime-2026-01-15) adalah model khusus. Model ini hanya mendukung suara yang dibuat oleh desain suara dan tidak mendukung suara sistem seperti Chelsie, Serena, Ethan, dan Cherry.

Kuota suara dan aturan pembersihan otomatis

Batas total: 1.000 suara per akun
Anda dapat mengkueri jumlah suara (total_count) dengan memanggil Kueri daftar suara
Pembersihan otomatis: Jika suara tidak digunakan untuk permintaan sintesis suara apa pun dalam satu tahun terakhir, sistem akan menghapusnya secara otomatis.

Informasi penagihan

Desain suara dan sintesis suara ditagih secara terpisah.

Desain suara: Buat suara ditagih sebesar $0,2 per suara. Pembuatan yang gagal tidak ditagih.
Catatan
Informasi kuota gratis (hanya tersedia di wilayah Singapura):
- Anda mendapatkan 10 kesempatan pembuatan suara gratis dalam 90 hari setelah mengaktifkan Alibaba Cloud Model Studio.
- Pembuatan yang gagal tidak mengurangi kuota gratis Anda.
- Menghapus suara tidak mengembalikan penggunaan kuota gratis.
- Setelah kuota gratis Anda habis atau periode validitas 90 hari berakhir, pembuatan suara ditagih sebesar $0,2 per suara.
Menggunakan suara kustom yang dibuat oleh desain suara untuk sintesis suara: Ditagih per jumlah karakter. Untuk detailnya, lihat Sintesis suara real-time - Qwen atau Sintesis suara - Qwen.

Pesan kesalahan

Jika Anda mengalami kesalahan, lihat Pesan kesalahan untuk troubleshooting.