Skip to main content
Referensi API Voice Cloning

Referensi SDK Python kloning suara

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
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Ganti {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.
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
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()}")
Penggunaan API
Generasi teks
Pembuatan Gambar
  • FAQ
Video Generation
Model Dunia
Audio
Real-time multimodal
Realtime API
Penyematan Teks
Lainnya Model
Toolkit/Framework
TokenPlan
Model production
Manajemen file
Penagihan
Manajemen Model
Lebih Banyak Tentang Model
Referensi SDK Python kloning suara - Alibaba Cloud Model Studio