Skip to main content

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
Pada DashScope Python SDK 2.0, sintesis suara non-realtime dipanggil melalui resource client.audio.tts.http.
# Instal versi terbaru SDK DashScope
import os
import dashscope

# Berikut adalah konfigurasi untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    # Kunci API untuk wilayah Singapura, AS (Virginia), dan Tiongkok (Beijing) tidak dapat saling dipertukarkan. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum dikonfigurasi, ganti dengan: api_key = "sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

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."
result = client.audio.tts.http.synthesize(
    text,
    model="qwen3-tts-flash",
    voice="Cherry"
)
print(result.audio_url, result.audio_id, result.expires_at)
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 adalah 600 karakter.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

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 karakter untuk permintaan ini.

Properties

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.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 {
    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.
                .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

# Berikut adalah konfigurasi untuk wilayah Singapura. Ganti {WorkspaceId} dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
client = dashscope.Client(
    # Kunci API untuk wilayah Singapura, AS (Virginia), dan Tiongkok (Beijing) tidak dapat saling dipertukarkan. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/model-studio/get-api-key
    # Jika variabel lingkungan belum dikonfigurasi, ganti dengan: api_key = "sk-xxx"
    api_key=os.getenv("DASHSCOPE_API_KEY"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

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!"

for chunk in client.audio.tts.http.stream(
    text,
    model="qwen3-tts-flash",
    voice="Cherry",
    language_type="English",  # Kami menyarankan agar nilai ini sesuai dengan bahasa teks agar pengucapan dan intonasi terdengar alami.
):
    if chunk.audio:
        # Putar data audio secara langsung (chunk.audio berisi byte audio yang telah didekode)
        stream.write(chunk.audio)
    if chunk.is_final:
        print(f"finish at: {chunk.expires_at}")
time.sleep(0.8)
# Bersihkan sumber daya
stream.stop_stream()
stream.close()
p.terminate()