Skip to main content

Referensi SDK Java kloning suara Qwen-Audio dan CosyVoice

Kloning dan kelola suara Qwen-Audio dan CosyVoice dengan SDK Java DashScope.

Titik akhir layanan

SDK menggunakan titik akhir China (Beijing) secara default. Untuk beralih ke wilayah lain, ubah Constants.baseHttpApiUrl sebelum inisialisasi.
  • API key berbeda antarwilayah. Gunakan API key untuk wilayah target.
  • Pengaturan wilayah bersifat global dan memengaruhi semua panggilan API SDK DashScope.
  • Singapore
  • China (Beijing)
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Ganti {WorkspaceId} dengan workspace ID Anda yang sebenarnya.
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:
  • 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:
ParameterTipeDeskripsi
apiKeyStringKunci API

createVoice() - Buat voice

Signature metode:
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException
Parameter:
ParameterTipeWajibDeskripsi
targetModelStringYaModel target yang menggunakan suara. Harus sama dengan model yang menggunakan suara tersebut pada permintaan berikutnya; jika berbeda, permintaan akan gagal.
prefixStringYaAwalan 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}.
urlStringYaAudio referensi untuk kloning suara. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya data:audio/wav;base64,....
customParamVoiceEnrollmentParamTidakParameter 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:
ParameterTypeWajibDeskripsi
prefixStringTidakMemfilter voice berdasarkan awalan nama.
pageIndexintTidakIndeks halaman, dimulai dari 0.
pageSizeintTidakJumlah catatan per halaman.
Nilai kembalian: Array Voice[]. Jika getTargetModel() mengembalikan null untuk item daftar, baca ID model tujuan dari voice.getData().get("target_model").

queryVoice() - Ambil detail voice

Signature metode:
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException
Parameter:
ParameterTypeWajibDeskripsi
voiceIdStringYaID voice yang akan diambil.
Nilai kembalian: Objek Voice yang berisi detail voice. Gunakan getTargetModel() untuk mendapatkan ID model tujuan.

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:
ParameterTipeWajibDeskripsi
voiceIdStringYaID voice yang akan diperbarui.
urlStringYaAudio referensi baru. Mendukung URL yang dapat diakses publik atau Base64 Data URI, misalnya data:audio/wav;base64,....
customParamVoiceEnrollmentParamTidakParameter kustom.

deleteVoice() - Hapus voice

Signature metode:
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException
Parameter:
ParameterTipeWajibDeskripsi
voiceIdStringYaID voice yang akan dihapus.

Kelas VoiceEnrollmentParam

Package: com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentParam Buat objek parameter menggunakan pola builder.
MetodeTipeDeskripsi
model(String)StringModel 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.
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.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.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)FloatDurasi maksimum (dalam detik) audio referensi setelah pra-pemrosesan. Nilai valid: [3,0, 30,0].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.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
parameter(String, Object)ObjectMenetapkan 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

ParameterTipeWajibDeskripsi
enable_preprocessbooleanTidakApakah 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.
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.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_volume_normalizationStringTidakApakah 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.1-tts-plus";
        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));
        for (Voice voice : voices) {
            logger.info("Model tujuan: {}", voice.getData().get("target_model"));
        }
    }
}

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.1-tts-plus-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));
        logger.info("Model tujuan: {}", voice.getTargetModel());
    }
}

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.1-tts-plus-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.1-tts-plus-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());
    }
}