Skip to main content
Qwen-TTS

Referensi API sintesis suara non-real-time Qwen-TTS

Parameter permintaan dan bidang respons untuk API sintesis suara non-realtime (Qwen-TTS).

Request body

  • Non-streaming output
  • Streaming output
  • Python
  • Java
  • curl
Antarmuka SpeechSynthesizer dalam SDK Python DashScope kini telah disatukan ke dalam MultiModalConversation. Penggunaan dan parameternya tetap sepenuhnya konsisten.
# Instal versi terbaru SDK DashScope
import os
import dashscope
# Wilayah Singapura
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'
text = "Let me recommend a T-shirt to everyone. This one is really super nice. The color is very elegant, and it's also a perfect item to match. Everyone can buy it without hesitation. It's truly beautiful and very forgiving on the figure. No matter what body type you have, it will look great. I recommend everyone to place an order."
# Penggunaan antarmuka SpeechSynthesizer: dashscope.audio.qwen_tts.SpeechSynthesizer.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 Anda: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # Jika variabel lingkungan belum dikonfigurasi, ganti baris berikut dengan Kunci API Model Studio Anda: api_key="sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    text=text,
    voice="Cherry"
    # Untuk menggunakan fitur kontrol instruksi, hapus komentar baris berikut dan ganti model dengan qwen3-tts-instruct-flash
    # instructions='Fast speech rate, with a clear rising intonation, suitable for introducing fashion products.',
    # optimize_instructions=True
)
print(response)
modelstring(required)Nama model. Untuk detailnya, lihat Model yang didukung.
inputobject(required)Parameter input.

Properties

text string (required)Teks yang akan disintesis. Mendukung input campuran multibahasa. Panjang input maksimum: 512 token (model Qwen-TTS) atau 600 karakter (model lainnya).voice string (required)Suara yang digunakan. Lihat Suara sistem yang didukung.language_type string (opsional)Bahasa audio yang disintesis. Nilai default: Auto.
  • Auto: Gunakan ketika input berisi beberapa bahasa atau bahasa tidak dapat ditentukan. Model secara otomatis mencocokkan pelafalan untuk setiap segmen bahasa, meskipun akurasinya tidak dijamin.
  • Bahasa tertentu: Gunakan untuk teks satu bahasa. Menentukan bahasa secara signifikan meningkatkan kualitas sintesis dan biasanya menghasilkan hasil yang lebih baik daripada Auto. Nilai yang valid:
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian
instructionsstring(opsional)Instruksi untuk sintesis suara. Lihat Kontrol instruksi.Default: None.Panjang maksimum: 1.600 token.Bahasa yang didukung: hanya Chinese dan English.Cakupan: Fitur ini hanya berlaku untuk model seri Qwen3-TTS-Instruct-Flash.optimize_instructionsboolean(opsional)Jika diaktifkan, secara semantik mengoptimalkan instructions untuk meningkatkan kealamian dan ekspresivitas suara yang disintesis.Default: false.Perilaku: Ketika diatur ke true, sistem secara semantik menulis ulang instructions untuk menghasilkan arahan yang lebih sesuai untuk sintesis suara.Gunakan parameter ini ketika diperlukan kontrol presisi atas penyampaian suara.Bergantung pada parameter instructions. Tidak berpengaruh jika instructions kosong.Cakupan: Fitur ini hanya berlaku untuk model seri Qwen3-TTS-Instruct-Flash.

Response object (format streaming dan non-streaming identik)

{
    "status_code": 200,
    "request_id": "5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
    "code": "",
    "message": "",
    "output": {
        "text": null,
        "finish_reason": "stop",
        "choices": null,
        "audio": {
            "data": "",
            "url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/1d/ab/20251218/d2033070/39b6d8f2-c0db-4daa-9073-5d27bfb66b78.wav?Expires=1766113409&OSSAccessKeyId=YOUR_ACCESS_KEY_ID&Signature=YOUR_SIGNATURE",
            "id": "audio_5c63c65c-cad8-4bf4-959d-xxxxxxxxxxxx",
            "expires_at": 1766113409
        }
    },
    "usage": {
        "input_tokens": 0,
        "output_tokens": 0,
        "characters": 195
    }
}
status_code integerKode status HTTP sebagaimana didefinisikan dalam RFC 9110. Nilai umum:
• 200: Permintaan berhasil.
• 400: Parameter permintaan tidak valid.
• 401: Tidak sah.
• 404: Sumber daya tidak ditemukan.
• 500: Kesalahan server internal.
request_id stringIdentifikasi unik untuk permintaan ini. Gunakan untuk troubleshooting.
code stringKode kesalahan yang dikembalikan saat gagal. Lihat Kode kesalahan.
message stringPesan kesalahan yang dikembalikan saat gagal. Lihat Kode kesalahan.
outputobjectOutput model.

Properties

textstringSelalu null. Abaikan bidang ini.choicesstringSelalu null. Abaikan bidang ini.finish_reasonstringStatus generasi:
  • null — Generasi sedang berlangsung.
  • stop — Generasi selesai secara normal, atau kondisi berhenti terpenuhi.
audio objectOutput audio dari model.

Properties

url stringURL file audio lengkap, berlaku selama 24 jam. Dalam mode non-streaming, dikembalikan langsung dalam respons. Dalam mode streaming, hanya dikembalikan pada chunk terakhir aliran SSE (chunk perantara tidak berisi bidang ini).data stringData audio yang dienkode Base64. Dalam mode non-streaming, bidang ini selalu berupa string kosong (gunakan url untuk mendapatkan file audio lengkap). Dalam mode streaming, chunk perantara berisi segmen audio yang dienkode Base64, sedangkan chunk terakhir mengembalikan string kosong (gunakan url untuk mendapatkan audio lengkap).id stringIdentifikasi unik untuk audio.expires_at integerWaktu kedaluwarsa URL sebagai timestamp Unix.
usage objectPenggunaan token atau karakter untuk permintaan ini. Qwen-TTS mengembalikan penggunaan token; Qwen3-TTS-Flash mengembalikan penggunaan karakter.

Properties

input_tokens_details objectRincian penggunaan token untuk teks input. Hanya dikembalikan oleh model Qwen-TTS.

Properties

text_tokens integerJumlah token yang dikonsumsi oleh teks input.
total_tokens integerJumlah total token yang dikonsumsi oleh permintaan ini. Hanya dikembalikan oleh model Qwen-TTS.output_tokens integerJumlah token yang dikonsumsi oleh audio output. Untuk model Qwen3-TTS-Flash, bidang ini selalu 0.input_tokens integerJumlah token yang dikonsumsi oleh teks input. Untuk model Qwen3-TTS-Flash, bidang ini selalu 0.output_tokens_details objectRincian penggunaan token untuk output. Hanya dikembalikan oleh model Qwen-TTS.

Properties

audio_tokens integerJumlah token yang dikonsumsi oleh audio output.text_tokens integerJumlah token yang dikonsumsi oleh teks output. Saat ini selalu 0.
characters integerJumlah karakter dalam teks input. Hanya dikembalikan oleh model Qwen3-TTS-Flash.
request_id stringIdentifikasi unik untuk permintaan ini. Gunakan untuk troubleshooting.

Unduhan dan pemutaran audio

Sebelum menjalankan contoh, dapatkan dan konfigurasikan API key serta instal DashScope SDK. Contoh pemutaran Python juga memerlukan PyAudio dan NumPy. Lihat komentar kode untuk instalasi PyAudio, dan instal NumPy dengan pip install numpy.

Unduh audio (Java)

Anda harus mengimpor dependensi Gson. Tambahkan menggunakan Maven atau Gradle:
  • Maven
  • Gradle
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>
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);
    }
}

Pemutaran streaming

  • Python
  • Java
# 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()
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
Realtime API
Penyematan Teks
TokenPlan
Model production