Skip to main content

Referensi SDK Python kloning suara Qwen-Audio dan CosyVoice

Kloning dan kelola suara Qwen-Audio dan CosyVoice dengan SDK Python DashScope.

Titik akhir layanan

Alamat titik akhir SDK ditentukan oleh parameter konstruktor Client workspace/region (sesuai alamat di bawah, sudah memuat WorkspaceId). Untuk beralih ke wilayah lain, ubah parameter konstruktor Client ke nilai wilayah yang sesuai.
  • API key berbeda antarwilayah. Gunakan API key untuk wilayah target.
  • Pengaturan wilayah adalah pengaturan tingkat Client dan memengaruhi semua panggilan API SDK DashScope pada Client tersebut.
  • Singapore
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.
Alibaba 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

Sumber daya utama (client.audio.voices)

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

Konstruksi Client (autentikasi dan wilayah)

import os
import dashscope

client = dashscope.Client(
    # 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"),
    # Berikut adalah konfigurasi untuk wilayah Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja aktual Anda. Nilai region berbeda-beda untuk setiap wilayah.
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

create() - Membuat suara

Signature metode:
def create(self, *, target_model: str, prefix: str, url: str,
           language_hints: List[str] = None,
           max_prompt_audio_length: float = None,
           extra_input: Dict = None,
           parameters: Dict = None, ...) -> Voice
Parameter:
ParameterTipeWajibDeskripsi
target_modelstrYaModel target yang menggunakan suara. Harus sama dengan model yang menggunakan suara tersebut pada permintaan berikutnya; jika berbeda, permintaan akan gagal.
prefixstrYaAwalan 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}.
urlstrYaAudio referensi untuk kloning suara. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya data:audio/wav;base64,....
language_hintsList[str]TidakMembantu 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.
Berlaku 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.
  • 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_lengthfloatTidakDurasi maksimum (dalam detik) audio referensi setelah pra-pemrosesan. Nilai valid: [3.0, 30.0].Default: 10.0.
Berlaku 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_preprocessboolTidakApakah 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.
Berlaku 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_normalizationboolTidakMenentukan apakah akan menormalisasi volume audio sampel yang digunakan untuk kloning suara. Diteruskan melalui dictionary extra_input. 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: Objek Voice; voice_id adalah ID suara, request_id adalah ID permintaan.

list() - Menampilkan daftar suara

Signature metode:
def list(self, *, prefix: str = None, page_index: int = 0, page_size: int = 10, ...) -> VoiceList
Parameter:
ParameterTipeWajibDeskripsi
prefixstrTidakFilter berdasarkan awalan nama suara.
page_indexintTidakIndeks halaman. Default: 0.
page_sizeintTidakJumlah entri per halaman. Default: 10.
Nilai kembalian: Objek VoiceList; voices adalah daftar suara, request_id adalah ID permintaan. Setiap item daftar berupa dictionary. Gunakan voice.get("target_model") untuk mendapatkan ID model tujuan.

get() - Menanyakan detail suara

Signature metode:
def get(self, voice_id: str, ...) -> Voice
Parameter:
ParameterTipeWajibDeskripsi
voice_idstrYaID suara yang akan ditanyakan.
Nilai kembalian: Objek Voice, detail suara. Gunakan voice.target_model untuk mendapatkan ID model tujuan.

update() - Memperbarui suara

Signature metode:
def update(self, voice_id: str, *, url: str, ...) -> JobStatus
Parameter:
ParameterTipeWajibDeskripsi
voice_idstrYaID suara yang akan diperbarui.
urlstrYaAudio referensi baru. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya data:audio/wav;base64,....

delete() - Menghapus suara

Signature metode:
def delete(self, voice_id: str, ...) -> JobStatus
Parameter:
ParameterTipeWajibDeskripsi
voice_idstrYaID suara yang akan dihapus.

Contoh kode

Membuat suara

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(
    # 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"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

TARGET_MODEL = 'qwen-audio-3.1-tts-plus'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'

# Hindari pemanggilan berulang. Setiap pemanggilan membuat suara baru; setelah mencapai batas kuota, tidak dapat dibuat lagi.
voice = client.audio.voices.create(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # extra_input={'enable_preprocess': False, 'enable_volume_normalization': True}
)

print(f"Request ID: {voice.request_id}")
print(f"Voice ID: {voice.voice_id}")
Untuk file WAV lokal, ganti penetapan url di atas dengan kode berikut sebelum memanggil client.audio.voices.create(). Untuk memperbarui suara, masukkan juga Data URI melalui parameter url dari client.audio.voices.update(). 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 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(
    # 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"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

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

print(f"Request ID: {voices.request_id}")
print(f"Suara yang ditemukan: {voices.voices}")
for voice in voices.voices:
    print(f"Model tujuan: {voice.get('target_model')}")

Menanyakan suara tertentu

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(
    # 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"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'

voice_details = client.audio.voices.get(voice_id=voice_id)

print(f"Request ID: {voice_details.request_id}")
print(f"Detail Suara: {voice_details}")
print(f"Model tujuan: {voice_details.target_model}")

Memperbarui suara

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(
    # 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"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

result = client.audio.voices.update(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Pembaruan dikirimkan. Request ID: {result.request_id}")

Menghapus suara

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(
    # 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"),
    workspace="{WorkspaceId}",
    region="ap-southeast-1",
)

result = client.audio.voices.delete(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Penghapusan dikirimkan. Request ID: {result.request_id}")