Skip to main content

API HTTP kloning suara: Qwen-Audio dan CosyVoice

Parameter HTTP, respons, dan contoh kloning suara untuk Qwen-Audio dan CosyVoice.

Referensi ini mencakup Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice. Pertama, dapatkan API Key dan konfigurasikan variabel lingkungan. Contoh permintaan membaca DASHSCOPE_API_KEY. Gunakan akun yang sama saat mengelola suara yang sama melalui API berbeda. Untuk definisi SDK, lihat Java SDK dan Python SDK.

Titik akhir layanan

  • Tiongkok (Beijing)
  • Singapura
POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization
Ganti {WorkspaceId} dengan ID ruang kerja yang sebenarnya. ID ini tersedia pada halaman Workspace Details di konsol Alibaba Cloud Model Studio. API Key untuk Beijing dan Singapura berbeda.
Alibaba Cloud Model Studio telah merilis domain khusus ruang kerja untuk wilayah China (Beijing) dan Singapore. Domain khusus baru ini memberikan performa lebih unggul dan stabilitas lebih tinggi untuk permintaan inferensi. Kami merekomendasikan migrasi ke domain baru:
  • Region Tiongkok (Beijing): Beralih dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
  • Region Singapura: Beralih dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com.
Domain yang ada tetap berfungsi sepenuhnya.

Header permintaan

ParameterTipeWajibDeskripsi
AuthorizationstringYaToken otentikasi dalam format Bearer <your_api_key>. Ganti <your_api_key> dengan Kunci API Anda yang sebenarnya.
Content-TypestringYaTetapkan ke application/json.

Persyaratan audio dan biaya

Untuk persyaratan audio, lihat Panduan pengguna kloning suara. Proses kloning Qwen-Audio-Realtime dijelaskan dalam Kloning suara percakapan suara realtime. Pembuatan suara Qwen-Audio-Realtime gratis. Panggilan model ditagih sesuai model tujuan. Lihat detailnya dalam Informasi penagihan dan batas jumlah dalam Informasi kuota.

Isi permintaan

model string — WajibAtur ke voice-enrollment.input object — Wajib

Properti

action string — WajibOperasi:
  • create_voice: Membuat suara.
  • list_voice: Mencantumkan suara.
  • query_voice: Melihat detail suara.
  • update_voice: Memperbarui suara.
  • delete_voice: Menghapus suara.
target_model string — Wajib saat membuatModel yang akan menggunakan suara. Model ini harus sama dengan model pada pemanggilan sintesis atau percakapan berikutnya; jika berbeda, pemanggilan gagal.Pilih model Qwen-Audio-TTS, Qwen-Audio-Realtime, atau CosyVoice yang mendukung kloning suara. Lihat ID model dan wilayah di Model yang didukung.audio string — Wajib saat membuat atau memperbarui jika url tidak diberikanAudio referensi untuk pembuatan, atau audio referensi baru untuk pembaruan. Menerima URL yang dapat diakses publik atau Data URI Base64, seperti data:audio/wav;base64,....
Kompatibel dengan parameter lama url. Jika menggunakan url, audio dapat dihilangkan. url akan dihentikan secara bertahap, jadi sebaiknya beralih ke audio.
prefix string — Wajib saat membuat; opsional saat mencantumkanSaat membuat: prefiks nama suara. Hanya angka dan huruf Inggris yang diizinkan, maksimal 10 karakter. Nama suara yang dihasilkan berformat {target_model}-{prefix}-{unique_id}.Saat mencantumkan: memfilter suara berdasarkan prefiks nama.language_hints array[string] — Opsional saat membuatMembantu model mengenali bahasa audio sampel agar karakteristik suara diekstrak lebih akurat dan hasil kloning lebih baik. Jika bahasa yang ditentukan tidak sesuai dengan bahasa audio sebenarnya, misalnya en untuk audio bahasa Mandarin, sistem mengabaikan pengaturan ini dan mendeteksi bahasa secara otomatis.Parameter ini berupa array dengan panjang harus 1.
Berlaku 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.1-realtime-flash, 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.
  • 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.1-realtime-flash、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: Indonesia
    • vi: Vietnam
    • it: Italia
    • es: Spanyol
    • ms: Melayu
    • fil: Filipino
    • ar: Arab
  • cosyvoice-v3-plus:
    • zh: Tionghoa
    • en: Inggris
    • fr: Prancis
    • de: Jerman
    • ja: Jepang
    • ko: Korea
    • ru: Rusia
  • cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash:
    • zh: Tionghoa
    • en: Inggris
    • fr: Prancis
    • de: Jerman
    • ja: Jepang
    • ko: Korea
    • ru: Rusia
    • pt: Portugis
    • th: Thai
    • id: Indonesia
    • vi: Vietnam
Nilai default: ["zh"].max_prompt_audio_length float — Opsional saat membuatDurasi maksimum (detik) audio referensi untuk kloning suara setelah prapemrosesan. Rentang nilai: [3.0, 30.0].Nilai default: 10.0.
Berlaku 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.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_preprocess boolean — Opsional saat membuatApakah prapemrosesan audio (pengurangan derau, peningkatan audio, dan normalisasi volume) diaktifkan. Aktifkan untuk rekaman dengan derau latar. Nonaktifkan untuk rekaman di lingkungan tenang agar karakteristik suara asli tetap terjaga.Default: false.
Berlaku 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.1-realtime-flash, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_volume_normalization string — Opsional saat membuatApakah volume audio sampel untuk kloning suara dinormalisasi. Nilai:
  • "true": Aktifkan normalisasi volume.
  • "false": Menonaktifkan normalisasi volume.
Jika diaktifkan, volume audio yang disintesis menggunakan suara yang dibuat dapat berbeda dibandingkan saat parameter ini dinonaktifkan.Nilai default: "false".page_index integer — Opsional saat mencantumkanIndeks halaman.page_size integer — Opsional saat mencantumkanJumlah entri per halaman.voice_id string — Wajib untuk melihat, memperbarui, atau menghapusID suara yang akan dilihat, diperbarui, atau dihapus.

Contoh permintaan

  • Buat
  • Daftar
  • Lihat detail
  • Perbarui
  • Hapus
Contoh ini menggunakan qwen-audio-3.1-tts-plus. Ganti target_model di dalam input dengan ID model target Anda yang sebenarnya.Konfigurasi berikut untuk region Singapura. Ganti "{WorkspaceId}" dengan ID ruang kerja yang sebenarnya. Konfigurasi berbeda menurut region.
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.1-tts-plus",
        "prefix": "myvoice",
        "audio": "https://your-audio-url.wav",
        "language_hints": ["en"],
        "enable_volume_normalization": "false"
    }
}'
Jika menggunakan file audio WAV lokal, buat Base64 Data URI dengan kode berikut dan tetapkan nilai audio pada bidang audio objek input dalam permintaan pembuatan atau pembaruan. Ganti sample.wav dengan jalur file audio lokal.
import base64
from pathlib import Path

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

Isi respons

request_id stringPengidentifikasi unik permintaan ini.output objectBerisi bidang untuk pembuatan, pencantuman, atau pengambilan detail suara. Pembaruan tidak mengembalikan data bisnis. Respons dapat menyertakan bidang preview_audio berupa objek kosong yang dapat diabaikan. Penghapusan mengembalikan objek kosong.
voice_id string — Dikembalikan saat membuatID suara.voice_list array[object] — Dikembalikan saat mencantumkanDaftar suara yang ditemukan.
voice_id stringID suara.target_model stringModel tujuan yang menggunakan suara (teks ke ucapan atau percakapan suara realtime).gmt_create stringWaktu pembuatan suara.gmt_modified stringWaktu perubahan terakhir.status stringStatus suara. Untuk nilai yang valid, lihat “Deskripsi status suara”.
resource_link string — Dikembalikan untuk detail suaraURL file audio.gmt_create string — Dikembalikan untuk detail suaraWaktu pembuatan suara.gmt_modified string — Dikembalikan untuk detail suaraWaktu perubahan terakhir.status string — Dikembalikan untuk detail suaraStatus suara. Untuk nilai yang valid, lihat “Deskripsi status suara”.target_model string — Dikembalikan untuk detail suaraModel tujuan yang menggunakan suara (teks ke ucapan atau percakapan suara realtime).
usage objectInformasi penggunaan untuk permintaan ini.
count integerSelalu 1. Untuk pembuatan suara, ini menunjukkan jumlah suara yang dibuat.

Contoh respons

  • Buat
  • Daftar
  • Lihat detail
  • Perbarui
  • Hapus
{
    "output": {
        "voice_id": "qwen-audio-3.1-tts-plus-myvoice-xxxxxx"
    },
    "usage": {
        "count": 1
    },
    "request_id": "xxxx-xxxx-xxxx"
}

Deskripsi status suara

Suara yang dibuat akan melalui proses peninjauan.
StatusDeskripsi
DEPLOYINGSedang dalam peninjauan atau pemrosesan.
OKPeninjauan berhasil. Suara siap digunakan.
UNDEPLOYEDPeninjauan ditolak. Suara tidak dapat digunakan.

Pesan kesalahan

Jika terjadi error, lihat Kode error untuk pemecahan masalah.