All Products
Search

This Product

    Alibaba Cloud Model Studio:Referensi API Voice Design

    Document Center

    Alibaba Cloud Model Studio:Referensi API Voice Design

    Last Updated:May 13, 2026

    Gunakan API HTTP Voice Design untuk membuat, menampilkan daftar, mengkueri, dan menghapus voice kustom.

    Endpoint

    Internasional

    Jika Anda memilih cakupan penerapan Internasional, sumber daya komputasi inferensi model dijadwalkan secara dinamis di seluruh dunia, tidak termasuk Tiongkok daratan. Data statis disimpan di wilayah yang Anda pilih. Wilayah yang didukung: Singapura.

    POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

    Tiongkok daratan

    Jika Anda memilih cakupan penerapan Tiongkok daratan, sumber daya komputasi inferensi model dibatasi hanya di Tiongkok daratan. Data statis disimpan di wilayah yang Anda pilih. Wilayah yang didukung: Tiongkok (Beijing).

    POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

    Header permintaan

    Parameter

    Tipe

    Wajib

    Deskripsi

    Authorization

    string

    Ya

    Token otorisasi 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.

    Membuat voice

    Isi permintaan

    Contoh berikut menggunakan URL wilayah Singapura. Untuk menggunakan model yang diterapkan di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

    Desain voice CosyVoice

    curl -X POST https://dashscope-intl.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"
    }
}'

    Desain voice Qwen

    curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "create",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "preferred_name": "announcer",
        "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.",
        "language": "en"
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

    model string (Wajib)

    Model desain voice. Nilai yang valid:

    • voice-enrollment: Desain voice CosyVoice.

    • qwen-voice-design: Desain voice Qwen.

    input object (Wajib)

    Objek parameter input.

    Properti

    action string (Wajib)

    Jenis operasi.

    • CosyVoice (voice-enrollment): Atur ke create_voice.

    • Qwen (qwen-voice-design): Atur ke create.

    target_model string (Wajib)

    Model text-to-speech (TTS) yang menggerakkan voice tersebut. Nilai ini harus sesuai dengan model yang digunakan saat Anda memanggil API TTS. Ketidaksesuaian akan menyebabkan sintesis gagal.

    voice_prompt string (Wajib)

    Deskripsi karakteristik voice yang diinginkan. Hanya bahasa Mandarin dan Inggris yang didukung.

    • CosyVoice (voice-enrollment): Maksimal 500 karakter.

    • Qwen (qwen-voice-design): Maksimal 2.048 karakter.

    preview_text string (Wajib)

    Teks untuk audio pratinjau.

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

    Penting

    Hanya berlaku untuk CosyVoice (ketika model adalah voice-enrollment).

    Awalan nama voice. Hanya digit dan huruf yang diizinkan, maksimal 10 karakter. Nama voice yang dihasilkan mengikuti format: {target_model}-vd-{prefix}-{unique_id}.

    preferred_name string (Wajib bersyarat)

    Penting

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

    Awalan nama voice. Hanya digit, huruf, dan garis bawah yang diizinkan, maksimal 16 karakter.

    language_hints array[string] (Opsional)

    Penting

    Hanya berlaku untuk CosyVoice (ketika model adalah voice-enrollment).

    Petunjuk bahasa untuk voice yang dihasilkan. Ini menentukan karakteristik bahasa dan pola pengucapan voice tersebut. Atur nilai ini sesuai dengan kasus penggunaan Anda. Bahasa yang ditentukan harus sesuai dengan bahasa preview_text.

    Saat ini, hanya elemen pertama yang digunakan.

    Nilai yang valid:

    • zh: Bahasa Tiongkok

    • en: Inggris

    Default: ["zh"].

    language string (Opsional)

    Penting

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

    Petunjuk bahasa untuk voice yang dihasilkan. Ini menentukan karakteristik bahasa dan pola pengucapan voice tersebut. Atur nilai ini sesuai dengan kasus penggunaan Anda. Bahasa yang ditentukan harus sesuai dengan bahasa preview_text.

    Nilai yang valid:

    • zh: Bahasa Tiongkok

    • en: Inggris

    • de: Jerman

    • it: Italia

    • pt: Portugis

    • es: Spanyol

    • ja: Jepang

    • ko: Korea

    • fr: Prancis

    • ru: Rusia

    Default: zh.

    parameters object (Opsional)

    Konfigurasi untuk Voice Design.

    Properti

    sample_rate int (Opsional)

    Laju sampel audio pratinjau, dalam Hz.

    • CosyVoice: 16000, 24000, atau 48000.

    • Qwen: 8000, 16000, 24000, atau 48000.

    Default: 24000.

    response_format string (Opsional)

    Format audio pratinjau.

    • CosyVoice: pcm, wav, atau mp3.

    • Qwen: pcm, wav, mp3, atau opus.

    Default: wav.

    Isi respons

    Desain voice CosyVoice

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

    Desain voice Qwen

    {
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "qwen3-tts-vd-realtime-2026-01-15",
        "voice": "yourVoice"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}
    Penting

    CosyVoice mengembalikan bidang voice_id, sedangkan Qwen mengembalikan bidang voice.

    request_id string

    Pengidentifikasi unik untuk permintaan ini.

    output object

    Data yang dikembalikan oleh model.

    Properti

    voice_id / voice string

    ID voice. CosyVoice mengembalikan voice_id, dan Qwen mengembalikan voice. Gunakan nilai ini langsung sebagai parameter voice di API TTS.

    preview_audio object

    Data audio pratinjau.

    Properti

    data string

    Data audio pratinjau, dikodekan Base64.

    sample_rate int

    Laju sampel audio pratinjau, dalam Hz.

    response_format string

    Format audio pratinjau.

    target_model string

    Model TTS yang menggerakkan voice tersebut.

    usage object

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    Jumlah voice yang dibuat. Selalu bernilai 1.

    Daftar suara

    Isi permintaan

    Contoh berikut menggunakan URL wilayah Singapura. Untuk menggunakan model yang diterapkan di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

    CosyVoice

    curl -X POST https://dashscope-intl.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
    }
}'

    Desain voice Qwen

    curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "list",
        "page_size": 10,
        "page_index": 0
    }
}'

    model string (Wajib)

    Model desain suara. Nilai yang valid:

    • voice-enrollment: Desain voice CosyVoice.

    • qwen-voice-design: Desain voice Qwen.

    input object (Wajib)

    Objek parameter input.

    Properti

    action string (Wajib)

    Jenis operasi. CosyVoice: list_voice. Qwen: list.

    prefix string (Opsional)

    Penting

    Hanya berlaku untuk CosyVoice.

    Filter voice berdasarkan awalan nama.

    page_index integer (Opsional)

    Indeks halaman.

    page_size integer (Opsional)

    Jumlah entri per halaman.

    Isi respons

    CosyVoice

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

    {
    "output": {
        "page_index": 0,
        "page_size": 10,
        "total_count": 1,
        "voice_list": [
            {
                "voice": "yourVoice",
                "gmt_create": "2025-08-11 17:59:32",
                "gmt_modified": "2025-08-11 17:59:32",
                "language": "zh",
                "target_model": "qwen3-tts-vd-realtime-2026-01-15",
                "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": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}
    Penting

    CosyVoice mengembalikan array voice_list di mana setiap item berisi bidang voice_id. Qwen juga mengembalikan array voice_list, tetapi setiap item berisi bidang voice sebagai gantinya. Respons Qwen juga mencakup bidang paginasi page_index, page_size, dan total_count.

    request_id string

    Pengidentifikasi unik untuk permintaan ini.

    output object

    Data yang dikembalikan oleh model.

    Properti

    page_index integer

    Penting

    Hanya dikembalikan oleh Qwen.

    Indeks halaman saat ini.

    page_size integer

    Penting

    Hanya dikembalikan oleh Qwen.

    Jumlah entri per halaman.

    total_count integer

    Penting

    Hanya dikembalikan oleh Qwen.

    Jumlah total voice.

    voice_list array[object]

    Daftar voice yang dikembalikan oleh kueri.

    Properti

    voice_id / voice string

    ID voice. CosyVoice menggunakan voice_id, dan Qwen menggunakan voice.

    gmt_create string

    Waktu pembuatan.

    gmt_modified string

    Waktu modifikasi terakhir.

    status string

    Penting

    Hanya dikembalikan oleh CosyVoice.

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

    target_model string

    Penting

    Hanya dikembalikan oleh Qwen.

    Model TTS yang menggerakkan voice tersebut.

    language string

    Bahasa suara.

    voice_prompt string

    Teks deskripsi voice.

    preview_text string

    Teks audio pratinjau.

    usage object

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    CosyVoice: selalu 1. Qwen: selalu 0.

    Mengkueri detail voice

    Isi permintaan

    Contoh berikut menggunakan URL wilayah Singapura. Untuk menggunakan model yang diterapkan di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

    CosyVoice

    curl -X POST https://dashscope-intl.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"
    }
}'

    Desain voice Qwen

    curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "query",
        "voice": "yourVoice"
    }
}'

    model string (Wajib)

    Model desain voice. Nilai yang valid:

    • voice-enrollment: Desain voice CosyVoice.

    • qwen-voice-design: Desain voice Qwen.

    input object (Wajib)

    Objek parameter input.

    Properti

    action string (Wajib)

    Jenis operasi. CosyVoice: query_voice. Desain voice Qwen: query.

    voice_id string (Wajib bersyarat)

    Penting

    Hanya berlaku untuk CosyVoice.

    ID voice yang akan dikueri.

    voice string (Wajib bersyarat)

    Penting

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

    Nama voice yang akan dikueri.

    Isi respons

    Desain voice CosyVoice

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

    Desain voice Qwen

    {
    "output": {
        "voice": "yourVoice",
        "gmt_create": "2025-08-11 17:59:32",
        "gmt_modified": "2025-08-11 17:59:32",
        "language": "zh",
        "target_model": "qwen3-tts-vd-realtime-2026-01-15"
    },
    "usage": {
        "count": 0
    },
    "request_id": "xxxx-xxxx-xxxx"
}
    Penting

    CosyVoice mengembalikan voice_id, voice_prompt, dan bidang lainnya. Qwen mengembalikan bidang voice dan language.

    request_id string

    Pengidentifikasi unik untuk permintaan ini.

    output object

    Data yang dikembalikan oleh model.

    Properti

    voice_id / voice string

    ID voice. CosyVoice mengembalikan voice_id, dan Qwen mengembalikan voice.

    gmt_create string

    Waktu pembuatan.

    gmt_modified string

    Waktu modifikasi terakhir.

    status string

    Penting

    Hanya dikembalikan oleh CosyVoice.

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

    target_model string

    Model TTS yang menggerakkan voice tersebut.

    language string

    Penting

    Hanya dikembalikan oleh desain voice Qwen.

    Bahasa suara.

    voice_prompt string

    Penting

    Hanya dikembalikan oleh desain voice CosyVoice.

    Teks deskripsi voice.

    preview_text string

    Penting

    Hanya dikembalikan oleh desain voice CosyVoice.

    Teks audio pratinjau.

    usage object

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    Selalu 1.

    Hapus suara

    Isi permintaan

    Contoh berikut menggunakan URL wilayah Singapura. Untuk menggunakan model yang diterapkan di wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization.

    CosyVoice

    curl -X POST https://dashscope-intl.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"
    }
}'

    Desain voice Qwen

    curl -X POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "qwen-voice-design",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}'

    model string (Wajib)

    Model desain voice. Nilai yang valid:

    • voice-enrollment: Desain voice CosyVoice.

    • qwen-voice-design: Desain voice Qwen.

    input object (Wajib)

    Objek parameter input.

    Properti

    action string (Wajib)

    Jenis operasi. CosyVoice: delete_voice. Qwen: delete.

    voice_id string (Wajib bersyarat)

    Penting

    Hanya berlaku untuk CosyVoice.

    ID voice yang akan dihapus.

    voice string (Wajib bersyarat)

    Penting

    Hanya berlaku untuk Qwen.

    Nama voice yang akan dihapus.

    Isi respons

    CosyVoice

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

    Qwen

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

    CosyVoice mengembalikan objek output kosong, sedangkan Qwen mengembalikan bidang voice.

    request_id string

    Pengidentifikasi unik untuk permintaan ini.

    output object

    Data yang dikembalikan oleh model. CosyVoice mengembalikan objek kosong. Qwen mengembalikan nama voice yang dihapus.

    Properti

    voice string

    Penting

    Hanya dikembalikan oleh Qwen.

    Nama voice yang dihapus.

    usage object

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    Selalu 1.

    Referensi status voice

    Setelah voice dibuat, voice tersebut melewati proses peninjauan. Tabel berikut menjelaskan setiap status. Sistem status ini hanya berlaku untuk CosyVoice (ketika model adalah voice-enrollment). Respons kueri dan daftar Qwen tidak menyertakan bidang status.

    Status

    Deskripsi

    DEPLOYING

    Dalam proses peninjauan atau pemrosesan.

    OK

    Peninjauan berhasil. Voice siap digunakan.

    UNDEPLOYED

    Peninjauan ditolak. Voice tidak dapat digunakan.