Skip to main content
Referensi API Voice Cloning

Referensi API HTTP kloning suara

Gunakan API HTTP untuk membuat, menampilkan daftar, mengkueri, memperbarui, dan menghapus suara yang dikloning.

Panduan pengguna: Kloning suara.

Titik akhir layanan

  • Singapura
  • Tiongkok (Beijing)
POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customizationGanti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah Tiongkok (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain berikut:
  • Tiongkok (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapura: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Ganti {WorkspaceId} dengan ID Ruang Kerja Anda yang sebenarnya. Domain lama tetap berfungsi sepenuhnya.

Header permintaan

Parameter

Tipe

Wajib

Deskripsi

Authorization

string

Ya

Token otentikasi dalam format Bearer <your_api_key>. Ganti <your_api_key> dengan Kunci API Anda yang sebenarnya.

Content-Type

string

Ya

Jenis media dari badan permintaan. Atur ke application/json untuk Qwen-Audio-TTS/CosyVoice/Qwen-TTS, atau application/json; charset=utf-8 untuk MiniMax.

Buat suara

Isi permintaan

modelstring(wajib)Model kloning suara. Nilai yang valid:
  • voice-enrollment: kloning suara Qwen-Audio-TTS/CosyVoice.
  • qwen-voice-enrollment: kloning suara Qwen-TTS.
inputobject(wajib)Parameter input.

Properti

action string(wajib)Jenis aksi.
  • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Atur ke create_voice.
  • Qwen (qwen-voice-enrollment): Atur ke create.
target_model string(wajib)Model text-to-speech (TTS) yang menggerakkan suara yang dikloning. Harus sesuai dengan model yang Anda tentukan saat memanggil API TTS; jika tidak, sintesis akan gagal.url string(wajib bersyarat)
Hanya berlaku untuk kloning suara Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment).
URL file audio untuk kloning suara. URL harus dapat diakses publik.audio object(wajib bersyarat)
Hanya berlaku untuk kloning suara Qwen-TTS (ketika model adalah qwen-voice-enrollment).
Data audio. Dua metode pengiriman didukung:
  • URL Data (Base64-encoded): Formatnya adalah {"data": "data:{mime_type};base64,{base64_encoded_data}"}. Jenis MIME yang didukung: audio/wav, audio/mpeg, dan audio/mp4.
  • URL Audio: Formatnya adalah {"data": "https://your-audio-url.wav"}. URL harus dapat diakses publik tanpa otentikasi.
text string(opsional)
Hanya berlaku untuk kloning suara Qwen-TTS (ketika model adalah qwen-voice-enrollment).
Transkrip audio, digunakan untuk meningkatkan kualitas kloning.prefix string(wajib bersyarat)
Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment).
Awalan untuk nama suara. Hanya karakter alfanumerik yang diizinkan, dengan panjang maksimum 10 karakter. Nama suara yang dihasilkan mengikuti format berikut: {target_model}-{prefix}-{unique_id}.preferred_name string(wajib bersyarat)
Hanya berlaku untuk kloning suara Qwen-TTS (ketika model adalah qwen-voice-enrollment).
Awalan untuk nama suara. Hanya karakter alfanumerik dan garis bawah (_) yang diizinkan, dengan panjang maksimum 16 karakter.language_hints array[string](opsional)
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 untuk mengekstraksi fitur suara lebih akurat dan meningkatkan kualitas kloning. Jika bahasa yang ditentukan tidak sesuai dengan bahasa audio sebenarnya (misalnya, mengatur en saat audionya dalam bahasa Tiongkok), 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: Tiongkok
    • 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 Mandarin
    • en: Inggris
    • fr: Prancis
    • de: Jerman
    • ja: Jepang
    • ko: Korea
    • ru: Rusia
    • pt: Portugis
    • th: Thai
    • id: Bahasa Indonesia
    • vi: Vietnam
Default: ["zh"].language string(opsional)
Hanya berlaku untuk kloning suara Qwen-TTS (ketika model adalah qwen-voice-enrollment).
Bahasa dari audio yang disediakan di audio.data. Jika Anda menggunakan parameter ini, pastikan bahasa yang ditentukan sesuai dengan bahasa sebenarnya dari audio yang digunakan untuk kloning.Nilai yang valid:
  • zh: Tiongkok
  • en: Inggris
  • de: Jerman
  • it: Italia
  • pt: Portugis
  • es: Spanyol
  • ja: Jepang
  • ko: Bahasa Korea
  • fr: Prancis
  • ru: Rusia
Default: zh.max_prompt_audio_length float(opsional)
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) dari audio referensi setelah pra-pemrosesan. Nilai yang valid: [3.0, 30.0].Default: 10.0.enable_preprocess boolean(opsional)
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 noise, peningkatan audio, dan normalisasi volume). Aktifkan ini untuk rekaman dengan noise latar belakang. Nonaktifkan untuk rekaman di lingkungan tenang agar karakteristik suara asli tetap terjaga.Default: false.enable_volume_normalization string(opsional)
Hanya berlaku untuk kloning suara Qwen-Audio-TTS/CosyVoice ketika model diatur ke voice-enrollment.
Apakah akan menormalisasi volume audio sampel yang digunakan untuk kloning suara. Nilai yang valid:
  • "true": Aktifkan normalisasi volume.
  • "false": Nonaktifkan normalisasi volume.
Jika diaktifkan, audio yang disintesis dengan suara yang dibuat mungkin memiliki volume berbeda dibandingkan audio yang disintesis dengan suara yang dibuat dengan parameter ini dinonaktifkan.Default: "false".
Contoh ini menggunakan titik akhir wilayah Singapura. Untuk wilayah Beijing, gunakan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "qwen-audio-3.0-tts-flash",
        "prefix": "myvoice",
        "url": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'

Isi respons

request_idstringPengidentifikasi unik untuk permintaan ini.outputobjectData yang dikembalikan oleh model.

Properti

voice_id / voicestringID suara. Qwen-Audio-TTS/CosyVoice mengembalikan voice_id, sedangkan Qwen mengembalikan voice. Gunakan nilai ini langsung pada parameter voice API TTS.target_modelstring
Hanya dikembalikan oleh Qwen.
Model TTS yang menggerakkan suara yang dikloning.fallback_modeboolean
Hanya berlaku untuk kloning suara Qwen-TTS (ketika model adalah qwen-voice-enrollment).
Apakah suara dibuat dalam mode fallback. Nilai true menunjukkan bahwa kualitas audio buruk atau tidak sesuai dengan teks yang diberikan, sehingga kualitas kloning mungkin berkurang.fallback_reasonstring
Hanya dikembalikan ketika fallback_mode bernilai true.
Alasan fallback. Nilai yang mungkin termasuk no_merged_segments (tidak dapat menggabungkan segmen audio) dan no_valid_asr_segments (ketidaksesuaian parah antara audio dan teks).
usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerJumlah suara yang dibuat. Selalu 1.
{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
Qwen-Audio-TTS/CosyVoice mengembalikan bidang voice_id, sedangkan Qwen mengembalikan bidang voice. Kloning suara Qwen-TTS juga dapat mengembalikan bidang fallback_mode dan fallback_reason.

Kueri daftar suara

Badan permintaan

modelstring(wajib)Model kloning suara. Nilai yang valid:
  • voice-enrollment: kloning suara Qwen-Audio-TTS/CosyVoice.
  • qwen-voice-enrollment: kloning suara Qwen-TTS.
inputobject(wajib)Parameter input.

Properti

action string(wajib)Jenis aksi. Qwen-Audio-TTS/CosyVoice: list_voice. Qwen: list.prefix string(opsional)
Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice.
Menyaring suara berdasarkan awalan nama.page_index integer(opsional)Indeks halaman.page_size integer(opsional)Jumlah entri per halaman.
Contoh ini menggunakan titik akhir wilayah Singapura. Untuk wilayah Beijing, gunakan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

Badan respons

request_idstringPengidentifikasi unik untuk permintaan ini.outputobjectData yang dikembalikan oleh model.

Properti

page_indexinteger
Hanya dikembalikan oleh Qwen.
Indeks halaman saat ini.page_sizeinteger
Hanya dikembalikan oleh Qwen.
Jumlah entri per halaman.total_countinteger
Hanya dikembalikan oleh Qwen.
Total jumlah suara.voice_listarray[object]Daftar suara yang dikueri. Baik Qwen-Audio-TTS/CosyVoice maupun Qwen menggunakan nama bidang voice_list.

Properti

voice_id / voicestringID suara. Qwen-Audio-TTS/CosyVoice menggunakan voice_id, sedangkan Qwen menggunakan voice.gmt_createstringWaktu pembuatan.gmt_modifiedstringWaktu modifikasi terakhir.statusstring
Hanya dikembalikan oleh Qwen-Audio-TTS/CosyVoice.
Status suara. Untuk nilai yang valid, lihat "Deskripsi status suara".target_modelstring
Hanya dikembalikan oleh Qwen.
Model TTS yang menggerakkan suara yang dikloning.
usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerSelalu 1 untuk Qwen-Audio-TTS/CosyVoice. Selalu 0 untuk Qwen.
{
    "output": {
        "voice_list": [
            {
                "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx",
                "gmt_create": "2024-12-11 13:38:02",
                "gmt_modified": "2024-12-11 13:38:02",
                "status": "OK"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
Qwen-Audio-TTS/CosyVoice mengembalikan array voice_list di mana setiap entri berisi bidang voice_id. Qwen juga mengembalikan array voice_list, tetapi setiap entri berisi bidang voice sebagai gantinya. Output Qwen juga menyertakan bidang pagination page_index, page_size, dan total_count.

Kueri detail suara

Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment). Model Qwen tidak mendukung operasi kueri detail suara.

Isi permintaan

modelstring(wajib)Atur ke voice-enrollment (Qwen-Audio-TTS/CosyVoice).inputobject(wajib)Parameter input.

Properti

action string(wajib)Atur ke query_voice.voice_id string(wajib)ID suara yang akan dikueri.
Contoh ini menggunakan titik akhir wilayah Singapura. Untuk wilayah Beijing, gunakan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.
  • Qwen-Audio-TTS/CosyVoice
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceId"
    }
}'

Isi respons

request_idstringPengidentifikasi unik untuk permintaan ini.outputobjectData yang dikembalikan oleh model.

Properti

resource_linkstringURL file audio.gmt_createstringWaktu pembuatan.gmt_modifiedstringWaktu modifikasi terakhir.statusstringStatus suara. Untuk nilai yang valid, lihat "Deskripsi status suara".target_modelstringModel TTS yang menggerakkan suara yang dikloning.
usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerSelalu 1.
{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "qwen-audio-3.0-tts-flash",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Perbarui suara

Hanya berlaku untuk kloning suara Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment). Model Qwen tidak mendukung operasi pembaruan.

Isi permintaan

modelstring(wajib)Atur ke voice-enrollment.inputobject(wajib)Parameter input.

Properti

action string(wajib)Atur ke update_voice.voice_id string(wajib)ID suara yang akan diperbarui.url string(wajib)URL file audio baru. URL harus dapat diakses publik.
Contoh ini menggunakan titik akhir wilayah Singapura. Untuk wilayah Beijing, gunakan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "update_voice",
        "voice_id": "yourVoiceId",
        "url": "https://new-audio-url.wav"
    }
}'

Isi Respons

request_idstringPengidentifikasi unik untuk permintaan ini.outputobjectData yang dikembalikan oleh model. Operasi pembaruan tidak mengembalikan data bisnis. Tanggapan mungkin menyertakan bidang preview_audio, yang merupakan objek kosong yang dapat Anda abaikan.usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerSelalu 1.
{
    "output": {
        "preview_audio": {}
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Hapus suara

Isi permintaan

modelstring(wajib)Model kloning suara. Nilai yang valid:
  • voice-enrollment: kloning suara Qwen-Audio-TTS/CosyVoice.
  • qwen-voice-enrollment: kloning suara Qwen-TTS.
inputobject(wajib)Parameter input.

Properti

action string(wajib)Jenis aksi. Qwen-Audio-TTS/CosyVoice: delete_voice. Qwen: delete.voice_id string(wajib bersyarat)
Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice.
ID suara yang akan dihapus.voice string(wajib bersyarat)
Hanya berlaku untuk Qwen.
Nama suara yang akan dihapus.
Contoh ini menggunakan titik akhir wilayah Singapura. Untuk wilayah Beijing, gunakan: https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization.Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.
curl -X POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

Badan tanggapan

request_idstringPengidentifikasi unik untuk permintaan ini.outputobjectData yang dikembalikan oleh model. Qwen-Audio-TTS/CosyVoice mengembalikan objek kosong, sedangkan Qwen mengembalikan nama suara yang dihapus.

Properti

voicestring
Hanya dikembalikan oleh Qwen.
Nama suara yang dihapus.
usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerSelalu 1 untuk Qwen-Audio-TTS/CosyVoice. Selalu 0 untuk Qwen.
{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
Qwen-Audio-TTS/CosyVoice mengembalikan objek output kosong, sedangkan Qwen mengembalikan bidang voice dengan nama suara yang dihapus.

Deskripsi status suara

Setelah suara dibuat, suara tersebut melewati proses peninjauan. Status berikut hanya berlaku untuk Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment). Tanggapan kueri dan daftar Qwen tidak menyertakan bidang status.

Status

Deskripsi

DEPLOYING

Sedang dalam peninjauan atau pemrosesan.

OK

Peninjauan berhasil. Suara siap digunakan.

UNDEPLOYED

Peninjauan ditolak. Suara tidak dapat digunakan.

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