API kloning suara CosyVoice - Alibaba Cloud Model Studio

Layanan kloning suara CosyVoice menggunakan model ucapan generatif berskala besar untuk membuat suara kustom yang sangat mirip dan alami hanya dari sampel audio berdurasi 10–20 detik—tanpa pelatihan tradisional. Desain suara menghasilkan suara kustom dari deskripsi teks dan mendukung definisi fitur suara multibahasa serta multidimensi. Kasus penggunaan meliputi narasi iklan, pembuatan suara karakter, dan produksi buku audio. Kloning suara dan desain suara merupakan dua langkah berurutan yang menjadi masukan bagi sintesis ucapan. Dokumen ini mencakup parameter dan antarmuka untuk kloning suara dan desain suara. Untuk sintesis ucapan, lihat Sintesis Ucapan Real-time – CosyVoice/Sambert.

Panduan Pengguna: Untuk pengenalan model dan panduan pemilihan, lihat Sintesis Ucapan Real-time – CosyVoice/Sambert.

Penting

Dokumen ini hanya mencakup API kloning suara dan desain suara CosyVoice. Jika Anda menggunakan model Qwen, lihat Kloning Suara (Qwen) dan Desain Suara (Qwen).
Desain suara CosyVoice menggunakan model FunAudioGen-VD.

Model yang Didukung

Kloning suara:
- cosyvoice-v3.5-plus, cosyvoice-v3.5-flash
- cosyvoice-v3-plus, cosyvoice-v3-flash
- cosyvoice-v2
Desain suara:
- cosyvoice-v3.5-plus, cosyvoice-v3.5-flash
- cosyvoice-v3-plus, cosyvoice-v3-flash

Penting

cosyvoice-v3.5-plus dan cosyvoice-v3.5-flash hanya tersedia dalam mode penyebaran China Mainland (Wilayah Beijing).
Dalam mode penyebaran Internasional (Wilayah Singapura), cosyvoice-v3-plus dan cosyvoice-v3-flash tidak mendukung kloning suara atau desain suara. Pilih model lain.

Bahasa yang Didukung

Kloning suara: Bergantung pada model sintesis ucapan target (ditentukan oleh parameter target_model/targetModel):
- cosyvoice-v2: Bahasa Tionghoa (Mandarin), Bahasa Inggris
- cosyvoice-v3-flash: Bahasa Tionghoa (Mandarin, Kanton, Timur Laut, Gansu, Guizhou, Henan, Hubei, Jiangxi, Minnan, Ningxia, Shanxi, Shaanxi, Shandong, Shanghai, Sichuan, Tianjin, Yunnan), Bahasa Inggris, Prancis, Jerman, Jepang, Korea, Rusia, Portugis, Thailand, Indonesia, Vietnam
- cosyvoice-v3-plus: Bahasa Tionghoa (Mandarin), Bahasa Inggris, Prancis, Jerman, Jepang, Korea, Rusia
- cosyvoice-v3.5-plus, cosyvoice-v3.5-flash: Bahasa Tionghoa (Mandarin, Kanton, Henan, Hubei, Minnan, Ningxia, Shaanxi, Shandong, Shanghai, Sichuan), Bahasa Inggris, Prancis, Jerman, Jepang, Korea, Rusia, Portugis, Thailand, Indonesia, Vietnam
Kloning suara saat ini tidak mendukung Bahasa Spanyol, Italia, atau bahasa lainnya.
Desain suara: Bahasa Tionghoa, Bahasa Inggris.

Memulai Cepat: Dari Kloning Suara hingga Sintesis Ucapan

Kloning suara dan sintesis ucapan adalah dua langkah independen namun saling terkait erat. Ikuti alur kerja “buat dulu, gunakan kemudian”:

Siapkan file rekaman audio
Unggah file audio yang memenuhi persyaratan format input kloning suara ke lokasi yang dapat diakses publik, seperti Alibaba Cloud OSS. Pastikan URL tersebut dapat diakses publik.
Buat suara
Panggil API Create voice. Anda harus menentukan target_model/targetModel untuk menyatakan model sintesis ucapan mana yang akan menggerakkan suara yang dibuat.
Jika Anda sudah memiliki suara yang dibuat (periksa menggunakan API List voices), lewati langkah ini dan lanjutkan ke langkah berikutnya.
Menggunakan timbre suara untuk sintesis ucapan
Setelah berhasil membuat suara menggunakan API Create voice, sistem mengembalikan voice_id/voiceID:
- Anda dapat langsung menggunakan voice_id/voiceID ini sebagai parameter voice dalam API sintesis ucapan atau di SDK untuk teks-ke-ucapan.
- Mendukung beberapa mode pemanggilan: sintesis non-streaming, streaming unidireksional, dan streaming bidireksional.
- Model sintesis ucapan yang digunakan selama sintesis harus sesuai dengan target_model/targetModel yang digunakan saat membuat suara. Jika tidak, sintesis gagal.

Kode contoh:

import os
import time
import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService, SpeechSynthesizer

# 1. Persiapan lingkungan
# Kami merekomendasikan mengonfigurasi kunci API Anda sebagai variabel lingkungan
# Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
if not dashscope.api_key:
    raise ValueError("Variabel lingkungan DASHSCOPE_API_KEY belum diatur.")

# Ini adalah URL WebSocket wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti dengan: wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'
# Ini adalah URL HTTP wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1
dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'


# 2. Tentukan parameter kloning
TARGET_MODEL = "cosyvoice-v3.5-plus" 
# Beri awalan bermakna untuk suara Anda
VOICE_PREFIX = "myvoice" # Hanya huruf dan angka. Kurang dari 10 karakter.
# URL audio yang dapat diakses publik
AUDIO_URL = "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav" # URL contoh. Ganti dengan milik Anda.

# 3. Buat suara (tugas asinkron)
print("--- Langkah 1: Membuat pendaftaran suara ---")
service = VoiceEnrollmentService()
try:
    voice_id = service.create_voice(
        target_model=TARGET_MODEL,
        prefix=VOICE_PREFIX,
        url=AUDIO_URL
    )
    print(f"Pendaftaran suara berhasil dikirim. ID Permintaan: {service.get_last_request_id()}")
    print(f"ID Suara yang Dihasilkan: {voice_id}")
except Exception as e:
    print(f"Kesalahan saat pembuatan suara: {e}")
    raise e
# 4. Periksa status suara secara berkala
print("\n--- Langkah 2: Memeriksa status suara ---")
max_attempts = 30
poll_interval = 10 # detik
for attempt in range(max_attempts):
    try:
        voice_info = service.query_voice(voice_id=voice_id)
        status = voice_info.get("status")
        print(f"Percobaan {attempt + 1}/{max_attempts}: Status suara adalah '{status}'")
        
        if status == "OK":
            print("Suara siap untuk sintesis.")
            break
        elif status == "UNDEPLOYED":
            print(f"Pemrosesan suara gagal dengan status: {status}. Harap periksa kualitas audio atau hubungi dukungan.")
            raise RuntimeError(f"Pemrosesan suara gagal dengan status: {status}")
        # Lanjutkan menunggu untuk status antara seperti "DEPLOYING"
        time.sleep(poll_interval)
    except Exception as e:
        print(f"Kesalahan saat memeriksa status: {e}")
        time.sleep(poll_interval)
else:
    print("Waktu pemeriksaan habis. Suara belum siap setelah beberapa percobaan.")
    raise RuntimeError("Waktu pemeriksaan habis. Suara belum siap setelah beberapa percobaan.")

# 5. Gunakan suara hasil kloning untuk sintesis ucapan
print("\n--- Langkah 3: Mensintesis ucapan dengan suara baru ---")
try:
    synthesizer = SpeechSynthesizer(model=TARGET_MODEL, voice=voice_id)
    text_to_synthesize = "Selamat! Anda berhasil mengkloning dan mensintesis suara Anda sendiri!"
    
    # Metode call() mengembalikan data audio biner
    audio_data = synthesizer.call(text_to_synthesize)
    print(f"Sintesis ucapan berhasil. ID Permintaan: {synthesizer.get_last_request_id()}")

    # 6. Simpan file audio
    output_file = "my_custom_voice_output.mp3"
    with open(output_file, "wb") as f:
        f.write(audio_data)
    print(f"Audio disimpan ke {output_file}")

except Exception as e:
    print(f"Kesalahan saat sintesis ucapan: {e}")

Memulai Cepat: Dari Desain Suara hingga Sintesis Ucapan

Desain suara dan sintesis ucapan adalah dua langkah independen namun saling terkait erat. Ikuti alur kerja “buat dulu, gunakan kemudian”:

Siapkan deskripsi suara dan teks pratinjau untuk desain suara.
- Prompt suara (voice_prompt): Menentukan karakteristik suara target. Untuk informasi lebih lanjut, lihat “Desain suara: Bagaimana cara menulis prompt suara berkualitas tinggi?”.
- Teks pratinjau (preview_text): Teks yang diucapkan dalam audio pratinjau (misalnya, “Halo semuanya, selamat datang untuk mendengarkan.”).
Panggil API Create voice untuk membuat suara kustom dan mendapatkan nama suara serta audio pratinjau.
Anda harus menentukan target_model untuk menyatakan model sintesis ucapan mana yang akan menggerakkan suara yang dibuat.
Anda dapat mendengarkan audio pratinjau untuk memeriksa apakah sesuai harapan. Jika sesuai, lanjutkan ke langkah berikutnya. Jika tidak, rancang ulang.
Jika Anda sudah memiliki suara yang dibuat (periksa menggunakan API List voices), lewati langkah ini dan lanjutkan ke langkah berikutnya.
Menggunakan Suara untuk Sintesis Ucapan
Setelah berhasil membuat suara menggunakan API Create voice, sistem mengembalikan voice_id/voiceID:
- Anda dapat langsung menggunakan voice_id/voiceID ini sebagai parameter voice dalam API sintesis ucapan atau di SDK untuk teks-ke-ucapan.
- Mendukung beberapa mode pemanggilan: sintesis non-streaming, streaming unidireksional, dan streaming bidireksional.
- Model sintesis ucapan yang digunakan selama sintesis harus sesuai dengan target_model/targetModel yang digunakan saat membuat suara. Jika tidak, sintesis gagal.

Kode contoh:

Buat suara kustom dan pratinjau. Jika puas, lanjutkan. Jika tidak, buat ulang.

Python

import requests
import base64
import os

def create_voice_and_play():
    # Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
    # Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")
    
    if not api_key:
        print("Kesalahan: Variabel lingkungan DASHSCOPE_API_KEY tidak ditemukan. Harap atur kunci API Anda terlebih dahulu.")
        return None, None, None
    
    # Siapkan data permintaan
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    data = {
        "model": "voice-enrollment",
        "input": {
            "action": "create_voice",
            "target_model": "cosyvoice-v3.5-plus",
            "voice_prompt": "Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter.",
            "preview_text": "Halo para pendengar, selamat datang di berita malam ini.",
            "prefix": "announcer"
        },
        "parameters": {
            "sample_rate": 24000,
            "response_format": "wav"
        }
    }
    
    # Ini adalah URL wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
    url = "https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization"
    
    try:
        # Kirim permintaan
        response = requests.post(
            url,
            headers=headers,
            json=data,
            timeout=60  # Tambahkan pengaturan timeout
        )
        
        if response.status_code == 200:
            result = response.json()
            
            # Dapatkan ID suara
            voice_id = result["output"]["voice_id"]
            print(f"ID Suara: {voice_id}")
            
            # Dapatkan data audio pratinjau
            base64_audio = result["output"]["preview_audio"]["data"]
            
            # Dekode data audio Base64
            audio_bytes = base64.b64decode(base64_audio)
            
            # Simpan file audio lokal
            filename = f"{voice_id}_preview.wav"
            
            # Tulis data audio ke file lokal
            with open(filename, 'wb') as f:
                f.write(audio_bytes)
            
            print(f"Audio disimpan ke file lokal: {filename}")
            print(f"Jalur file: {os.path.abspath(filename)}")
            
            return voice_id, audio_bytes, filename
        else:
            print(f"Permintaan gagal. Kode status: {response.status_code}")
            print(f"Tanggapan: {response.text}")
            return None, None, None
            
    except requests.exceptions.RequestException as e:
        print(f"Kesalahan permintaan jaringan: {e}")
        return None, None, None
    except KeyError as e:
        print(f"Kesalahan format tanggapan. Bidang wajib tidak ditemukan: {e}")
        print(f"Tanggapan: {response.text if 'response' in locals() else 'Tidak ada tanggapan'}")
        return None, None, None
    except Exception as e:
        print(f"Kesalahan tidak dikenal: {e}")
        return None, None, None

if __name__ == "__main__":
    print("Memulai pembuatan suara...")
    voice_id, audio_data, saved_filename = create_voice_and_play()
    
    if voice_id:
        print(f"\nBerhasil membuat suara '{voice_id}'")
        print(f"File audio disimpan: '{saved_filename}'")
        print(f"Ukuran file: {os.path.getsize(saved_filename)} byte")
    else:
        print("\nPembuatan suara gagal")

Java

Anda perlu mengimpor dependensi Gson. Jika menggunakan Maven atau Gradle, tambahkan dependensi sebagai berikut:

Maven

Tambahkan berikut ke pom.xml Anda:

<!-- https://mvnrepository.com/artifact/com.google.code.gson/gson -->
<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.13.1</version>
</dependency>

Gradle

Tambahkan berikut ke build.gradle Anda:

// https://mvnrepository.com/artifact/com.google.code.gson/gson
implementation("com.google.code.gson:gson:2.13.1")

import com.google.gson.JsonObject;
import com.google.gson.JsonParser;
import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class Main {
    public static void main(String[] args) {
        Main example = new Main();
        example.createVoice();
    }

    public void createVoice() {
        // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
        // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan: String apiKey = "sk-xxx"
        String apiKey = System.getenv("DASHSCOPE_API_KEY");

        // Buat string body permintaan JSON
        String jsonBody = "{\n" +
                "    \"model\": \"voice-enrollment\",\n" +
                "    \"input\": {\n" +
                "        \"action\": \"create_voice\",\n" +
                "        \"target_model\": \"cosyvoice-v3.5-plus\",\n" +
                "        \"voice_prompt\": \"Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter.\",\n" +
                "        \"preview_text\": \"Halo para pendengar, selamat datang di berita malam ini.\",\n" +
                "        \"prefix\": \"announcer\"\n" +
                "    },\n" +
                "    \"parameters\": {\n" +
                "        \"sample_rate\": 24000,\n" +
                "        \"response_format\": \"wav\"\n" +
                "    }\n" +
                "}";

        HttpURLConnection connection = null;
        try {
            // Ini adalah URL wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
            URL url = new URL("https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization");
            connection = (HttpURLConnection) url.openConnection();

            // Atur metode dan header permintaan
            connection.setRequestMethod("POST");
            connection.setRequestProperty("Authorization", "Bearer " + apiKey);
            connection.setRequestProperty("Content-Type", "application/json");
            connection.setDoOutput(true);
            connection.setDoInput(true);

            // Kirim body permintaan
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = jsonBody.getBytes("UTF-8");
                os.write(input, 0, input.length);
                os.flush();
            }

            // Dapatkan tanggapan
            int responseCode = connection.getResponseCode();
            if (responseCode == HttpURLConnection.HTTP_OK) {
                // Baca konten tanggapan
                StringBuilder response = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getInputStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        response.append(responseLine.trim());
                    }
                }

                // Uraikan tanggapan JSON
                JsonObject jsonResponse = JsonParser.parseString(response.toString()).getAsJsonObject();
                JsonObject outputObj = jsonResponse.getAsJsonObject("output");
                JsonObject previewAudioObj = outputObj.getAsJsonObject("preview_audio");

                // Dapatkan ID suara
                String voiceId = outputObj.get("voice_id").getAsString();
                System.out.println("ID Suara: " + voiceId);

                // Dapatkan data audio dalam format Base64
                String base64Audio = previewAudioObj.get("data").getAsString();

                // Dekode data audio Base64
                byte[] audioBytes = Base64.getDecoder().decode(base64Audio);

                // Simpan audio ke file lokal
                String filename = voiceId + "_preview.wav";
                saveAudioToFile(audioBytes, filename);

                System.out.println("Audio disimpan ke file lokal: " + filename);

            } else {
                // Baca tanggapan kesalahan
                StringBuilder errorResponse = new StringBuilder();
                try (BufferedReader br = new BufferedReader(
                        new InputStreamReader(connection.getErrorStream(), "UTF-8"))) {
                    String responseLine;
                    while ((responseLine = br.readLine()) != null) {
                        errorResponse.append(responseLine.trim());
                    }
                }

                System.out.println("Permintaan gagal. Kode status: " + responseCode);
                System.out.println("Tanggapan kesalahan: " + errorResponse.toString());
            }

        } catch (Exception e) {
            System.err.println("Kesalahan permintaan: " + e.getMessage());
            e.printStackTrace();
        } finally {
            if (connection != null) {
                connection.disconnect();
            }
        }
    }

    private void saveAudioToFile(byte[] audioBytes, String filename) {
        try {
            File file = new File(filename);
            try (FileOutputStream fos = new FileOutputStream(file)) {
                fos.write(audioBytes);
            }
            System.out.println("Audio disimpan ke: " + file.getAbsolutePath());
        } catch (IOException e) {
            System.err.println("Kesalahan saat menyimpan file audio: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

Gunakan suara kustom yang dibuat pada langkah sebelumnya untuk sintesis ucapan.

Contoh ini mengacu pada contoh pemanggilan non-streaming. Anda harus mengganti parameter voice dengan ID suara kustom yang dihasilkan oleh desain suara.

Aturan utama: Model yang digunakan untuk desain suara (target_model) harus sesuai dengan model yang digunakan untuk sintesis ucapan (model). Jika tidak, sintesis gagal.

Python

# coding=utf-8

import dashscope
from dashscope.audio.tts_v2 import *
import os

# Kunci API untuk wilayah Singapura dan Beijing berbeda. Untuk mendapatkan kunci API, kunjungi: https://www.alibabacloud.com/help/en/model-studio/get-api-key
# Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan kunci API Model Studio Anda: dashscope.api_key = "sk-xxx"
dashscope.api_key = os.environ.get('DASHSCOPE_API_KEY')

# URL berikut untuk wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: wss://dashscope.aliyuncs.com/api-ws/v1/inference
dashscope.base_websocket_api_url='wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference'

# Model yang sama harus digunakan untuk desain suara dan sintesis ucapan.
model = "cosyvoice-v3.5-plus"
# Ganti parameter voice dengan suara kustom yang dihasilkan dari desain suara.
voice = "your_voice"

# Buat instance SpeechSynthesizer dan teruskan parameter permintaan seperti model dan voice ke konstruktor.
synthesizer = SpeechSynthesizer(model=model, voice=voice)
# Kirim teks yang akan disintesis untuk mendapatkan audio biner.
audio = synthesizer.call("Bagaimana cuaca hari ini?")
# Saat Anda mengirim teks untuk pertama kalinya, koneksi WebSocket perlu dibuat. Oleh karena itu, latensi paket pertama mencakup waktu pembuatan koneksi.
print('[Metric] Request ID: {}, Latensi paket pertama: {} ms'.format(
    synthesizer.get_last_request_id(),
    synthesizer.get_first_package_delay()))

# Simpan audio ke file lokal.
with open('output.mp3', 'wb') as f:
    f.write(audio)

Java

import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.utils.Constants;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.ByteBuffer;

public class Main {
    // Gunakan model yang sama untuk desain suara dan sintesis ucapan
    private static String model = "cosyvoice-v3.5-plus";
    // Ganti parameter voice dengan ID suara kustom yang dihasilkan oleh desain suara
    private static String voice = "your_voice_id";

    public static void streamAudioDataToSpeaker() {
        // Parameter permintaan
        SpeechSynthesisParam param =
                SpeechSynthesisParam.builder()
                        // Kunci API berbeda antara wilayah Singapura dan Beijing. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
                        // Jika Anda belum mengonfigurasi variabel lingkungan, ganti baris berikut dengan: .apiKey("sk-xxx")
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .model(model) // Model
                        .voice(voice) // Suara
                        .build();

        // Mode sinkron: nonaktifkan callback (parameter kedua null)
        SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, null);
        ByteBuffer audio = null;
        try {
            // Blokir hingga audio dikembalikan
            audio = synthesizer.call("Bagaimana cuaca hari ini?");
        } catch (Exception e) {
            throw new RuntimeException(e);
        } finally {
            // Tutup koneksi WebSocket setelah tugas selesai
            synthesizer.getDuplexApi().close(1000, "bye");
        }
        if (audio != null) {
            // Simpan data audio ke file lokal “output.mp3”
            File file = new File("output.mp3");
            // Penundaan paket pertama mencakup waktu penyiapan koneksi WebSocket
            System.out.println(
                    "[Metric] requestId: "
                            + synthesizer.getLastRequestId()
                            + ", penundaan paket pertama (ms): "
                            + synthesizer.getFirstPackageDelay());
            try (FileOutputStream fos = new FileOutputStream(file)) {
                fos.write(audio.array());
            } catch (IOException e) {
                throw new RuntimeException(e);
            }
        }
    }

    public static void main(String[] args) {
        // Ini adalah URL wilayah Singapura. Jika Anda menggunakan model di wilayah Beijing, ganti URL dengan: wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference
        Constants.baseWebsocketApiUrl = "wss://dashscope-intl.aliyuncs.com/api-ws/v1/inference";
        streamAudioDataToSpeaker();
        System.exit(0);
    }
}

Referensi API

Gunakan Akun Alibaba Cloud yang sama untuk semua operasi API.

Penting

SDK DashScope Java dan Python tidak mendukung desain suara. Untuk desain suara, gunakan RESTful API.

Create Voice

RESTful API

URL

China Mainland:

POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization

Internasional:

POST https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization

Header Permintaan

Parameter	Tipe	Wajib	Deskripsi
Authorization	string	Didukung	Token autentikasi. Format: `Bearer <your_api_key>`. Ganti "`<your_api_key>`" dengan kunci API aktual Anda.
Content-Type	string	Didukung	Jenis media data dalam badan permintaan. Nilai tetap: `application/json`.

Request Body

Badan permintaan berisi semua parameter. Bidang opsional dapat dihilangkan sesuai kebutuhan bisnis Anda.

Penting

Perhatikan perbedaan antara parameter berikut:

model: Model kloning/desain suara. Nilai tetap: voice-enrollment
target_model: Model sintesis ucapan yang menggerakkan suara. Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.

Kloning Suara

{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v3.5-plus",
        "prefix": "myvoice",
        "url": "https://yourAudioFileUrl",
        "language_hints": ["zh"]
    }
}

Desain Suara

{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v3.5-plus",
        "voice_prompt": "Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter.",
        "preview_text": "Halo para pendengar, selamat datang di berita malam ini.",
        "prefix": "announcer",
        "language_hints": ["zh"]
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}

Parameter Permintaan

Parameter	Tipe	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model kloning/desain suara. Nilai tetap: `voice-enrollment`.
action	string	-	Didukung	Jenis aksi. Nilai tetap: `create_voice`.
target_model	string	-	Didukung	Model sintesis ucapan yang menggerakkan suara (lihat Model yang Didukung). Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
url	string	-	Didukung	Penting Hanya wajib untuk kloning suara URL publik file audio yang digunakan untuk kloning suara. Untuk detail format audio, lihat Kloning suara: Format audio input. Untuk panduan perekaman, lihat Panduan Perekaman.
voice_prompt	string	-	Didukung	Penting Hanya wajib untuk desain suara Deskripsi suara. Panjang maksimum: 500 karakter. Hanya Bahasa Tionghoa dan Inggris. Untuk panduan menulis deskripsi suara, lihat Desain suara: Cara menulis deskripsi suara berkualitas tinggi?.
preview_text	string	-	Didukung	Penting Hanya wajib untuk desain suara Teks untuk audio pratinjau. Panjang maksimum: 200 karakter. Bahasa yang didukung: Bahasa Tionghoa (zh), Bahasa Inggris (en).
prefix	string	-	Didukung	Nama untuk suara (hanya huruf dan angka; maksimal 10 karakter). Gunakan identifikasi yang terkait dengan peran atau skenario. Kata kunci ini muncul dalam nama suara akhir. Misalnya, jika kata kuncinya "announcer", nama suara akhirnya adalah: Kloning suara: cosyvoice-v3.5-plus-announcer-8aae0c0397fa408ca60c29cf**** Desain suara: cosyvoice-v3.5-plus-vd-announcer-8aae0c0397fa408ca60c29cf****
language_hints	array[string]	["zh"]	Tidak	Anda dapat menentukan bahasa sampel audio yang digunakan untuk mengekstraksi fitur timbre target. Opsi ini hanya tersedia untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, dan cosyvoice-v3-plus. Catatan: Parameter ini berupa array, tetapi hanya elemen pertama yang diproses. Kirim hanya satu nilai. Fungsionalitas: Kloning Suara Parameter ini membantu model mengidentifikasi bahasa sampel audio (audio referensi asli), sehingga dapat mengekstraksi karakteristik suara secara lebih akurat dan meningkatkan kualitas kloning suara. Jika petunjuk bahasa yang ditentukan tidak sesuai dengan bahasa audio aktual (misalnya, menentukan `en` untuk audio Bahasa Tionghoa), sistem akan mengabaikan petunjuk ini dan mendeteksi bahasa secara otomatis berdasarkan konten audio. Nilai yang valid (berdasarkan model): cosyvoice-v3-plus: zh: Bahasa Tionghoa (bawaan) en: Bahasa Inggris fr: Bahasa Prancis de: Bahasa Jerman ja: Bahasa Jepang ko: Bahasa Korea ru: Bahasa Rusia cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Bahasa Tionghoa (bawaan) en: Bahasa Inggris fr: Bahasa Prancis de: Bahasa Jerman ja: Bahasa Jepang ko: Bahasa Korea ru: Bahasa Rusia pt: Bahasa Portugis th: Bahasa Thailand id: Bahasa Indonesia vi: Bahasa Vietnam Untuk dialek Bahasa Tionghoa (misalnya, Timur Laut, Kanton), atur `language_hints` ke `zh`. Kontrol gaya dialek dalam sintesis ucapan menggunakan konten teks atau parameter `instruct`. Desain Suara Menentukan preferensi bahasa untuk suara yang dihasilkan. Mempengaruhi fitur bahasa dan pengucapan. Pilih kode bahasa yang sesuai dengan kasus penggunaan Anda. Jika digunakan, bahasa harus sesuai dengan bahasa `preview_text`. Nilai yang valid: zh: Bahasa Tionghoa (bawaan) en: Bahasa Inggris
max_prompt_audio_length	float	10.0	Tidak	Penting Hanya tersedia untuk kloning suara Durasi maksimum (dalam detik) audio referensi yang digunakan untuk kloning suara setelah pra-pemrosesan. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, dan cosyvoice-v3-flash. Rentang valid: [3.0, 30.0].
enable_preprocess	boolean	false	Tidak	Penting Hanya tersedia untuk kloning suara Aktifkan pra-pemrosesan audio. Saat diaktifkan, sistem menerapkan pengurangan noise, peningkatan audio, dan normalisasi volume sebelum kloning. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, dan cosyvoice-v3-flash. Nilai yang valid: true: Aktifkan false: Nonaktifkan
sample_rate	int	24000	Tidak	Penting Hanya tersedia untuk desain suara Laju sampel (Hz) audio pratinjau yang dihasilkan oleh desain suara. Nilai yang valid: 16000 24000 48000
response_format	string	wav	Tidak	Penting Hanya tersedia untuk desain suara Format audio pratinjau yang dihasilkan oleh desain suara. Nilai yang valid: pcm wav mp3

Parameter Tanggapan

Lihat contoh tanggapan

Kloning Suara

{
    "output": {
        "voice_id": "yourVoiceId"
    },
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Desain Suara

{
    "output": {
        "preview_audio": {
            "data": "{base64_encoded_audio}",
            "sample_rate": 24000,
            "response_format": "wav"
        },
        "target_model": "cosyvoice-v3.5-plus",
        "voice_id": "yourVoice"
    },
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Parameter utama:

Parameter	Type	Deskripsi
voice_id	string	ID Suara. Gunakan langsung sebagai parameter `voice` dalam API sintesis ucapan.
data	string	Data audio pratinjau yang dihasilkan oleh desain suara, dikembalikan sebagai string terenkripsi Base64.
sample_rate	int	Laju sampel (Hz) audio pratinjau yang dihasilkan oleh desain suara. Sesuai dengan laju sampel yang digunakan saat membuat suara. Bawaan: 24000 Hz jika tidak ditentukan.
response_format	string	Format audio pratinjau yang dihasilkan oleh desain suara. Sesuai dengan format yang digunakan saat membuat suara. Bawaan: wav jika tidak ditentukan.
target_model	string	Model sintesis ucapan yang menggerakkan suara (lihat Model yang Didukung). Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
request_id	string	ID Permintaan.
count	integer	Jumlah operasi "buat suara" dalam permintaan ini. Selalu 1 untuk pembuatan suara.

Kode Contoh

Penting

Perhatikan perbedaan antara parameter berikut:

model: Model kloning/desain suara. Nilai tetap: voice-enrollment
target_model: Model sintesis ucapan yang menggerakkan suara. Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.

Kloning Suara

Jika Anda belum mengonfigurasi kunci API Anda dalam variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan kunci API aktual Anda.

https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization<a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="28f184e9f7vq7">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization</a># ======= Pemberitahuan Penting =======
# Berikut adalah URL untuk wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===

curl -X POST <a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="28f184e9f7vq7">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization</a> \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v3.5-plus",
        "prefix": "myvoice",
        "url": "https://yourAudioFileUrl"
    }
}'

Desain Suara

Jika Anda belum mengonfigurasi kunci API Anda dalam variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan kunci API aktual Anda.

https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization<a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="087ab4e9d2b9r">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization</a># ======= Pemberitahuan Penting =======
# Berikut adalah URL untuk wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===

curl -X POST <a data-init-id="9f104f338c7kz" href="https://poc-dashscope.aliyuncs.com/api/v1/services/audio/tts/customization" id="087ab4e9d2b9r">https://dashscope-intl.aliyuncs.com/api/v1/services/audio/tts/customization</a> \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v3.5-plus",
        "voice_prompt": "Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter.",
        "preview_text": "Halo para pendengar, selamat datang di berita malam ini.",
        "prefix": "announcer"
    },
    "parameters": {
        "sample_rate": 24000,
        "response_format": "wav"
    }
}'

SDK Python

Deskripsi Antarmuka

Sebelum menggunakan antarmuka ini, instal SDK DashScope terbaru.

def create_voice(self, target_model: str, prefix: str, url: str, language_hints: List[str] = None) -> str:
    '''
    Buat suara kustom baru.
    param: target_model Model sintesis ucapan yang menggerakkan suara. Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
    param: prefix Nama untuk suara (hanya huruf, angka, dan garis bawah; maksimal 10 karakter). Gunakan identifikasi yang terkait dengan peran atau skenario. Kata kunci ini muncul dalam nama suara hasil kloning. Format: model-name-prefix-unique-id, misalnya, cosyvoice-v3-plus-myvoice-xxxxxxxx.
    param: url URL publik file audio yang digunakan untuk kloning suara.
    param: language_hints Bahasa audio referensi yang digunakan untuk mengekstraksi fitur suara. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, dan cosyvoice-v3-plus.
                Membantu model mengidentifikasi bahasa audio referensi (sampel asli), meningkatkan ekstraksi fitur suara dan kualitas kloning.
                Jika petunjuk bahasa tidak sesuai dengan audio aktual (misalnya, "en" untuk audio Bahasa Tionghoa), sistem mengabaikan petunjuk tersebut dan mendeteksi bahasa secara otomatis.
                Nilai yang valid (berdasarkan model):
                    cosyvoice-v3-plus: zh (bawaan), en, fr, de, ja, ko, ru.
                    cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh (bawaan), en, fr, de, ja, ko, ru, pt, th, id, vi.
                Parameter ini berupa array, tetapi hanya elemen pertama yang diproses. Kirim hanya satu nilai.
    param: max_prompt_audio_length Durasi maksimum (dalam detik) audio referensi yang digunakan untuk kloning suara setelah pra-pemrosesan. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, dan cosyvoice-v3-flash.
                Rentang valid: [3.0, 30.0].
    param: enable_preprocess Aktifkan pra-pemrosesan audio. Saat diaktifkan, sistem menerapkan pengurangan noise, peningkatan audio, dan normalisasi volume sebelum kloning. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, dan cosyvoice-v3-flash.
    return: voice_id ID Suara. Gunakan langsung sebagai parameter voice dalam API sintesis ucapan.
    '''

Penting

target_model: Model sintesis ucapan yang menggerakkan suara. Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
language_hints: Bahasa audio referensi yang digunakan untuk mengekstraksi fitur suara. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, dan cosyvoice-v3-plus.
Fungsionalitas:
Kloning Suara
Parameter ini membantu model mengidentifikasi bahasa sampel audio (audio referensi asli), sehingga dapat mengekstraksi karakteristik suara secara lebih akurat dan meningkatkan kualitas kloning suara. Jika petunjuk bahasa yang ditentukan tidak sesuai dengan bahasa audio aktual (misalnya, menentukan en untuk audio Bahasa Tionghoa), sistem akan mengabaikan petunjuk ini dan mendeteksi bahasa secara otomatis berdasarkan konten audio.
Nilai yang valid (berdasarkan model):
- cosyvoice-v3-plus:
  zh: Bahasa Tionghoa (bawaan)
  en: Bahasa Inggris
  fr: Bahasa Prancis
  de: Bahasa Jerman
  ja: Bahasa Jepang
  ko: Bahasa Korea
  ru: Bahasa Rusia
- cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash:
  zh: Bahasa Tionghoa (bawaan)
  en: Bahasa Inggris
  fr: Bahasa Prancis
  de: Bahasa Jerman
  ja: Bahasa Jepang
  ko: Bahasa Korea
  ru: Bahasa Rusia
  pt: Bahasa Portugis
  th: Bahasa Thailand
  id: Bahasa Indonesia
  vi: Bahasa Vietnam
Untuk dialek Bahasa Tionghoa (misalnya, Timur Laut, Kanton), atur language_hints ke zh. Kontrol gaya dialek dalam sintesis ucapan menggunakan konten teks atau parameter instruct.
Desain Suara
Menentukan preferensi bahasa untuk suara yang dihasilkan. Mempengaruhi fitur bahasa dan pengucapan. Pilih kode bahasa yang sesuai dengan kasus penggunaan Anda.
Jika digunakan, bahasa harus sesuai dengan bahasa preview_text.
Nilai yang valid:
- zh: Bahasa Tionghoa (bawaan)
- en: Bahasa Inggris

Contoh Permintaan

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

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

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

SDK Java

Deskripsi Antarmuka

Sebelum menggunakan antarmuka ini, instal SDK DashScope terbaru.

/**
 * Buat suara kustom baru.
 *
 * @param targetModel Model sintesis ucapan yang menggerakkan suara. Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
 * @param prefix Nama untuk suara (hanya huruf, angka, dan garis bawah; maksimal 10 karakter). Gunakan identifikasi yang terkait dengan peran atau skenario. Kata kunci ini muncul dalam nama suara hasil kloning. Format: model-name-prefix-unique-id, misalnya, cosyvoice-v3-plus-myvoice-xxxxxxxx.
 * @param url URL publik file audio yang digunakan untuk kloning suara.
 * @param customParam Parameter kustom. Tentukan languageHints dan maxPromptAudioLength di sini.
 *              languageHints: Bahasa audio referensi yang digunakan untuk mengekstraksi fitur suara. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, dan cosyvoice-v3-plus.
 *                  Membantu model mengidentifikasi bahasa audio referensi (sampel asli), meningkatkan ekstraksi fitur suara dan kualitas kloning.
 *                  Jika petunjuk bahasa tidak sesuai dengan audio aktual (misalnya, "en" untuk audio Bahasa Tionghoa), sistem mengabaikan petunjuk tersebut dan mendeteksi bahasa secara otomatis.
 *                  Nilai yang valid (berdasarkan model):
 *                      cosyvoice-v3-plus: zh (bawaan), en, fr, de, ja, ko, ru.
 *                      cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh (bawaan), en, fr, de, ja, ko, ru, pt, th, id, vi.
 *                  Hanya elemen pertama yang diproses. Kirim hanya satu nilai.
 *              maxPromptAudioLength: Durasi maksimum (dalam detik) audio referensi yang digunakan untuk kloning suara setelah pra-pemrosesan. Hanya berlaku untuk model cosyvoice-v3-flash.
 *                  Rentang valid: [3.0, 30.0].
 *              enable_preprocess: Konfigurasikan parameter ini menggunakan parameter generik "parameter". Aktifkan pra-pemrosesan audio. Saat diaktifkan, sistem menerapkan pengurangan noise, peningkatan audio, dan normalisasi volume sebelum kloning. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, dan cosyvoice-v3-flash.
 * @return Voice Suara baru. Panggil Voice.getVoiceId() untuk mendapatkan ID suara. Gunakan langsung sebagai parameter voice dalam API sintesis ucapan.
 * @throws NoApiKeyException Jika kunci API kosong.
 * @throws InputRequiredException Jika parameter wajib kosong.
 */
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Penting

targetModel: Model sintesis ucapan yang menggerakkan suara. Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
languageHints: Bahasa audio referensi yang digunakan untuk mengekstraksi fitur suara. Hanya berlaku untuk model cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, dan cosyvoice-v3-plus.
Fungsionalitas:
Kloning Suara
Parameter ini membantu model mengidentifikasi bahasa sampel audio (audio referensi asli), sehingga dapat mengekstraksi karakteristik suara secara lebih akurat dan meningkatkan kualitas kloning suara. Jika petunjuk bahasa yang ditentukan tidak sesuai dengan bahasa audio aktual (misalnya, menentukan en untuk audio Bahasa Tionghoa), sistem akan mengabaikan petunjuk ini dan mendeteksi bahasa secara otomatis berdasarkan konten audio.
Nilai yang valid (berdasarkan model):
- cosyvoice-v3-plus:
  zh: Bahasa Tionghoa (bawaan)
  en: Bahasa Inggris
  fr: Bahasa Prancis
  de: Bahasa Jerman
  ja: Bahasa Jepang
  ko: Bahasa Korea
  ru: Bahasa Rusia
- cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash:
  zh: Bahasa Tionghoa (bawaan)
  en: Bahasa Inggris
  fr: Bahasa Prancis
  de: Bahasa Jerman
  ja: Bahasa Jepang
  ko: Bahasa Korea
  ru: Bahasa Rusia
  pt: Bahasa Portugis
  th: Bahasa Thailand
  id: Bahasa Indonesia
  vi: Bahasa Vietnam
Untuk dialek Bahasa Tionghoa (misalnya, Timur Laut, Kanton), atur language_hints ke zh. Kontrol gaya dialek dalam sintesis ucapan menggunakan konten teks atau parameter instruct.
Desain Suara
Menentukan preferensi bahasa untuk suara yang dihasilkan. Mempengaruhi fitur bahasa dan pengucapan. Pilih kode bahasa yang sesuai dengan kasus penggunaan Anda.
Jika digunakan, bahasa harus sesuai dengan bahasa preview_text.
Nilai yang valid:
- zh: Bahasa Tionghoa (bawaan)
- en: Bahasa Inggris

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.5-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("zh"))
                            // .maxPromptAudioLength(10.0f)
                            // .parameter("enable_preprocess", false)
                            .build());

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

List Voices

Kueri daftar suara yang telah dibuat dengan pagination.

RESTful API

URL dan Header Permintaan sama dengan API Create Voice
Request Body
Badan permintaan berisi semua parameter. Bidang opsional dapat dihilangkan sesuai kebutuhan bisnis Anda.
Penting
model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.
```
{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "announcer"
        "page_size": 10,
        "page_index": 0
    }
}
```

Parameter Permintaan

Parameter	Tipe	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model kloning/desain suara. Nilai tetap: `voice-enrollment`.
action	string	-	Didukung	Jenis aksi. Nilai tetap: `list_voice`.
prefix	string	-	Tidak	Awalan yang sama digunakan saat membuat suara. Hanya huruf dan angka; maksimal 10 karakter.
page_index	integer	0	Tidak didukung	Indeks halaman. Harus lebih besar dari atau sama dengan 0.
page_size	integer	10	Tidak	Jumlah item per halaman. Rentang valid: [0, 1000].

Parameter Tanggapan

Lihat contoh tanggapan

Kloning Suara

{
    "output": {
        "voice_list": [
            {
                "gmt_create": "2024-12-11 13:38:02",
                "voice_id": "yourVoiceId",
                "gmt_modified": "2024-12-11 13:38:02",
                "status": "OK"
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Desain Suara

{
    "output": {
        "voice_list": [
            {
                "gmt_create": "2025-12-10 17:04:54",
                "gmt_modified": "2025-12-10 17:04:54",
                "preview_text": "Halo para pendengar, selamat datang di acara hari ini.",
                "target_model": "cosyvoice-v3.5-plus",
                "voice_id": "yourVoice1",
                "status": "OK",
                "voice_prompt": "Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter., dalam dan magnetis, kecepatan stabil"
            },
            {
                "gmt_create": "2025-12-10 15:31:35",
                "gmt_modified": "2025-12-10 15:31:35",
                "language": "zh",
                "preview_text": "Halo para pendengar, selamat datang",
                "target_model": "cosyvoice-v3.5-plus",
                "voice_id": "yourVoice2",
                "status": "OK"
                "voice_prompt": "Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter."
            }
        ]
    },
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Parameter utama:

Parameter	Tipe	Deskripsi
voice_id	string	ID Suara. Gunakan langsung sebagai parameter `voice` dalam API sintesis ucapan.
target_model	string	Model sintesis ucapan yang menggerakkan suara (lihat Model yang Didukung). Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
gmt_create	string	Waktu suara dibuat.
gmt_modified	string	Waktu timbre dimodifikasi.
voice_prompt	string	Deskripsi suara.
preview_text	string	Teks pratinjau.
request_id	string	ID Permintaan.
status	string	Status suara: DEPLOYING: Sedang ditinjau OK: Disetujui dan siap digunakan UNDEPLOYED: Ditolak dan tidak tersedia

Kode Contoh

Penting

model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.

Jika Anda belum mengonfigurasi kunci API Anda dalam variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan kunci API aktual Anda.

# ======= Pemberitahuan Penting =======
# Berikut adalah URL untuk wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===

curl -X POST https://dashscope.aliyuncs-intl.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "announcer",
        "page_size": 10,
        "page_index": 0
    }
}'

SDK Python

Deskripsi Antarmuka

def list_voices(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
    '''
    Kueri semua suara yang telah dibuat
    param: prefix Awalan kustom untuk suara (hanya huruf dan huruf kecil; kurang dari 10 karakter).
    param: page_index Indeks halaman untuk dikueri
    param: page_size Ukuran halaman untuk dikueri
    return: List[dict] Daftar suara yang berisi ID, waktu pembuatan, waktu modifikasi, dan status untuk 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'}]
    Status suara:
        DEPLOYING: Sedang ditinjau
        OK: Disetujui dan siap digunakan
        UNDEPLOYED: Ditolak dan tidak tersedia
    '''

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"ID Permintaan: {service.get_last_request_id()}")
print(f"Suara yang ditemukan: {voices}")

Contoh Tanggapan

[
    {
        "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 Tanggapan

Parameter	Tipe	Deskripsi
voice_id	string	ID Suara. Gunakan langsung sebagai parameter `voice` dalam API sintesis ucapan.
target_model	string	Model sintesis ucapan yang menggerakkan suara (lihat Model yang Didukung). Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
gmt_create	string	Waktu suara dibuat.
gmt_modified	string	Waktu timbre dimodifikasi.
voice_prompt	string	Deskripsi suara.
preview_text	string	Teks pratinjau.
request_id	string	ID Permintaan.
status	string	Status suara: DEPLOYING: Sedang ditinjau OK: Disetujui dan siap digunakan UNDEPLOYED: Ditolak dan tidak tersedia

SDK Java

Deskripsi Antarmuka

// Status suara:
//        DEPLOYING: Sedang ditinjau
//        OK: Disetujui dan siap digunakan
//        UNDEPLOYED: Ditolak dan tidak tersedia
/**
 * Kueri semua suara yang telah dibuat. Indeks halaman bawaan adalah 0, ukuran halaman bawaan adalah 10.
 *
 * @param prefix Awalan kustom untuk suara (hanya huruf dan huruf kecil; kurang dari 10 karakter). Bisa null.
 * @return Voice[] Array objek Voice. Voice merangkum ID, waktu pembuatan, waktu modifikasi, dan status suara.
 * @throws NoApiKeyException Jika kunci API kosong.
 * @throws InputRequiredException Jika parameter wajib kosong.
 */
public Voice[] listVoice(String prefix) throws NoApiKeyException, InputRequiredException 

/**
 * Kueri semua suara yang telah dibuat.
 *
 * @param prefix Awalan kustom untuk suara (hanya huruf dan huruf kecil; kurang dari 10 karakter).
 * @param pageIndex Indeks halaman untuk dikueri.
 * @param pageSize Ukuran halaman untuk dikueri.
 * @return Voice[] Array objek Voice. Voice merangkum ID, waktu pembuatan, waktu modifikasi, dan status suara.
 * @throws NoApiKeyException Jika kunci API kosong.
 * @throws InputRequiredException Jika parameter wajib kosong.
 */
public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Contoh Permintaan

Anda perlu 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 mengatur variabel lingkungan, ganti ini dengan kunci API Anda
    private static String prefix = "myvoice"; // Ganti 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. ID Permintaan: {}", service.getLastRequestId());
        logger.info("Detail Suara: {}", new Gson().toJson(voices));
    }
}

Contoh Tanggapan

[
    {
        "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 Tanggapan

Parameter	Tipe	Deskripsi
voice_id	string	ID Suara. Gunakan langsung sebagai parameter `voice` dalam API sintesis ucapan.
target_model	string	Model sintesis ucapan yang menggerakkan suara (lihat Model yang Didukung). Harus sesuai dengan model sintesis ucapan yang digunakan nanti. Jika tidak, sintesis gagal.
gmt_create	string	Waktu suara dibuat.
gmt_modified	string	Waktu timbre dimodifikasi.
voice_prompt	string	Deskripsi suara.
preview_text	string	Teks pratinjau.
request_id	string	ID Permintaan.
status	string	Status suara: DEPLOYING: Sedang ditinjau OK: Disetujui dan siap digunakan UNDEPLOYED: Ditolak dan tidak tersedia

Query Specific Voice

Anda dapat mengambil informasi detail tentang suara tertentu berdasarkan namanya.

RESTful API

URL dan Header Permintaan sama dengan API Create Voice
Isi Permintaan
Badan permintaan berisi semua parameter. Bidang opsional dapat dihilangkan sesuai kebutuhan bisnis Anda.
Penting
model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.
```
{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceID"
    }
}
```

Parameter Permintaan

Parameter	Tipe	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model kloning/desain suara. Nilai tetap: `voice-enrollment`.
action	string	-	Didukung	Jenis aksi. Nilai tetap: `query_voice`.
voice_id	string	-	Didukung	ID suara yang akan dikueri.

Parameter Tanggapan

Lihat contoh tanggapan

Kloning Suara

{
    "output": {
        "gmt_create": "2024-12-11 13:38:02",
        "resource_link": "https://yourAudioFileUrl",
        "target_model": "cosyvoice-v3.5-plus",
        "gmt_modified": "2024-12-11 13:38:02",
        "status": "OK"
    },
    "usage": {
        "count": 1
    },
    "request_id": "2450f969-d9ea-9483-bafc-************"
}

Desain Suara

{
    "output": {
        "gmt_create": "2025-12-10 14:54:09",
        "gmt_modified": "2025-12-10 17:47:48",
        "preview_text": "Halo para pendengar, selamat datang",
        "target_model": "cosyvoice-v3.5-plus",
        "status": "OK",
        "voice_id": "yourVoice",
        "voice_prompt": "Seorang penyiar pria paruh baya yang tenang dengan suara dalam, kaya, dan magnetis, kecepatan bicara stabil, dan artikulasi jelas, cocok untuk siaran berita atau narasi dokumenter."
    },
    "usage": {},
    "request_id": "yourRequestId"
}

Untuk deskripsi parameter, lihat API List Voices.

Kode Contoh

Penting

model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.

Jika Anda belum mengonfigurasi kunci API Anda dalam variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan kunci API aktual Anda.

# ======= Pemberitahuan Penting =======
# Berikut adalah URL untuk wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===

curl -X POST https://dashscope.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": "query_voice",
        "voice_id": "yourVoiceID"
    }
}'

SDK Python

Deskripsi Antarmuka

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

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"ID Permintaan: {service.get_last_request_id()}")
print(f"Detail Suara: {voice_details}")

Contoh Tanggapan

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

Parameter Tanggapan

Lihat API .

SDK Java

Deskripsi Antarmuka

/**
 * Kueri detail untuk suara tertentu
 *
 * @param voiceId ID suara yang akan dikueri
 * @return Voice Detail suara, termasuk status, waktu pembuatan, tautan audio, dll.
 * @throws NoApiKeyException Jika kunci API kosong
 * @throws InputRequiredException Jika parameter wajib kosong
 */
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Contoh Permintaan

Anda perlu 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 mengatur variabel lingkungan, ganti ini dengan kunci API Anda
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Ganti 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. ID Permintaan: {}", service.getLastRequestId());
        logger.info("Detail Suara: {}", new Gson().toJson(voice));
    }
}

Contoh Tanggapan

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

Parameter Tanggapan

Lihat API .

Update Voice (Hanya untuk Kloning Suara)

Perbarui suara yang ada dengan file audio baru.

Penting

Fitur ini tidak didukung untuk desain suara.

RESTful API

URL dan Header Permintaan sama dengan API Create Voice
Request Body
Badan permintaan berisi semua parameter. Bidang opsional dapat dihilangkan sesuai kebutuhan bisnis Anda:
Penting
model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.
```
{
    "model": "voice-enrollment",
    "input": {
        "action": "update_voice",
        "voice_id": "yourVoiceId",
        "url": "https://yourAudioFileUrl"
    }
}
```

Parameter Permintaan

Parameter	Jenis	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model kloning/desain suara. Nilai tetap: `voice-enrollment`.
action	string	-	Didukung	Jenis aksi. Nilai tetap: `update_voice`.
voice_id	string	-	Didukung	Suara yang akan diperbarui.
url	string	-	Didukung	URL file audio untuk memperbarui suara. URL harus dapat diakses publik.

Parameter Tanggapan

Lihat contoh tanggapan

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Kode Contoh

Penting

model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.

Jika Anda belum mengonfigurasi kunci API Anda dalam variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan kunci API aktual Anda.

# ======= Pemberitahuan Penting =======
# Berikut adalah URL untuk wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===

curl -X POST https://dashscope-intl.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": "update_voice",
        "voice_id": "yourVoiceId",
        "url": "https://yourAudioFileUrl"
    }
}'

SDK Python

Deskripsi Antarmuka

def update_voice(self, voice_id: str, url: str) -> None:
    '''
    Perbarui 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. ID Permintaan: {service.get_last_request_id()}")

SDK Java

Deskripsi Antarmuka

/**
 * Perbarui 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 wajib 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 mengatur variabel lingkungan, ganti ini dengan kunci API Anda
    private static String fileUrl = "https://your-audio-file-url";  // Ganti dengan nilai aktual Anda
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Ganti 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. ID Permintaan: {}", service.getLastRequestId());
    }
}

Delete Voice

Hapus suara yang tidak lagi Anda butuhkan untuk mengosongkan kuota Anda. Tindakan ini tidak dapat dikembalikan.

RESTful API

URL dan Header Permintaan sama dengan API Create Voice
Request Body
Badan permintaan berisi semua parameter. Bidang opsional dapat dihilangkan sesuai kebutuhan bisnis Anda:
Penting
model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.
```
{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceID"
    }
}
```

Parameter Permintaan

Parameter	Type	Bawaan	Wajib	Deskripsi
model	string	-	Didukung	Model kloning/desain suara. Nilai tetap: `voice-enrollment`.
action	string	-	Didukung	Jenis aksi. Nilai tetap: `delete_voice`.
voice_id	string	-	Didukung	Suara yang akan dihapus.

Parameter Tanggapan

Lihat contoh tanggapan

{
    "output": {},
    "usage": {
        "count": 1
    },
    "request_id": "yourRequestId"
}

Kode Contoh

Penting

model: Model kloning/desain suara. Nilai tetap: voice-enrollment. Jangan ubah.

Jika Anda belum mengonfigurasi kunci API Anda dalam variabel lingkungan, ganti $DASHSCOPE_API_KEY dalam contoh dengan kunci API aktual Anda.

# ======= Pemberitahuan Penting =======
# Berikut adalah URL untuk wilayah Singapura. Jika Anda menggunakan model wilayah Beijing, ganti URL dengan: https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
# Kunci API untuk wilayah Singapura dan Beijing berbeda. Dapatkan kunci API Anda: https://www.alibabacloud.com/help/zh/model-studio/get-api-key
# === Hapus komentar ini sebelum menjalankan ===

curl -X POST https://dashscope-intl.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": "delete_voice",
        "voice_id": "yourVoiceID"
    }
}'

SDK Python

Deskripsi Antarmuka

def delete_voice(self, voice_id: str) -> None:
    '''
    Hapus 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. ID Permintaan: {service.get_last_request_id()}")

SDK Java

Deskripsi Antarmuka

/**
 * Hapus suara
 *
 * @param voiceId Suara yang akan dihapus
 * @throws NoApiKeyException Jika kunci API kosong
 * @throws InputRequiredException Jika parameter wajib 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 mengatur variabel lingkungan, ganti ini dengan kunci API Anda
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Ganti 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. ID Permintaan: {}", service.getLastRequestId());
    }
}

Kuota Suara dan Aturan Pembersihan Otomatis

Batas total: 1.000 suara
API saat ini tidak menyediakan cara untuk mengkueri jumlah suara. Anda dapat memanggil API untuk menghitung suara sendiri.
Pembersihan otomatis: Jika suara tidak digunakan untuk permintaan sintesis ucapan apa pun dalam satu tahun terakhir, sistem akan menghapusnya secara otomatis.

Penagihan

Kloning/desain suara: Membuat, mengkueri, memperbarui, dan menghapus suara gratis.
Sintesis ucapan menggunakan suara kustom: Ditagih berdasarkan jumlah karakter teks. Untuk informasi lebih lanjut, lihat Sintesis Ucapan Real-time – CosyVoice/Sambert.

Hak Cipta dan Legalitas

Anda bertanggung jawab atas kepemilikan dan hak hukum untuk menggunakan suara apa pun yang Anda berikan. Baca Ketentuan Layanan.

Kode Kesalahan

Jika Anda mengalami kesalahan, lihat Pesan Kesalahan untuk troubleshooting.

FAQ

Fitur

T: Bagaimana cara menyesuaikan kecepatan dan volume suara kustom?

Sesuaikan dengan cara yang sama seperti menyesuaikan suara preset. Teruskan parameter yang sesuai saat memanggil API sintesis ucapan. Misalnya, gunakan speech_rate (Python) atau speechRate (Java) untuk menyesuaikan kecepatan, dan volume untuk menyesuaikan volume. Untuk informasi lebih lanjut, lihat dokumentasi API sintesis ucapan (SDK Java/SDK Python/API WebSocket).

T: Bagaimana cara memanggil API menggunakan bahasa selain Java dan Python (seperti Go, C#, atau Node.js)?

Untuk manajemen suara, gunakan RESTful API yang disediakan dalam dokumen ini. Untuk sintesis ucapan, gunakan API WebSocket dan teruskan voice_id hasil kloning sebagai parameter voice.

Troubleshooting

Jika Anda mengalami kesalahan kode, lakukan troubleshooting menggunakan informasi di Kode Kesalahan.

T: Apa yang harus saya lakukan jika audio hasil sintesis dari suara hasil kloning berisi konten tambahan?

Jika Anda menemukan karakter tambahan atau noise dalam audio hasil sintesis dari suara hasil kloning, ikuti langkah-langkah berikut untuk troubleshooting:

Periksa kualitas audio sumber
Kualitas audio hasil kloning secara langsung memengaruhi hasil sintesis. Pastikan audio sumber memenuhi persyaratan berikut:
- Tidak ada noise latar atau statis
- Kualitas suara jernih (laju sampel ≥ 16 kHz direkomendasikan)
- Format audio: WAV lebih baik daripada MP3 (hindari kompresi lossy)
- Mono (stereo dapat menyebabkan gangguan)
- Tidak ada segmen diam atau jeda panjang
- Kecepatan bicara sedang (kecepatan cepat memengaruhi ekstraksi fitur)
Periksa teks input
Konfirmasi bahwa teks input tidak mengandung simbol atau penanda khusus:
- Hindari simbol khusus seperti **, "", dan ''
- Kecuali digunakan untuk formula LaTeX, pra-pemrosesan teks untuk menyaring simbol khusus.
Verifikasi parameter kloning suara
Pastikan parameter bahasa (language_hints/languageHints) diatur dengan benar saat .
Coba kloning lagi
Gunakan file audio sumber berkualitas lebih tinggi untuk mengkloning suara lagi dan uji hasilnya.
Bandingkan dengan suara sistem
Uji teks yang sama dengan suara sistem preset untuk mengonfirmasi apakah masalah tersebut spesifik pada suara hasil kloning.

T: Bagaimana cara melakukan troubleshooting jika audio yang dihasilkan dari suara hasil kloning diam?

Periksa Status Suara
Panggil API Query Specific Voice untuk memeriksa apakah status suara adalah OK.
Periksa konsistensi versi model
Pastikan parameter target_model yang digunakan untuk kloning suara persis sama dengan parameter model yang digunakan untuk sintesis ucapan. Misalnya:
- Saat Anda mengkloning repositori, gunakan cosyvoice-v3-plus.
- Anda juga harus menggunakan cosyvoice-v3-plus untuk sintesis
Verifikasi kualitas audio sumber
Periksa apakah audio sumber yang digunakan untuk kloning memenuhi persyaratan format input kloning suara:
- Durasi audio: 10–20 detik
- Kualitas suara jernih
- Tidak ada noise latar
Periksa parameter permintaan
Konfirmasi bahwa parameter voice diatur ke ID suara hasil kloning selama sintesis ucapan.

T: Apa yang harus saya lakukan jika ucapan hasil sintesis dari suara hasil kloning tidak stabil atau tidak lengkap?

Jika ucapan hasil sintesis dari suara hasil kloning memiliki masalah berikut:

Pemutaran tidak lengkap; hanya bagian teks yang dibaca
Kualitas sintesis tidak stabil; kadang bagus, kadang buruk
Jeda abnormal atau segmen diam dalam audio

Kemungkinan penyebab: Kualitas audio sumber tidak memenuhi persyaratan.

Solusi: Periksa apakah audio sumber memenuhi persyaratan berikut. Rekam ulang audio mengikuti Panduan Perekaman.

Periksa kontinuitas audio: Pastikan ucapan dalam audio sumber bersambung. Hindari jeda panjang atau segmen diam (lebih dari 2 detik). Segmen kosong yang jelas dapat menyebabkan model menganggap diam atau noise sebagai bagian dari fitur suara, memengaruhi hasil.
Periksa rasio aktivitas ucapan: Pastikan ucapan aktif mencakup lebih dari 60% dari total durasi audio. Noise latar atau segmen non-ucapan yang terlalu banyak akan mengganggu ekstraksi fitur suara.
Verifikasi detail kualitas audio:
- Durasi audio: 10–20 detik (15 detik direkomendasikan)
- Pengucapan jelas dan kecepatan bicara stabil
- Tidak ada noise latar, gema, atau statis
- Energi ucapan terkonsentrasi tanpa segmen diam panjang

T: Mengapa saya tidak dapat menemukan kelas VoiceEnrollmentService?

Versi SDK Anda terlalu lama. Instal SDK terbaru.

T: Apa yang harus saya lakukan jika hasil kloning suara buruk, dengan noise atau audio tidak jelas?

Ini biasanya karena kualitas input audio rendah. Rekam ulang dan unggah audio, ikuti secara ketat Panduan Perekaman.

T: Mengapa ada diam panjang di awal atau durasi total abnormal saat saya mensintesis teks sangat pendek (seperti satu kata) dengan suara hasil kloning?

Model kloning suara mempelajari jeda dan ritme dari sampel audio. Jika rekaman asli memiliki diam awal yang panjang atau jeda, hasil sintesis mungkin mempertahankan pola serupa. Untuk teks tunggal atau teks sangat pendek, rasio diam ini diperbesar, sehingga tampak seperti "audio panjang tetapi sebagian besar diam." Hindari diam panjang saat merekam sampel audio. Gunakan kalimat lengkap atau teks lebih panjang untuk sintesis. Jika Anda harus mensintesis satu kata, tambahkan konteks sebelum atau sesudahnya, atau gunakan homofon untuk menghindari kasus ekstrem.