Referensi API Voice Design - Alibaba Cloud Model Studio

Panduan pengguna: Voice Design.

Endpoint

Singapura
China (Beijing)

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customizationGanti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapura. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru berikut:

China (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 Workspace ID Anda yang sebenarnya. Domain lama tetap berfungsi penuh.

Header permintaan

Parameter	Type	Wajib	Deskripsi
Authorization	string	Ya	Atur ke `Bearer <your_api_key>`. Ganti `<your_api_key>` dengan Kunci API Anda.
Content-Type	string	Ya	Jenis media badan permintaan. Atur ke `application/json`.

Membuat voice

Isi permintaan

modelstring(Wajib)Model desain voice. Nilai yang valid:

voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.
qwen-voice-design: desain voice Qwen.

inputobject(Wajib)Objek parameter input.

Properti

action string(Wajib)Jenis operasi.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Atur ke create_voice.
Qwen (qwen-voice-design): Atur ke create.

target_model string(Wajib)Model text-to-speech (TTS) untuk voice tersebut. Harus sesuai dengan model dalam panggilan API TTS, atau sintesis akan gagal.qwen-audio-3.0-tts-plus dan qwen-audio-3.0-tts-flash tidak mendukung Voice Design.voice_prompt string(Wajib)Deskripsi karakteristik voice yang diinginkan. Hanya bahasa Mandarin dan Inggris.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Maksimal 500 karakter.
Qwen (qwen-voice-design): Maksimal 2.048 karakter.

preview_text string(Wajib)Teks untuk audio pratinjau.

Qwen-Audio-TTS/CosyVoice (voice-enrollment): Maksimal 200 karakter. Mendukung bahasa Mandarin dan Inggris.
Qwen (qwen-voice-design): Maksimal 1.024 karakter. Mendukung bahasa Mandarin, Inggris, Jerman, Italia, Portugis, Spanyol, Jepang, Korea, Prancis, dan Rusia.

prefix string(Wajib bersyarat)

Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment).

Awalan nama voice. Hanya alfanumerik, maksimal 10 karakter. Format nama yang dihasilkan: {target_model}-vd-{prefix}-{unique_id}preferred_name string(Wajib bersyarat)

Hanya berlaku untuk Qwen (ketika model adalah qwen-voice-design).

Awalan nama voice. Alfanumerik dan garis bawah, maksimal 16 karakter.language_hints array[string](Opsional)

Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice (ketika model adalah voice-enrollment).

Petunjuk bahasa untuk pembuatan voice. Harus sesuai dengan bahasa preview_text.Saat ini, hanya elemen pertama yang digunakan.Nilai yang valid:

zh: Bahasa Mandarin
en: Inggris

Bawaan: ["zh"].language string(Opsional)

Hanya berlaku untuk Qwen (ketika model adalah qwen-voice-design).

Petunjuk bahasa untuk pembuatan voice. Harus sesuai dengan bahasa preview_text.Nilai yang valid:

zh: Bahasa Mandarin
en: Inggris
de: Jerman
it: Bahasa Italia
pt: Portugis
es: Spanyol
ja: Jepang
ko: Korea
fr: Prancis
ru: Rusia

Bawaan: zh.

parametersobject(Opsional)Konfigurasi untuk desain suara.

Properti

sample_rate int(Opsional)Laju sampel audio pratinjau, dalam Hz.

Qwen-Audio-TTS/CosyVoice: 16000, 24000, atau 48000.
Qwen: 8000, 16000, 24000, atau 48000.

Bawaan: 24000.response_format string(Opsional)Format audio pratinjau.

Qwen-Audio-TTS/CosyVoice: pcm, wav, atau mp3.
Qwen: pcm, wav, mp3, atau opus.

Bawaan: wav.

Desain voice Qwen-Audio-TTS/CosyVoice hanya tersedia di wilayah Beijing. Desain voice Qwen mendukung wilayah Singapura. Contoh Qwen-Audio-TTS/CosyVoice di bawah ini menggunakan URL wilayah China (Beijing). Contoh Qwen di bawah ini menggunakan URL wilayah Singapura (ganti {WorkspaceId} dengan workspace ID 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": "cosyvoice-v3.5-plus",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "prefix": "announcer",
        "language_hints": ["en"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

Isi Respons

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

Properti

voice_id / voicestringQwen-Audio-TTS/CosyVoice mengembalikan voice_id; Qwen mengembalikan voice. Gunakan nilai ini sebagai parameter voice dalam panggilan API TTS.preview_audioobjectData audio pratinjau.

Properti

data stringData audio pratinjau yang dienkripsi dalam Base64.sample_rate intLaju sampel audio pratinjau, dalam Hz.response_format stringFormat audio pratinjau.

target_model stringModel TTS yang mendasari suara tersebut.

usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerJumlah voice yang dibuat. Selalu 1.

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "cosyvoice-v3.5-plus",
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice mengembalikan bidang voice_id, sedangkan Qwen mengembalikan bidang voice.

Daftar suara

Badan permintaan

modelstring(Wajib)Model desain voice. Nilai yang valid:

voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.
qwen-voice-design: desain voice Qwen.

inputobject(Wajib)Objek parameter input.

Properti

action string(Wajib)Jenis operasi. Qwen-Audio-TTS/CosyVoice: list_voice. Qwen: list.prefix string(Opsional)

Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice.

Filter voice berdasarkan awalan nama.page_index integer(Opsional)Indeks halaman.page_size integer(Opsional)Jumlah entri per halaman.

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 tanggapan

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 voice.voice_listarray[object]Daftar voice yang dikembalikan oleh kueri.

Properti

voice_id / voicestringID voice. Qwen-Audio-TTS/CosyVoice menggunakan voice_id, dan Qwen menggunakan voice.gmt_createstringWaktu pembuatan.gmt_modifiedstringWaktu modifikasi terakhir.statusstring

Hanya dikembalikan oleh Qwen-Audio-TTS/CosyVoice.

Status voice. Untuk nilai yang valid, lihat "Referensi status voice".target_modelstring

Hanya dikembalikan oleh Qwen.

Model TTS yang mendorong voice tersebut.languagestringBahasa suara.voice_promptstringTeks deskripsi voice.preview_textstringTeks audio pratinjau.

usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerQwen-Audio-TTS/CosyVoice: selalu 1. Qwen: selalu 0.

{
    "output": {
        "voice_list": [
            {
                "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
                "gmt_create": "2025-12-10 14:54:09",
                "gmt_modified": "2025-12-10 17:47:48",
                "status": "OK",
                "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary.",
                "preview_text": "Dear listeners, hello everyone. Welcome to the evening news."
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice mengembalikan array voice_list dengan voice_id per item. Qwen mengembalikan voice_list dengan voice sebagai gantinya, ditambah page_index, page_size, dan total_count untuk paginasi.

Mengkueri detail voice

Isi permintaan

modelstring(Wajib)Model desain voice. Nilai yang valid:

voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.
qwen-voice-design: desain voice Qwen.

inputobject(Wajib)Objek parameter input.

Properti

action string(Wajib)Jenis operasi. Qwen-Audio-TTS/CosyVoice: query_voice. Desain voice Qwen: query.voice_id string(Wajib bersyarat)

Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice.

ID voice yang akan dikueri.voice string(Wajib bersyarat)

Hanya berlaku untuk desain voice Qwen (ketika model adalah qwen-voice-design).

Nama voice yang akan dikueri.

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

voice_id / voicestringID voice. Qwen-Audio-TTS/CosyVoice mengembalikan voice_id, dan Qwen mengembalikan voice.gmt_createstringWaktu pembuatan.gmt_modifiedstringWaktu modifikasi terakhir.statusstring

Hanya dikembalikan oleh Qwen-Audio-TTS/CosyVoice.

Status voice. Untuk nilai yang valid, lihat "Referensi status voice".target_modelstringModel TTS yang menghasilkan suara.languagestring

Hanya dikembalikan oleh desain voice Qwen.

Bahasa suara.voice_promptstring

Hanya dikembalikan oleh desain voice Qwen-Audio-TTS/CosyVoice.

Teks deskripsi voice.preview_textstring

Hanya dikembalikan oleh desain voice Qwen-Audio-TTS/CosyVoice.

Teks audio pratinjau.

usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerQwen: selalu 0. Tidak dikembalikan oleh Qwen-Audio-TTS/CosyVoice (objek usage kosong).

{
    "output": {
        "voice_id": "cosyvoice-v3.5-plus-vd-announcer-xxxxxx",
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "preview_text": "Dear listeners, hello everyone. Welcome to the evening news.",
        "target_model": "cosyvoice-v3.5-plus",
        "status": "OK",
        "voice_prompt": "A composed middle-aged male announcer with a deep, rich and magnetic voice, a steady speaking speed and clear articulation, is suitable for news broadcasting or documentary commentary."
    },
    "usage": {},
    "request_id": "xxxx-xxxx-xxxx"
}

Qwen-Audio-TTS/CosyVoice mengembalikan voice_id, voice_prompt, dan bidang lainnya. Qwen mengembalikan bidang voice dan language.

Hapus suara

Isi permintaan

modelstring(Wajib)Model desain voice. Nilai yang valid:

voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.
qwen-voice-design: desain voice Qwen.

inputobject(Wajib)Objek parameter input.

Properti

action string(Wajib)Jenis operasi. Qwen-Audio-TTS/CosyVoice: delete_voice. Qwen: delete.voice_id string(Wajib bersyarat)

Hanya berlaku untuk Qwen-Audio-TTS/CosyVoice.

ID voice yang akan dihapus.voice string(Wajib bersyarat)

Hanya berlaku untuk Qwen.

Nama voice yang akan dihapus.

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

Isi respons

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

Properti

voicestring

Hanya dikembalikan oleh Qwen.

Nama voice yang dihapus.

usageobjectInformasi penggunaan untuk permintaan ini.

Properti

count integerQwen-Audio-TTS/CosyVoice: selalu 1. Qwen: selalu 0.

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

Qwen-Audio-TTS/CosyVoice mengembalikan objek output kosong, sedangkan Qwen mengembalikan bidang voice.

Referensi status voice

Voice yang dibuat melewati proses peninjauan. Status berikut hanya berlaku untuk Qwen-Audio-TTS/CosyVoice (model voice-enrollment). Tanggapan Qwen tidak menyertakan bidang status.

Status	Deskripsi
DEPLOYING	Dalam peninjauan atau pemrosesan.
OK	Peninjauan lolos. Voice siap digunakan.
UNDEPLOYED	Peninjauan ditolak. Voice tidak dapat digunakan.

​Endpoint

​Header permintaan

​Membuat voice

Isi permintaan

Isi Respons

​Daftar suara

Badan permintaan

Badan tanggapan

​Mengkueri detail voice

Isi permintaan

Isi respons

​Hapus suara

Isi permintaan

Isi respons

​Referensi status voice

Endpoint

Header permintaan

Membuat voice

Daftar suara

Mengkueri detail voice

Hapus suara

Referensi status voice