Alibaba Cloud Model Studio：API kloning suara CosyVoice

Deskripsi API

def create_voice(self, target_model: str, prefix: str, url: str, language_hints: List[str] = None) -> str:
    '''
    Membuat suara kustom baru.
    param: target_model Model sintesis suara yang menggerakkan suara. Nilai ini harus sama dengan model sintesis suara yang digunakan saat Anda memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal. Model yang direkomendasikan adalah cosyvoice-v3-flash atau cosyvoice-v3-plus.
    param: prefix Nama yang mudah diingat untuk suara (hanya digit, huruf besar dan kecil, serta garis bawah yang diizinkan, maksimal 10 karakter). Gunakan pengenal yang terkait dengan peran atau skenario. Kata kunci ini muncul dalam nama suara yang dikloning. Format nama suara yang dihasilkan adalah: model_name-prefix-unique_identifier, misalnya, cosyvoice-v3-plus-myvoice-xxxxxxxx.
    param: url URL file audio untuk kloning suara. URL harus dapat diakses publik.
    param: language_hints Menentukan bahasa dari audio sampel yang digunakan untuk mengekstraksi fitur suara target. Parameter ini hanya berlaku untuk model cosyvoice-v3-flash dan cosyvoice-v3-plus.
            Parameter ini membantu model mengidentifikasi bahasa audio sampel (audio referensi asli) agar ekstraksi fitur suara lebih akurat dan meningkatkan hasil kloning.
            Jika petunjuk bahasa yang ditentukan tidak sesuai dengan bahasa audio aktual, misalnya menetapkan 'en' untuk file audio berbahasa Mandarin, sistem akan mengabaikan petunjuk tersebut dan mendeteksi bahasa secara otomatis dari konten audio.
            Nilai yang valid: zh (default), en, fr, de, ja, ko, ru. Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Kirim hanya satu nilai.
    return: voice_id ID suara. Dapat langsung digunakan untuk parameter voice dalam API sintesis suara.
    '''

Contoh permintaan

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

# Hindari pemanggilan berulang. Setiap panggilan membuat suara baru. Anda tidak dapat membuat lebih banyak suara setelah mencapai batas kuota.
voice_id = service.create_voice(
    target_model='cosyvoice-v3-plus',
    prefix='myvoice',
    url='https://your-audio-file-url',
    language_hints=['en']
)

print(f"Request ID: {service.get_last_request_id()}")
print(f"ID Suara: {voice_id}")

Deskripsi API

/**
 * Membuat suara kustom baru.
 *
 * @param targetModel Model sintesis suara yang menggerakkan suara. Nilai ini harus sama dengan model sintesis suara yang digunakan saat Anda memanggil API sintesis suara nanti. Jika tidak, sintesis akan gagal. Model yang direkomendasikan adalah cosyvoice-v3-flash atau cosyvoice-v3-plus.
 * @param prefix Nama yang mudah diingat untuk suara (hanya digit, huruf besar dan kecil, serta garis bawah yang diizinkan, maksimal 10 karakter). Gunakan pengenal yang terkait dengan peran atau skenario. Kata kunci ini muncul dalam nama suara yang dikloning. Format nama suara yang dihasilkan adalah: model_name-prefix-unique_identifier, misalnya, cosyvoice-v3-plus-myvoice-xxxxxxxx.
 * @param url URL file audio untuk kloning suara. URL harus dapat diakses publik.
 * @param customParam Parameter kustom. Anda dapat menentukan languageHints di sini.
 *                  languageHints menentukan bahasa dari audio sampel yang digunakan untuk mengekstraksi fitur suara target. Parameter ini hanya berlaku untuk model cosyvoice-v3-flash dan cosyvoice-v3-plus.
 *                  Parameter ini membantu model mengidentifikasi bahasa audio sampel (audio referensi asli) agar ekstraksi fitur suara lebih akurat dan meningkatkan hasil kloning.
 *                  Jika petunjuk bahasa yang ditentukan tidak sesuai dengan bahasa audio aktual, misalnya menetapkan 'en' untuk file audio berbahasa Mandarin, sistem akan mengabaikan petunjuk tersebut dan mendeteksi bahasa secara otomatis dari konten audio.
 *                  Nilai yang valid: zh (default), en, fr, de, ja, ko, ru. Parameter ini berupa array, tetapi versi saat ini hanya memproses elemen pertama. Kirim hanya satu nilai.
 * @return Voice Objek suara yang baru dibuat. Anda dapat memperoleh ID suara menggunakan metode getVoiceId dari objek Voice. ID tersebut dapat langsung digunakan untuk parameter voice dalam API sintesis suara.
 * @throws NoApiKeyException jika Kunci API kosong.
 * @throws InputRequiredException jika parameter yang diperlukan kosong.
 */
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Contoh permintaan

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 org.slf4j.Logger;
import org.slf4j.LoggerFactory;

import java.util.Collections;

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

    public static void main(String[] args) {
        String apiKey = System.getenv("DASHSCOPE_API_KEY");
        String targetModel = "cosyvoice-v3-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)
                    .languageHints(Collections.singletonList("en")).build());

            logger.info("Pembuatan suara berhasil dikirim. Request ID: {}", service.getLastRequestId());
            logger.info("ID Suara yang Dihasilkan: {}", myVoice.getVoiceId());
        } catch (Exception e) {
            logger.error("Gagal membuat suara", e);
        }
    }
}

Deskripsi API

def list_voices(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
    '''
    Mengkueri semua suara yang telah dibuat.
    param: prefix Awalan kustom untuk suara. Hanya digit dan huruf kecil yang diizinkan, maksimal 10 karakter.
    param: page_index Indeks halaman untuk kueri.
    param: page_size Ukuran halaman untuk kueri.
    return: List[dict] Daftar suara. Termasuk ID, waktu pembuatan, waktu modifikasi, dan status setiap suara. Format: [{'gmt_create': '2025-10-09 14:51:01', 'gmt_modified': '2025-10-09 14:51:07', 'status': 'OK', 'voice_id': 'cosyvoice-v3-myvoice-xxx'}]
    Terdapat tiga status suara:
        DEPLOYING: Sedang ditinjau
        OK: Disetujui dan siap digunakan
        UNDEPLOYED: Tidak disetujui dan tidak dapat digunakan
    '''

Contoh permintaan

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

# Filter berdasarkan awalan, atau atur ke None untuk mengkueri semua.
voices = service.list_voices(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Suara yang ditemukan: {voices}")

Contoh respons

[
    {
        "gmt_create": "2024-09-13 11:29:41",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 11:29:41",
        "status": "OK"
    },
    {
        "gmt_create": "2024-09-13 13:22:38",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 13:22:38",
        "status": "OK"
    }
]

Parameter respons

Deskripsi API

// Terdapat tiga status suara:
//        DEPLOYING: Sedang ditinjau
//        OK: Disetujui dan siap digunakan
//        UNDEPLOYED: Tidak disetujui dan tidak dapat digunakan
/**
 * Mengkueri semua suara yang telah dibuat. Indeks halaman default adalah 0, dan ukuran halaman default adalah 10.
 *
 * @param prefix Awalan kustom untuk suara. Hanya digit dan huruf kecil yang diizinkan, maksimal 10 karakter. Bisa null.
 * @return Voice[] Array objek Voice. Objek Voice mengenkapsulasi ID suara, waktu pembuatan, waktu modifikasi, dan status.
 * @throws NoApiKeyException jika Kunci API kosong.
 * @throws InputRequiredException jika parameter yang diperlukan kosong.
 */
public Voice[] listVoice(String prefix) throws NoApiKeyException, InputRequiredException 

/**
 * Mengkueri semua suara yang telah dibuat.
 *
 * @param prefix Awalan kustom untuk suara. Hanya digit dan huruf kecil yang diizinkan, maksimal 10 karakter.
 * @param pageIndex Indeks halaman untuk kueri.
 * @param pageSize Ukuran halaman untuk kueri.
 * @return Voice[] Array objek Voice. Objek Voice mengenkapsulasi ID suara, waktu pembuatan, waktu modifikasi, dan status.
 * @throws NoApiKeyException jika Kunci API kosong.
 * @throws InputRequiredException jika parameter yang diperlukan kosong.
 */
public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Contoh permintaan

Anda harus mengimpor 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.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Jika Anda belum mengonfigurasi variabel lingkungan, ganti ini dengan Kunci API Anda.
    private static String prefix = "myvoice"; // Ganti ini dengan nilai aktual Anda.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Kueri suara.
        Voice[] voices = service.listVoice(prefix, 0, 10);
        logger.info("Daftar berhasil. Request ID: {}", service.getLastRequestId());
        logger.info("Detail Suara: {}", new Gson().toJson(voices));
    }
}

Contoh respons

[
    {
        "gmt_create": "2024-09-13 11:29:41",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 11:29:41",
        "status": "OK"
    },
    {
        "gmt_create": "2024-09-13 13:22:38",
        "voice_id": "yourVoiceId",
        "gmt_modified": "2024-09-13 13:22:38",
        "status": "OK"
    }
]

Parameter respons

Deskripsi API

def query_voice(self, voice_id: str) -> List[str]:
    '''
    Mengkueri detail suara tertentu.
    param: voice_id ID suara yang akan dikueri.
    return: List[str] Detail suara, termasuk status, waktu pembuatan, tautan audio, dan lainnya.
    '''

Contoh permintaan

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()
voice_id = 'cosyvoice-v3-plus-myvoice-xxxxxxxx'

voice_details = service.query_voice(voice_id=voice_id)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Detail Suara: {voice_details}")

Contoh respons

{
    "gmt_create": "2024-09-13 11:29:41",
    "resource_link": "https://yourAudioFileUrl",
    "target_model": "cosyvoice-v3-plus",
    "gmt_modified": "2024-09-13 11:29:41",
    "status": "OK"
}

Parameter respons

Deskripsi API

/**
 * Mengkueri detail suara tertentu.
 *
 * @param voiceId ID suara yang akan dikueri.
 * @return Voice Detail suara, termasuk status, waktu pembuatan, tautan audio, dan lainnya.
 * @throws NoApiKeyException jika Kunci API kosong.
 * @throws InputRequiredException jika parameter yang diperlukan kosong.
 */
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Contoh permintaan

Anda harus mengimpor 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.google.gson.Gson;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Jika Anda belum mengonfigurasi variabel lingkungan, ganti ini dengan Kunci API Anda.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Ganti ini dengan nilai aktual Anda.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        Voice voice = service.queryVoice(voiceId);
        
        logger.info("Kueri berhasil. Request ID: {}", service.getLastRequestId());
        logger.info("Detail Suara: {}", new Gson().toJson(voice));
    }
}

Contoh respons

{
    "gmt_create": "2024-09-13 11:29:41",
    "resource_link": "https://yourAudioFileUrl",
    "target_model": "cosyvoice-v3-plus",
    "gmt_modified": "2024-09-13 11:29:41",
    "status": "OK"
}

Parameter respons

Deskripsi API

def update_voice(self, voice_id: str, url: str) -> None:
    '''
    Memperbarui suara.
    param: voice_id ID suara.
    param: url URL file audio untuk kloning suara.
    '''

Contoh permintaan

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()
service.update_voice(
    voice_id='cosyvoice-v3-plus-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Pembaruan berhasil dikirim. Request ID: {service.get_last_request_id()}")

Deskripsi API

/**
 * Memperbarui suara.
 *
 * @param voiceId Suara yang akan diperbarui.
 * @param url URL file audio untuk kloning suara.
 * @throws NoApiKeyException jika Kunci API kosong.
 * @throws InputRequiredException jika parameter yang diperlukan kosong.
 */
public void updateVoice(String voiceId, String url)
    throws NoApiKeyException, InputRequiredException

Contoh permintaan

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

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Jika Anda belum mengonfigurasi variabel lingkungan, ganti ini dengan Kunci API Anda.
    private static String fileUrl = "https://your-audio-file-url";  // Ganti ini dengan nilai aktual Anda.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Ganti ini dengan nilai aktual Anda.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    
    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Perbarui suara.
        service.updateVoice(voiceId, fileUrl);
        logger.info("Pembaruan berhasil dikirim. Request ID: {}", service.getLastRequestId());
    }
}

Deskripsi API

def delete_voice(self, voice_id: str) -> None:
    '''
    Menghapus suara.
    param: voice_id Suara yang akan dihapus.
    '''

Contoh permintaan

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()
service.delete_voice(voice_id='cosyvoice-v3-plus-myvoice-xxxxxxxx')
print(f"Penghapusan berhasil dikirim. Request ID: {service.get_last_request_id()}")

Deskripsi API

/**
 * Menghapus suara.
 *
 * @param voiceId Suara yang akan dihapus.
 * @throws NoApiKeyException jika Kunci API kosong.
 * @throws InputRequiredException jika parameter yang diperlukan kosong.
 */
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException 

Contoh permintaan

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

public class Main {
    public static String apiKey = System.getenv("DASHSCOPE_API_KEY");  // Jika Anda belum mengonfigurasi variabel lingkungan, ganti ini dengan Kunci API Anda.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Ganti ini dengan nilai aktual Anda.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    
    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Hapus suara.
        service.deleteVoice(voiceId);
        logger.info("Penghapusan berhasil dikirim. Request ID: {}", service.getLastRequestId());
    }
}