SDK Python kloning suara Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice - Alibaba Cloud Model Studio

Kloning suara Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice dapat diakses melalui DashScope Python SDK.

Titik akhir layanan

SDK menggunakan titik akhir wilayah China (Beijing) secara default. Untuk beralih ke wilayah lain, atur dashscope.base_http_api_url sebelum menginisialisasi client.

Catatan

API key berbeda antarwilayah. Gunakan API key untuk wilayah target.
Pengaturan wilayah bersifat global dan memengaruhi semua panggilan API SDK DashScope.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

PentingAlibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapore. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:

China (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Kelas VoiceEnrollmentService

Jalur paket: dashscope.audio.tts_v2.VoiceEnrollmentService

Tujuan: Mengelola siklus hidup suara hasil kloning Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice (membuat, mengkueri, memperbarui, dan menghapus).

Konstruktor

VoiceEnrollmentService()

create_voice() — Membuat suara

Signature metode:

def create_voice(self, target_model: str, prefix: str, url: str,
                 language_hints: List[str] = None,
                 max_prompt_audio_length: float = None,
                 **kwargs) -> str

Parameter:

Parameter	Tipe	Wajib	Deskripsi
target_model	str	Ya	Model target yang menggunakan suara. Harus sama dengan model yang menggunakan suara tersebut pada permintaan berikutnya; jika berbeda, permintaan akan gagal.
prefix	str	Ya	Awalan untuk nama suara. Hanya karakter alfanumerik yang diperbolehkan, dengan panjang maksimum 10 karakter. Nama suara yang dihasilkan mengikuti format berikut: `{target_model}-{prefix}-{unique_id}`.
url	str	Ya	Audio referensi untuk kloning suara. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya `data:audio/wav;base64,...`.
language_hints	List[str]	Tidak	Membantu model mengidentifikasi bahasa audio sampel agar fitur suara dapat diekstraksi lebih akurat dan meningkatkan kualitas kloning. Jika bahasa yang ditentukan tidak sesuai dengan bahasa audio sebenarnya (misalnya, menyetel `en` padahal audionya dalam bahasa Mandarin), sistem akan mengabaikan nilai ini dan mendeteksi bahasa secara otomatis. Parameter ini berupa array yang harus berisi tepat satu elemen. CatatanBerlaku untuk qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash. Klik untuk melihat bahasa yang didukung per model qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash: zh: Tionghoa en: Inggris fr: Prancis de: Jerman ja: Jepang ko: Korea ru: Rusia pt: Portugis th: Thai id: Bahasa Indonesia vi: Vietnam it: Italia es: Spanyol ms: Malaysia fil: Filipino ar: Arab cosyvoice-v3-plus: zh: Tionghoa en: Inggris fr: Prancis de: Jerman ja: Jepang ko: Korea ru: Rusia cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Bahasa Tionghoa en: Inggris fr: Prancis de: Jerman ja: Jepang ko: Korea ru: Rusia pt: Portugis th: Thai id: Indonesia vi: Vietnam Default: ["zh"].
max_prompt_audio_length	float	Tidak	Durasi maksimum (dalam detik) audio referensi setelah pra-pemrosesan. Nilai valid: [3.0, 30.0]. Default: 10.0. CatatanBerlaku untuk qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_preprocess	bool	Tidak	Apakah akan mengaktifkan pra-pemrosesan audio (pengurangan kebisingan, peningkatan audio, dan normalisasi volume). Aktifkan opsi ini untuk rekaman yang memiliki kebisingan latar belakang. Nonaktifkan untuk rekaman di lingkungan tenang agar karakteristik suara asli tetap terjaga. Default: false. CatatanBerlaku untuk qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_volume_normalization	bool	Tidak	Menentukan apakah akan menormalisasi volume audio sampel yang digunakan untuk kloning suara. Teruskan parameter ini langsung sebagai argumen kata kunci. Nilai default: `False`. Jika Anda menyetel parameter ini ke `True`, volume audio yang disintesis dengan suara yang dibuat mungkin berbeda dari volume audio yang disintesis dengan suara yang dibuat tanpa mengaktifkan parameter ini.

Nilai kembalian: str — ID suara (voice_id).

list_voices() — Menampilkan daftar suara

Signature metode:

def list_voices(self, prefix: str = None, page_index: int = 0, page_size: int = 10) -> list

Parameter:

Parameter	Tipe	Wajib	Deskripsi
prefix	str	Tidak	Filter berdasarkan awalan nama suara.
page_index	int	Tidak	Indeks halaman. Default: 0.
page_size	int	Tidak	Jumlah entri per halaman. Default: 10.

Nilai kembalian: list — Daftar suara.

query_voice() — Menanyakan detail suara

Signature metode:

def query_voice(self, voice_id: str) -> dict

Parameter:

Parameter	Tipe	Wajib	Deskripsi
voice_id	str	Ya	ID suara yang akan ditanyakan.

Nilai kembalian: dict — Detail suara.

update_voice() — Memperbarui suara

Signature metode:

def update_voice(self, voice_id: str, url: str) -> None

Parameter:

Parameter	Tipe	Wajib	Deskripsi
voice_id	str	Ya	ID suara yang akan diperbarui.
url	str	Ya	Audio referensi baru. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya `data:audio/wav;base64,...`.

delete_voice() — Menghapus suara

Signature metode:

def delete_voice(self, voice_id: str) -> None

Parameter:

Parameter	Tipe	Wajib	Deskripsi
voice_id	str	Ya	ID suara yang akan dihapus.

Contoh kode

Contoh berikut menunjukkan cara menggunakan kelas VoiceEnrollmentService untuk operasi kloning suara umum.

Membuat suara

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# Berikut ini menggunakan titik akhir wilayah Singapore. Ganti "{WorkspaceId}" dengan workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

TARGET_MODEL = 'qwen-audio-3.0-tts-flash'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'
service = VoiceEnrollmentService()

# Hindari pemanggilan berulang. Setiap pemanggilan membuat suara baru, dan Anda tidak dapat membuat
# lagi setelah mencapai batas kuota.
voice_id = service.create_voice(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # enable_preprocess=False,
    # enable_volume_normalization=True
)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice ID: {voice_id}")

Untuk file WAV lokal, ganti penetapan url di atas dengan kode berikut sebelum memanggil create_voice. Untuk memperbarui suara, masukkan juga Data URI melalui parameter url dari update_voice. Ganti sample.wav dengan jalur file audio lokal Anda.

import base64
from pathlib import Path

url = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

Menampilkan daftar suara

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# Berikut ini menggunakan titik akhir wilayah Singapore. Ganti "{WorkspaceId}" dengan workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()

# Filter berdasarkan awalan, atau atur ke None untuk menampilkan semua suara
voices = service.list_voices(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Suara yang ditemukan: {voices}")

Menanyakan suara tertentu

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# Berikut ini menggunakan titik akhir wilayah Singapore. Ganti "{WorkspaceId}" dengan workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = service.query_voice(voice_id=voice_id)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Detail Suara: {voice_details}")

Memperbarui suara

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# Berikut ini menggunakan titik akhir wilayah Singapore. Ganti "{WorkspaceId}" dengan workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.update_voice(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Pembaruan dikirimkan. Request ID: {service.get_last_request_id()}")

Menghapus suara

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# Berikut ini menggunakan titik akhir wilayah Singapore. Ganti "{WorkspaceId}" dengan workspace ID Anda yang sebenarnya. Konfigurasi berbeda tiap wilayah.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.delete_voice(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Penghapusan dikirimkan. Request ID: {service.get_last_request_id()}")