Referensi API HTTP kloning suara - Alibaba Cloud Model Studio

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

Panduan pengguna: Kloning suara.

Titik akhir layanan

Singapura

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Ganti {WorkspaceId} dengan ID ruang kerja Anda yang sebenarnya.

Tiongkok (Beijing)

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

Ganti {WorkspaceId} dengan ID ruang kerja Anda.

PentingAlibaba 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)

PentingHanya 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)

PentingHanya 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)

PentingHanya berlaku untuk kloning suara Qwen-TTS (ketika model adalah qwen-voice-enrollment).

Transkrip audio, digunakan untuk meningkatkan kualitas kloning.

prefix string(wajib bersyarat)

PentingHanya 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)

PentingHanya 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)

PentingHanya 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)

PentingHanya 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)

Durasi maksimum (dalam detik) dari audio referensi setelah pra-pemrosesan. Nilai yang valid: [3.0, 30.0].

Default: 10.0.

enable_preprocess boolean(opsional)

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)

PentingHanya 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.

Kloning suara 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": "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"
    }
}'

Kloning suara Qwen-TTS

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": "qwen-voice-enrollment",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vc-realtime-2026-01-15",
        "preferred_name": "myvoice",
        "audio": {"data": "data:audio/mpeg;base64,{base64_encoded_audio}"}
    }
}'

Isi respons

request_idstring

Pengidentifikasi unik untuk permintaan ini.

outputobject

Data yang dikembalikan oleh model.

Properti

voice_id / voicestring

ID suara. Qwen-Audio-TTS/CosyVoice mengembalikan voice_id, sedangkan Qwen mengembalikan voice. Gunakan nilai ini langsung pada parameter voice API TTS.

target_modelstring

PentingHanya dikembalikan oleh Qwen.

Model TTS yang menggerakkan suara yang dikloning.

fallback_modeboolean

PentingHanya 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

PentingHanya 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).

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Jumlah suara yang dibuat. Selalu 1.

Kloning suara Qwen-Audio-TTS/CosyVoice

{
    "output": {
        "voice_id": "qwen-audio-3.0-tts-flash-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Kloning suara Qwen-TTS

{
    "output": {
        "voice": "yourVoice",
        "target_model": "qwen3-tts-vc-realtime-2026-01-15"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

PentingQwen-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)

PentingHanya 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.

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": "list_voice",
        "prefix": "myvoice",
        "page_size": 10,
        "page_index": 0
    }
}'

Kloning suara Qwen-TTS

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": "qwen-voice-enrollment",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

Badan respons

request_idstring

Pengidentifikasi unik untuk permintaan ini.

outputobject

Data yang dikembalikan oleh model.

Properti

page_indexinteger

PentingHanya dikembalikan oleh Qwen.

Indeks halaman saat ini.

page_sizeinteger

PentingHanya dikembalikan oleh Qwen.

Jumlah entri per halaman.

total_countinteger

PentingHanya 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 / voicestring

ID suara. Qwen-Audio-TTS/CosyVoice menggunakan voice_id, sedangkan Qwen menggunakan voice.

gmt_createstring

Waktu pembuatan.

gmt_modifiedstring

Waktu modifikasi terakhir.

statusstring

PentingHanya dikembalikan oleh Qwen-Audio-TTS/CosyVoice.

Status suara. Untuk nilai yang valid, lihat "Deskripsi status suara".

target_modelstring

PentingHanya dikembalikan oleh Qwen.

Model TTS yang menggerakkan suara yang dikloning.

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Selalu 1 untuk Qwen-Audio-TTS/CosyVoice. Selalu 0 untuk Qwen.

Qwen-Audio-TTS/CosyVoice

{
    "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

{
    "output": {
        "page_index": 0,
        "page_size": 10,
        "total_count": 2,
        "voice_list": [
            {
                "voice": "yourVoice1",
                "gmt_create": "2025-08-11 17:59:32",
                "gmt_modified": "2025-08-11 17:59:32",
                "language": "en",
                "target_model": "qwen3-tts-vc-realtime-2026-01-15"
            }
        ]
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

PentingQwen-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

PentingHanya 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_idstring

Pengidentifikasi unik untuk permintaan ini.

outputobject

Data yang dikembalikan oleh model.

Properti

resource_linkstring

URL file audio.

gmt_createstring

Waktu pembuatan.

gmt_modifiedstring

Waktu modifikasi terakhir.

statusstring

Status suara. Untuk nilai yang valid, lihat "Deskripsi status suara".

target_modelstring

Model TTS yang menggerakkan suara yang dikloning.

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Selalu 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

PentingHanya 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_idstring

Pengidentifikasi unik untuk permintaan ini.

outputobject

Data yang dikembalikan oleh model. Operasi pembaruan tidak mengembalikan data bisnis. Tanggapan mungkin menyertakan bidang preview_audio, yang merupakan objek kosong yang dapat Anda abaikan.

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Selalu 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)

PentingHanya berlaku untuk Qwen-Audio-TTS/CosyVoice.

ID suara yang akan dihapus.

voice string(wajib bersyarat)

PentingHanya 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.

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": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

Kloning suara Qwen-TTS

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": "qwen-voice-enrollment",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

Badan tanggapan

request_idstring

Pengidentifikasi unik untuk permintaan ini.

outputobject

Data yang dikembalikan oleh model. Qwen-Audio-TTS/CosyVoice mengembalikan objek kosong, sedangkan Qwen mengembalikan nama suara yang dihapus.

Properti

voicestring

PentingHanya dikembalikan oleh Qwen.

Nama suara yang dihapus.

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Selalu 1 untuk Qwen-Audio-TTS/CosyVoice. Selalu 0 untuk Qwen.

Qwen-Audio-TTS/CosyVoice

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

Qwen

{
    "output": {
        "voice": "yourVoice"
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}

PentingQwen-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.