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:Oct 21, 2026

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

    Panduan pengguna: Voice Design.

    Endpoint

    China (Beijing)

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

    Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

    PentingAlibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing). 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

    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.

    inputobject(Wajib)

    Objek parameter input.

    Properti

    action string(Wajib)

    Jenis operasi.

    • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Atur ke create_voice.

    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.

    preview_text string(Wajib)

    Teks untuk audio pratinjau.

    • Qwen-Audio-TTS/CosyVoice (voice-enrollment): Maksimal 200 karakter. Mendukung bahasa Mandarin dan Inggris.

    prefix string(Wajib)

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

    language_hints array[string](Opsional)

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

    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.

    Bawaan: 24000.

    response_format string(Opsional)

    Format audio pratinjau.

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

    Bawaan: wav.

    Contoh berikut menggunakan konfigurasi wilayah China (Beijing). Ganti {WorkspaceId} dengan ID workspace Anda yang sebenarnya.

    curl -X POST https://{WorkspaceId}.cn-beijing.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_idstring

    Pengidentifikasi unik untuk permintaan ini.

    outputobject

    Data yang dikembalikan oleh model.

    Properti

    voice_idstring

    ID suara. Gunakan dalam parameter voice pada TTS API.

    preview_audioobject

    Data audio pratinjau.

    Properti

    data string

    Data audio pratinjau yang dienkripsi dalam Base64.

    sample_rate int

    Laju sampel audio pratinjau, dalam Hz.

    response_format string

    Format audio pratinjau.

    target_model string

    Model TTS yang mendasari suara tersebut.

    usageobject

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

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

    Daftar suara

    Badan permintaan

    modelstring(Wajib)

    Model desain voice. Nilai yang valid:

    • voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.

    inputobject(Wajib)

    Objek parameter input.

    Properti

    action string(Wajib)

    Tetapkan ke list_voice.

    prefix string(Opsional)

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

    Contoh berikut menggunakan konfigurasi wilayah China (Beijing). Ganti {WorkspaceId} dengan ID workspace Anda yang sebenarnya.

    curl -X POST https://{WorkspaceId}.cn-beijing.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_idstring

    Pengidentifikasi unik untuk permintaan ini.

    outputobject

    Data yang dikembalikan oleh model.

    Properti

    voice_listarray[object]

    Daftar voice yang dikembalikan oleh kueri.

    Properti

    voice_idstring

    ID suara. Gunakan dalam parameter voice pada TTS API.

    gmt_createstring

    Waktu pembuatan.

    gmt_modifiedstring

    Waktu modifikasi terakhir.

    statusstring

    PentingHanya dikembalikan oleh Qwen-Audio-TTS/CosyVoice.

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

    voice_promptstring

    Teks deskripsi voice.

    preview_textstring

    Teks audio pratinjau.

    usageobject

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    Selalu 1.

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

    Mengkueri detail voice

    Isi permintaan

    modelstring(Wajib)

    Model desain voice. Nilai yang valid:

    • voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.

    inputobject(Wajib)

    Objek parameter input.

    Properti

    action string(Wajib)

    Tetapkan ke query_voice.

    voice_id string(Wajib)

    PentingHanya berlaku untuk Qwen-Audio-TTS/CosyVoice.

    ID voice yang akan dikueri.

    Contoh berikut menggunakan konfigurasi wilayah China (Beijing). Ganti {WorkspaceId} dengan ID workspace Anda yang sebenarnya.

    curl -X POST https://{WorkspaceId}.cn-beijing.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

    voice_idstring

    ID suara. Gunakan dalam parameter voice pada TTS API.

    gmt_createstring

    Waktu pembuatan.

    gmt_modifiedstring

    Waktu modifikasi terakhir.

    statusstring

    PentingHanya dikembalikan oleh Qwen-Audio-TTS/CosyVoice.

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

    target_modelstring

    Model TTS yang menghasilkan suara.

    voice_promptstring

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

    Teks deskripsi voice.

    preview_textstring

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

    Teks audio pratinjau.

    usageobject

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    Selalu 1.

    {
    "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": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

    Hapus suara

    Isi permintaan

    modelstring(Wajib)

    Model desain voice. Nilai yang valid:

    • voice-enrollment: desain voice Qwen-Audio-TTS/CosyVoice.

    inputobject(Wajib)

    Objek parameter input.

    Properti

    action string(Wajib)

    Tetapkan ke delete_voice.

    voice_id string(Wajib)

    PentingHanya berlaku untuk Qwen-Audio-TTS/CosyVoice.

    ID voice yang akan dihapus.

    Contoh berikut menggunakan konfigurasi wilayah China (Beijing). Ganti {WorkspaceId} dengan ID workspace Anda yang sebenarnya.

    curl -X POST https://{WorkspaceId}.cn-beijing.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_idstring

    Pengidentifikasi unik untuk permintaan ini.

    outputobject

    Data yang dikembalikan oleh model. Berupa objek kosong.

    usageobject

    Informasi penggunaan untuk permintaan ini.

    Properti

    count integer

    Selalu 1.

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

    Referensi status voice

    Suara yang dibuat melewati proses peninjauan. Status berikut berlaku untuk Qwen-Audio-TTS/CosyVoice ketika model adalah voice-enrollment.

    Status

    Deskripsi

    DEPLOYING

    Dalam peninjauan atau pemrosesan.

    OK

    Peninjauan lolos. Voice siap digunakan.

    UNDEPLOYED

    Peninjauan ditolak. Voice tidak dapat digunakan.