Referensi API HTTP kloning suara - Alibaba Cloud Model Studio

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

Titik akhir layanan

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

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

Header permintaan

Parameter Tipe Wajib Deskripsi

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 body permintaan. Tetapkan sesuai seri model: Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice: `application/json`.

Authorization

string

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

Content-Type

string

Jenis media body permintaan. Tetapkan sesuai seri model:

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice: application/json.

Buat suara

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice

Isi permintaan

modelstring(wajib)

Atur ke voice-enrollment.

inputobject(wajib)

Parameter input.

Properti

action string(wajib)

Atur ke create_voice.

target_model string(wajib)

Model target yang menggunakan suara. Harus sama dengan model yang menggunakan suara tersebut pada permintaan berikutnya; jika berbeda, permintaan akan gagal.

audio string(wajib)

Audio referensi untuk kloning suara. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya data:audio/wav;base64,....

CatatanParameter lama url tetap didukung. Anda dapat menghilangkan audio saat menggunakan url. Parameter url akan dihentikan secara bertahap; gunakan audio untuk permintaan baru.

prefix string(wajib)

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

language_hints array[string](opsional)

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 yang harus berisi tepat satu elemen.

CatatanBerlaku untuk qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash.

Klik untuk melihat bahasa yang didukung per model

qwen-audio-3.1-tts-plus, qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-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"].

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)

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

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",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'

Untuk file WAV lokal, gunakan kode berikut untuk membuat Base64 Data URI, lalu masukkan nilai audio ke input.audio dalam permintaan pembuatan atau pembaruan. Ganti sample.wav dengan jalur file audio lokal Anda.

import base64
from pathlib import Path

audio = "data:audio/wav;base64," + base64.b64encode(
    Path("sample.wav").read_bytes()
).decode("ascii")

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.

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Jumlah suara yang dibuat. Selalu 1.

Kloning suara

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

Kueri daftar suara

Berlaku untuk Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice.

Badan permintaan

modelstring(wajib)

Atur ke voice-enrollment.

inputobject(wajib)

Parameter input.

Properti

action string(wajib)

Tetapkan ke list_voice.

prefix string(opsional)

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.

Kueri daftar suara

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_idstring

Pengidentifikasi unik untuk permintaan ini.

outputobject

Data yang dikembalikan oleh model.

Properti

voice_listarray[object]

Daftar suara yang dikueri.

Properti

voice_idstring

ID suara. Gunakan dalam parameter voice pada TTS API.

gmt_createstring

Waktu pembuatan.

gmt_modifiedstring

Waktu modifikasi terakhir.

statusstring

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

usageobject

Informasi penggunaan untuk permintaan ini.

Properti

count integer

Selalu 1.

Kueri daftar suara

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

Kueri detail suara

Berlaku untuk Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice.

Isi permintaan

modelstring(wajib)

Atur ke voice-enrollment.

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.

Kueri detail suara

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

Berlaku untuk Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice.

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.

audio string(wajib)

Audio referensi baru. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya data:audio/wav;base64,....

CatatanParameter lama url tetap didukung. Anda dapat menghilangkan audio saat menggunakan url. Parameter url akan dihentikan secara bertahap; gunakan audio untuk permintaan baru.

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",
        "audio": "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

Berlaku untuk Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice.

Isi permintaan

modelstring(wajib)

Atur ke voice-enrollment.

inputobject(wajib)

Parameter input.

Properti

action string(wajib)

Tetapkan ke delete_voice.

voice_id string(wajib)

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

Hapus suara

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

Hapus suara

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

Deskripsi status suara

Suara yang dibuat melewati proses peninjauan. Status berikut berlaku untuk Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice.

Status	Deskripsi
DEPLOYING	Sedang dalam peninjauan atau pemrosesan.
OK	Peninjauan berhasil. Suara siap digunakan.
UNDEPLOYED	Peninjauan ditolak. Suara tidak dapat digunakan.