Referensi SDK Java untuk voice cloning - DashScope - Alibaba Cloud Model Studio

Gunakan DashScope Java SDK untuk mengkloning dan mengelola voice Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice.

Titik akhir layanan

SDK menggunakan titik akhir China (Beijing) secara default. Untuk beralih ke wilayah lain, ubah Constants.baseHttpApiUrl sebelum inisialisasi.

Catatan

API key berbeda antarwilayah. Gunakan API key untuk wilayah target.
Pengaturan wilayah bersifat global dan memengaruhi semua panggilan API SDK DashScope.

Singapore

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1

Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

China (Beijing)

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1

Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.

PentingAlibaba 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:

China (Beijing): dari dashscope.aliyuncs.com ke {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: dari dashscope-intl.aliyuncs.com ke {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Kelas VoiceEnrollmentService

Package: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService

Tujuan: Mengelola siklus hidup suara hasil kloning Qwen-Audio-TTS, Qwen-Audio-Realtime, dan CosyVoice (membuat, mengkueri, memperbarui, dan menghapus).

Konstruktor

public VoiceEnrollmentService(String apiKey)

Parameter:

Parameter	Tipe	Deskripsi
apiKey	String	Kunci API

createVoice() - Buat voice

Signature metode:

public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Parameter:

Parameter	Tipe	Wajib	Deskripsi
targetModel	String	Ya	Model target yang menggunakan suara. Harus sama dengan model yang menggunakan suara tersebut pada permintaan berikutnya; jika berbeda, permintaan akan gagal.
prefix	String	Ya	Awalan untuk nama voice. Hanya karakter alfanumerik yang diperbolehkan, dengan panjang maksimum 10 karakter. Nama voice yang dihasilkan mengikuti format berikut: `{target_model}-{prefix}-{unique_id}`.
url	String	Ya	Audio referensi untuk kloning suara. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya `data:audio/wav;base64,...`.
customParam	VoiceEnrollmentParam	Tidak	Parameter kustom seperti languageHints dan maxPromptAudioLength.

Nilai kembalian: Objek Voice. Panggil getVoiceId() untuk mengambil ID voice.

listVoice() - Daftar voice

Signature metode:

public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Parameter:

Parameter	Type	Wajib	Deskripsi
prefix	String	Tidak	Memfilter voice berdasarkan awalan nama.
pageIndex	int	Tidak	Indeks halaman, dimulai dari 0.
pageSize	int	Tidak	Jumlah catatan per halaman.

Nilai kembalian: Array Voice[].

queryVoice() - Ambil detail voice

Signature metode:

public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parameter:

Parameter	Type	Wajib	Deskripsi
voiceId	String	Ya	ID voice yang akan diambil.

Nilai kembalian: Objek Voice yang berisi detail voice.

updateVoice() - Memperbarui suara

Signature metode:

public void updateVoice(String voiceId, String url) throws NoApiKeyException, InputRequiredException
public void updateVoice(String voiceId, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Parameter:

Parameter	Tipe	Wajib	Deskripsi
voiceId	String	Ya	ID voice yang akan diperbarui.
url	String	Ya	Audio referensi baru. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya `data:audio/wav;base64,...`.
customParam	VoiceEnrollmentParam	Tidak	Parameter kustom.

deleteVoice() - Hapus voice

Signature metode:

public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Parameter:

Parameter	Tipe	Wajib	Deskripsi
voiceId	String	Ya	ID voice yang akan dihapus.

Kelas VoiceEnrollmentParam

Package: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam

Buat objek parameter menggunakan pola builder.

Metode	Tipe	Deskripsi
model(String)	String	Model voice cloning. Nilainya harus "voice-enrollment".
`languageHints(List<String>)`	`List<String>`	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 aktual (misalnya, menetapkan `en` saat audionya dalam bahasa Mandarin), 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: Bahasa Korea ru: Rusia pt: Portugis th: Thai id: Indonesia vi: Vietnam it: Italia es: Spanyol ms: Malaysia 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 Default: ["zh"].
maxPromptAudioLength(Float)	Float	Durasi maksimum (dalam detik) audio referensi setelah pra-pemrosesan. Nilai valid: [3,0, 30,0]. Default: 10,0. 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-flash.
parameter(String, Object)	Object	Menetapkan parameter kustom, seperti parameter("language_hints", Arrays.asList("en")), parameter("max_prompt_audio_length", 10.0f), parameter("enable_preprocess", false), dan parameter("enable_volume_normalization", "false").

Parameter tambahan

Parameter Tipe Wajib Deskripsi

Parameter	Tipe	Wajib	Deskripsi
enable_preprocess	boolean	Tidak	Apakah akan mengaktifkan pra-pemrosesan audio (pengurangan noise, peningkatan audio, dan normalisasi volume). Aktifkan opsi ini untuk rekaman dengan noise latar belakang. Nonaktifkan untuk rekaman di lingkungan tenang agar karakteristik suara asli tetap terjaga. Default: false. 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-flash.
enable_volume_normalization	String	Tidak	Apakah akan menormalisasi volume audio sampel yang digunakan untuk voice cloning. Nilai yang valid adalah `"true"` dan `"false"`. Saat diaktifkan, audio yang disintesis dengan voice yang dibuat mungkin memiliki volume berbeda dibandingkan audio yang disintesis dengan voice yang dibuat tanpa mengaktifkan parameter ini. Default: `"false"`.

enable_preprocess

boolean

Tidak

Apakah akan mengaktifkan pra-pemrosesan audio (pengurangan noise, peningkatan audio, dan normalisasi volume). Aktifkan opsi ini untuk rekaman dengan noise latar belakang. Nonaktifkan untuk rekaman di lingkungan tenang agar karakteristik suara asli tetap terjaga.

Default: false.

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

enable_volume_normalization

String

Tidak

Apakah akan menormalisasi volume audio sampel yang digunakan untuk voice cloning. Nilai yang valid adalah "true" dan "false". Saat diaktifkan, audio yang disintesis dengan voice yang dibuat mungkin memiliki volume berbeda dibandingkan audio yang disintesis dengan voice yang dibuat tanpa mengaktifkan parameter ini. Default: "false".

Kode contoh

Buat voice

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Arrays;

public class Main {
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args) {
        // Contoh berikut menggunakan wilayah Singapore. Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. Untuk wilayah lain, sesuaikan URL-nya.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String targetModel = "qwen-audio-3.0-tts-flash";
        String prefix = "myvoice";
        String fileUrl = "https://your-audio-file-url";
        String cloneModelName = "voice-enrollment";

        try {
            VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
            Voice myVoice = service.createVoice(
                    targetModel,
                    prefix,
                    fileUrl,
                    VoiceEnrollmentParam.builder()
                            .model(cloneModelName)
                            .parameter("language_hints", Arrays.asList("en"))
                            // .parameter("max_prompt_audio_length", 10.0f)
                            // .parameter("enable_preprocess", false)
                            // .parameter("enable_volume_normalization", "false")
                            .build());

            logger.info("Permintaan pembuatan voice telah dikirim. Request ID: {}", service.getLastRequestId());
            logger.info("ID Voice yang Dihasilkan: {}", myVoice.getVoiceId());
        } catch (Exception e) {
            logger.error("Gagal membuat voice", e);
        }
    }
}

Untuk file WAV lokal, tambahkan penetapan berikut di dalam blok try di atas sebelum memanggil createVoice. Untuk memperbarui suara, masukkan juga Data URI melalui parameter url dari updateVoice. Ganti sample.wav dengan jalur file audio lokal Anda.

fileUrl = "data:audio/wav;base64," + java.util.Base64.getEncoder().encodeToString(
        java.nio.file.Files.readAllBytes(java.nio.file.Paths.get("sample.wav")));

Daftar voice

Contoh ini memerlukan library pihak ketiga com.google.gson.Gson.

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Ganti dengan kunci API Anda jika tidak menggunakan variabel lingkungan
    private static String prefix = "myvoice"; // Ganti dengan nilai Anda yang sebenarnya
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // Contoh berikut menggunakan wilayah Singapore. Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. Untuk wilayah lain, sesuaikan URL-nya.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Daftar voice
        Voice[] voices = service.listVoice(prefix, 0, 10);
        logger.info("Berhasil menampilkan daftar. Request ID: {}", service.getLastRequestId());
        logger.info("Detail Voice: {}", new Gson().toJson(voices));
    }
}

Ambil voice tertentu

Contoh ini memerlukan library pihak ketiga com.google.gson.Gson.

import com.alibaba.dashscope.audio.ttsv2.enrollment.Voice;
import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import com.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Ganti dengan kunci API Anda jika tidak menggunakan variabel lingkungan
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // Ganti dengan nilai Anda yang sebenarnya
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // Contoh berikut menggunakan wilayah Singapore. Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. Untuk wilayah lain, sesuaikan URL-nya.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        Voice voice = service.queryVoice(voiceId);

        logger.info("Berhasil mengambil data. Request ID: {}", service.getLastRequestId());
        logger.info("Detail Voice: {}", new Gson().toJson(voice));
    }
}

Perbarui voice

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Ganti dengan kunci API Anda jika tidak menggunakan variabel lingkungan
    private static String fileUrl = "https://your-audio-file-url";  // Ganti dengan nilai Anda yang sebenarnya
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // Ganti dengan nilai Anda yang sebenarnya
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // Contoh berikut menggunakan wilayah Singapore. Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. Untuk wilayah lain, sesuaikan URL-nya.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Perbarui voice
        service.updateVoice(voiceId, fileUrl);
        logger.info("Permintaan pembaruan telah dikirim. Request ID: {}", service.getLastRequestId());
    }
}

Hapus suara

import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Ganti dengan kunci API Anda jika tidak menggunakan variabel lingkungan
    private static String voiceId = "qwen-audio-3.0-tts-flash-myvoice-xxx"; // Ganti dengan nilai Anda yang sebenarnya
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        // Contoh berikut menggunakan wilayah Singapore. Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya. Untuk wilayah lain, sesuaikan URL-nya.
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Hapus voice
        service.deleteVoice(voiceId);
        logger.info("Permintaan penghapusan telah dikirim. Request ID: {}", service.getLastRequestId());
    }
}