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

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

Panduan pengguna: Voice cloning.

Titik akhir layanan

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

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.

Beralih ke wilayah Singapore:

import com.alibaba.dashscope.utils.Constants;

// Set di awal kode Anda
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1";

Catatan:

Kunci API berbeda antar wilayah. Gunakan kunci API yang sesuai dengan wilayah target.

Pengaturan wilayah bersifat global dan memengaruhi semua panggilan API DashScope SDK.

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

Ganti {WorkspaceId} dengan Workspace ID Anda yang sebenarnya. Domain lama tetap berfungsi sepenuhnya.

Kelas VoiceEnrollmentService

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

Tujuan: Mengelola siklus hidup voice Qwen-Audio-TTS/CosyVoice yang dikloning (buat, daftar, ambil, perbarui, dan hapus).

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 text-to-speech (TTS) yang mendorong voice yang dikloning. Nilainya harus sesuai dengan model yang Anda tentukan saat memanggil API TTS; jika tidak, sintesis 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	URL file audio untuk voice cloning. URL tersebut harus dapat diakses publik.
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	URL file audio baru.
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>	Hanya berlaku untuk voice cloning Qwen-Audio-TTS/CosyVoice (ketika model adalah `voice-enrollment`). Hanya didukung oleh qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, v3-plus, dan v3-flash. 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, tetapi versi saat ini hanya memproses elemen pertama. Nilai yang valid bervariasi tergantung model: qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-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	Hanya berlaku untuk voice cloning Qwen-Audio-TTS/CosyVoice (ketika model adalah `voice-enrollment`). Hanya didukung oleh qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, dan v3-flash. Durasi maksimum (dalam detik) audio referensi setelah pra-pemrosesan. Nilai valid: [3,0, 30,0]. Default: 10,0.
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
enable_preprocess	boolean	Tidak	Hanya berlaku untuk voice cloning Qwen-Audio-TTS/CosyVoice (ketika model adalah `voice-enrollment`). Hanya didukung oleh qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, dan v3-flash. 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.
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);
        }
    }
}

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());
    }
}