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

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

Panduan pengguna: Kloning suara.

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.

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.

Beralih ke wilayah Singapore:

import dashscope

# Atur di awal kode Anda
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Catatan:

Kunci API berbeda antar wilayah. Gunakan Kunci API yang sesuai dengan wilayah target.

Pengaturan wilayah bersifat global dan memengaruhi semua panggilan API SDK DashScope.

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

Ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya. Domain lama tetap berfungsi sepenuhnya.

Kelas VoiceEnrollmentService

Jalur paket: dashscope.audio.tts_v2.VoiceEnrollmentService

Tujuan: Mengelola siklus hidup suara hasil kloning Qwen-Audio-TTS/CosyVoice, termasuk membuat, menanyakan, memperbarui, dan menghapus suara.

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 text-to-speech (TTS) yang mendorong suara hasil kloning. Nilai ini harus sesuai dengan model yang Anda tentukan saat memanggil API TTS; jika tidak, sintesis 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	URL file audio untuk kloning suara. URL harus dapat diakses publik.
language_hints	List[str]	Tidak	Hanya berlaku untuk kloning suara Qwen-Audio-TTS/CosyVoice (ketika model adalah `voice-enrollment`). Hanya didukung oleh qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, v3-plus, dan v3-flash. 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, tetapi versi saat ini hanya memproses elemen pertama. Nilai yang valid bervariasi tergantung model: qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-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	Hanya berlaku untuk kloning suara Qwen-Audio-TTS/CosyVoice (ketika model adalah `voice-enrollment`). Hanya didukung oleh qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, dan v3-flash. Durasi maksimum (dalam detik) audio referensi setelah pra-pemrosesan. Nilai valid: [3.0, 30.0]. Default: 10.0.
enable_preprocess	bool	Tidak	Hanya berlaku untuk kloning suara Qwen-Audio-TTS/CosyVoice (ketika model adalah `voice-enrollment`). Hanya didukung oleh qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, dan v3-flash. 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.
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, language_hints: List[str] = None,
                 max_prompt_audio_length: float = None, enable_preprocess: bool = None) -> None

Parameter:

Parameter	Tipe	Wajib	Deskripsi
voice_id	str	Ya	ID suara yang akan diperbarui.
url	str	Ya	URL file audio baru.
language_hints	List[str]	Tidak	Petunjuk bahasa untuk audio sampel.
max_prompt_audio_length	float	Tidak	Durasi maksimum audio referensi.
enable_preprocess	bool	Tidak	Apakah akan mengaktifkan pra-pemrosesan audio.

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}")

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()}")