Sintesis suara non-real-time mengonversi teks menjadi suara melalui API HTTP. Fitur ini dirancang untuk skenario yang toleran terhadap latensi, seperti produksi buku audio, narasi pembelajaran daring, dan pembuatan konten, serta mendukung berbagai suara, beberapa bahasa, kloning suara, dan desain suara.
Ikhtisar
Fitur ini mengonversi teks lengkap menjadi file audio melalui API HTTP dengan dua mode output: non-streaming dan streaming.
- Non-streaming mengembalikan URL file audio yang berlaku selama 24 jam; streaming mengembalikan data audio dalam bentuk chunk.
- Mendukung beberapa bahasa, termasuk dialek Bahasa Tionghoa.
- Mendukung kloning suara dan Desain Suara untuk membuat suara kustom.
- Mendukung kontrol instruksi untuk mengatur ekspresivitas suara melalui instruksi dalam bahasa alami.
Untuk skenario streaming berlatensi rendah, lihat Sintesis suara real-time. Untuk rekomendasi pemilihan model, lihat Sintesis suara.
Audio yang disintesis pada halaman desain suara di Konsol Model Studio hanya dapat dipratinjau secara daring dan tidak dapat diunduh sebagai file audio. Untuk mengunduh audio, panggil API atau SDK. Dalam mode non-streaming, respons mengembalikan URL file audio yang berlaku selama 24 jam.
Prasyarat
Sebelum memulai, lakukan persiapan berikut:
- Konfigurasikan Kunci API dan tetapkan sebagai variabel lingkungan
- (Opsional) Jika Anda memanggil API melalui SDK DashScope, instal SDK versi terbaru
Memulai dengan cepat
Tab berikut menunjukkan contoh sintesis suara untuk setiap seri model. Untuk contoh dalam bahasa lain dan penjelasan parameter lebih rinci, lihat Referensi API.
Qwen-TTS
Semua contoh pada bagian ini menggunakan suara sistem.
Output non-streaming
Dalam mode non-streaming, respons berisi bidang url yang mengarah ke file audio hasil sintesis. URL tersebut berlaku selama 24 jam.
Python
import os
import dashscope
# Berikut adalah konfigurasi untuk wilayah Singapura.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
text = "Today is a wonderful day to build something people love!"
# Penggunaan antarmuka: dashscope.MultiModalConversation.call(...)
response = dashscope.MultiModalConversation.call(
# Untuk menggunakan fitur kontrol instruksi, ganti model dengan qwen3-tts-instruct-flash
model="qwen3-tts-flash",
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
text=text,
voice="Cherry",
language_type="English", # Kami menyarankan agar nilai ini sesuai dengan bahasa teks agar pengucapan dan intonasi terdengar alami.
# Untuk menggunakan fitur kontrol instruksi, hapus komentar baris di bawah ini dan ganti model dengan qwen3-tts-instruct-flash
# instructions='Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.',
# optimize_instructions=True,
stream=False
)
print(response)
Java
Anda harus mengimpor dependensi Gson. Tambahkan menggunakan Maven atau Gradle:
Maven
Tambahkan 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 berikut ke build.gradle:
// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileOutputStream;
import java.io.InputStream;
import java.net.URL;
public class Main {
// Untuk menggunakan fitur kontrol instruksi, ganti MODEL dengan qwen3-tts-instruct-flash
private static final String MODEL = "qwen3-tts-flash";
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/zh/model-studio/get-api-key
// Jika Anda belum mengonfigurasi variabel lingkungan, 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!")
.voice(AudioParameters.Voice.CHERRY)
.languageType("English") // Kami menyarankan agar nilai ini sesuai dengan bahasa teks agar pengucapan dan intonasi terdengar alami.
// Untuk menggunakan fitur kontrol instruksi, hapus komentar baris di bawah ini dan ganti model dengan qwen3-tts-instruct-flash
// .parameter("instructions","Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.")
// .parameter("optimize_instructions",true)
.build();
MultiModalConversationResult result = conv.call(param);
String audioUrl = result.getOutput().getAudio().getUrl();
System.out.print(audioUrl);
// Unduh file audio ke penyimpanan 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: downloaded_audio.wav");
} catch (Exception e) {
System.out.println("\nGagal mengunduh file audio: " + e.getMessage());
}
}
public static void main(String[] args) {
// Berikut adalah konfigurasi untuk wilayah Singapura.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
try {
call();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
cURL
# ======= Penting =======
# Konfigurasi berikut untuk wilayah Singapura.
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===
curl -X POST 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen3-tts-flash",
"input": {
"text": "Today is a wonderful day to build something people love!",
"voice": "Cherry",
"language_type": "English"
}
}'
Output streaming
Dalam mode streaming, data audio dikembalikan dalam bentuk chunk yang dikodekan Base64 PCM. Paket terakhir berisi URL ke file audio lengkap.
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 os
import dashscope
import pyaudio
import time
import base64
import numpy as np
# Berikut adalah konfigurasi untuk wilayah Singapura.
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
p = pyaudio.PyAudio()
# Buat aliran audio
stream = p.open(format=pyaudio.paInt16,
channels=1,
rate=24000,
output=True)
text = "Today is a wonderful day to build something people love!"
response = dashscope.MultiModalConversation.call(
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan Kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan Kunci API Model Studio Anda: api_key = "sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# Untuk menggunakan fitur kontrol instruksi, ganti model dengan qwen3-tts-instruct-flash
model="qwen3-tts-flash",
text=text,
voice="Cherry",
language_type="English", # Kami menyarankan agar nilai ini sesuai dengan bahasa teks agar pengucapan dan intonasi terdengar alami.
# Untuk menggunakan fitur kontrol instruksi, hapus komentar baris di bawah ini dan ganti model dengan qwen3-tts-instruct-flash
# instructions='Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.',
# optimize_instructions=True,
stream=True
)
for chunk in response:
if chunk.output is not None:
audio = chunk.output.audio
if audio.data is not None:
wav_bytes = base64.b64decode(audio.data)
audio_np = np.frombuffer(wav_bytes, dtype=np.int16)
# Putar data audio secara langsung
stream.write(audio_np.tobytes())
if chunk.output.finish_reason == "stop":
print(f"selesai pada: {chunk.output.audio.expires_at}")
time.sleep(0.8)
# Bersihkan sumber daya
stream.stop_stream()
stream.close()
p.terminate()
Java
Anda harus mengimpor dependensi Gson. Tambahkan menggunakan Maven atau Gradle:
Maven
Tambahkan 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 berikut ke build.gradle:
// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")
// Harap instal versi terbaru SDK DashScope
import com.alibaba.dashscope.aigc.multimodalconversation.AudioParameters;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversation;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationParam;
import com.alibaba.dashscope.aigc.multimodalconversation.MultiModalConversationResult;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.exception.UploadFileException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.Flowable;
import javax.sound.sampled.*;
import java.util.Base64;
public class Main {
// Untuk menggunakan fitur kontrol instruksi, ganti MODEL dengan qwen3-tts-instruct-flash
private static final String MODEL = "qwen3-tts-flash";
public static void streamCall() 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/zh/model-studio/get-api-key
// Jika Anda belum mengonfigurasi variabel lingkungan, 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!")
.voice(AudioParameters.Voice.CHERRY)
.languageType("English") // Kami menyarankan agar nilai ini sesuai dengan bahasa teks agar pengucapan dan intonasi terdengar alami.
// Untuk menggunakan fitur kontrol instruksi, hapus komentar baris di bawah ini dan ganti model dengan qwen3-tts-instruct-flash
// .parameter("instructions","Fast-paced speech with noticeable upward intonation, ideal for presenting fashion products.")
// .parameter("optimize_instructions",true)
.build();
Flowable<MultiModalConversationResult> result = conv.streamCall(param);
result.blockingForEach(r -> {
try {
// 1. Dapatkan data audio yang dikodekan Base64
String base64Data = r.getOutput().getAudio().getData();
byte[] audioBytes = Base64.getDecoder().decode(base64Data);
// 2. Konfigurasikan format audio (sesuaikan dengan format audio yang dikembalikan oleh API)
AudioFormat format = new AudioFormat(
AudioFormat.Encoding.PCM_SIGNED,
24000, // Laju sampel (harus sesuai dengan format yang dikembalikan oleh API)
16, // Kedalaman bit
1, // Jumlah saluran
2, // Ukuran frame (dalam byte)
24000, // Laju frame (harus sesuai dengan laju sampel)
false // Big-endian
);
// 3. Putar data audio secara real-time
DataLine.Info info = new DataLine.Info(SourceDataLine.class, format);
try (SourceDataLine line = (SourceDataLine) AudioSystem.getLine(info)) {
if (line != null) {
line.open(format);
line.start();
line.write(audioBytes, 0, audioBytes.length);
line.drain();
}
}
} catch (LineUnavailableException e) {
e.printStackTrace();
}
});
}
public static void main(String[] args) {
// Berikut adalah konfigurasi untuk wilayah Singapura.
Constants.baseHttpApiUrl = "https://dashscope-intl.aliyuncs.com/api/v1";
try {
streamCall();
} catch (ApiException | NoApiKeyException | UploadFileException e) {
System.out.println(e.getMessage());
}
System.exit(0);
}
}
cURL
# ======= Penting =======
# Konfigurasi berikut untuk wilayah Singapura.
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===
curl -X POST 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/multimodal-generation/generation' \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'X-DashScope-SSE: enable' \
-d '{
"model": "qwen3-tts-flash",
"input": {
"text": "Today is a wonderful day to build something people love!",
"voice": "Cherry",
"language_type": "English"
}
}'
Fitur lanjutan
Kontrol instruksi
Spesifikasi instruksi berdasarkan model:
Qwen-TTS
Model yang didukung: Hanya model seri Qwen3-TTS-Instruct-Flash yang didukung.
Penggunaan: Kirim konten instruksi melalui parameter instructions.
Bahasa yang didukung untuk teks instruksi: Hanya Bahasa Tionghoa dan Inggris yang didukung.
Batas panjang teks instruksi: Hingga 1.600 token.
Dialek
Bagian ini menjelaskan cara menghasilkan suara dalam dialek Bahasa Tionghoa (seperti dialek Henan dan Sichuan). Metode konfigurasi berbeda berdasarkan model dan jenis suara.
Qwen-TTS
- Suara sistem: Gunakan suara sistem yang mendukung dialek. Lihat Daftar Suara Qwen-TTS.
- Suara hasil kloning: Dialek tidak didukung.
- Suara hasil desain: Dialek tidak didukung.
Dialek yang didukung: Lihat bagian "Bahasa yang didukung" untuk setiap model di Qwen3-TTS.
Model dan wilayah yang didukung
Singapura
Untuk memanggil model berikut, gunakan Kunci API untuk wilayah Singapura:
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash: qwen3-tts-instruct-flash (versi stabil, saat ini setara dengan qwen3-tts-instruct-flash-2026-01-26), qwen3-tts-instruct-flash-2026-01-26 (snapshot terbaru)
- Qwen3-TTS-VD: qwen3-tts-vd-2026-01-26 (snapshot terbaru)
- Qwen3-TTS-VC: qwen3-tts-vc-2026-01-22 (snapshot terbaru)
- Qwen3-TTS-Flash: qwen3-tts-flash (versi stabil, saat ini setara dengan qwen3-tts-flash-2025-11-27), qwen3-tts-flash-2025-11-27, qwen3-tts-flash-2025-09-18
Tiongkok (Beijing)
Untuk memanggil model berikut, gunakan Kunci API untuk wilayah Beijing:
-
Qwen-TTS:
- Qwen3-TTS-Instruct-Flash: qwen3-tts-instruct-flash (versi stabil, saat ini setara dengan qwen3-tts-instruct-flash-2026-01-26), qwen3-tts-instruct-flash-2026-01-26 (snapshot terbaru)
- Qwen3-TTS-VD: qwen3-tts-vd-2026-01-26 (snapshot terbaru)
- Qwen3-TTS-VC: qwen3-tts-vc-2026-01-22 (snapshot terbaru)
- Qwen3-TTS-Flash: qwen3-tts-flash (versi stabil, saat ini setara dengan qwen3-tts-flash-2025-11-27), qwen3-tts-flash-2025-11-27, qwen3-tts-flash-2025-09-18
- Qwen-TTS: qwen-tts (versi stabil, saat ini setara dengan qwen-tts-2025-04-10), qwen-tts-latest (versi terbaru, saat ini setara dengan qwen-tts-2025-05-22), qwen-tts-2025-05-22 (snapshot), qwen-tts-2025-04-10 (snapshot)
Suara sistem yang didukung
Model yang berbeda mendukung suara yang berbeda. Atur parameter permintaan voice ke nilai dari kolom parameter suara pada tabel berikut.
Referensi API
FAQ
T: Berapa lama masa berlaku URL file audio?
J: URL file audio berlaku selama 24 jam setelah dihasilkan. Setelah URL kedaluwarsa, panggil API lagi untuk mendapatkan URL baru.