Alibaba Cloud Model Studio:CosyVoice voice cloning API

API description

def create_voice(self, target_model: str, prefix: str, url: str, language_hints: List[str] = None) -> str:
    '''
    Creates a new custom voice.
    param: target_model The speech synthesis model that drives the voice. This must be the same as the speech synthesis model used when you later call the speech synthesis API. Otherwise, synthesis will fail. Recommended models are cosyvoice-v3-flash or cosyvoice-v3-plus.
    param: prefix A user-friendly name for the voice (only digits, uppercase and lowercase letters, and underscores are allowed, up to 10 characters). Use an identifier related to the role or scenario. This keyword appears in the cloned voice name. The generated voice name format is: model_name-prefix-unique_identifier, for example, cosyvoice-v3-plus-myvoice-xxxxxxxx.
    param: url The URL of the audio file for voice cloning. The URL must be publicly accessible.
    param: language_hints Specifies the target language to help improve synthesis accuracy. This parameter is effective for English, French, German, Japanese, Korean, and Russian (Chinese does not need to be specified). Currently, only one language can be selected. Valid values: en, fr, de, ja, ko, ru.
    return: voice_id The voice ID. It can be directly used for the voice parameter in the speech synthesis API.
    '''

Request example

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

# Avoid frequent calls. Each call creates a new voice. You cannot create more voices after you reach the quota limit.
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"Voice ID: {voice_id}")

API description

/**
 * Creates a new custom voice.
 *
 * @param targetModel The speech synthesis model that drives the voice. This must be the same as the speech synthesis model used when you later call the speech synthesis API. Otherwise, synthesis will fail. Recommended models are cosyvoice-v3-flash or cosyvoice-v3-plus.
 * @param prefix A user-friendly name for the voice (only digits, uppercase and lowercase letters, and underscores are allowed, up to 10 characters). Use an identifier related to the role or scenario. This keyword appears in the cloned voice name. The generated voice name format is: model_name-prefix-unique_identifier, for example, cosyvoice-v3-plus-myvoice-xxxxxxxx.
 * @param url The URL of the audio file for voice cloning. The URL must be publicly accessible.
 * @param customParam Custom parameters. You can specify the target language (languageHints) here to help improve synthesis accuracy. This parameter is effective for English, French, German, Japanese, Korean, and Russian (Chinese does not need to be specified). Currently, only one language can be selected. Valid values: en, fr, de, ja, ko, ru.
 * @return Voice The newly created voice. You can get the voice ID using the getVoiceId method of the Voice object. The ID can be directly used for the voice parameter in the speech synthesis API.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Voice createVoice(String targetModel, String prefix, String url, VoiceEnrollmentParam customParam) throws NoApiKeyException, InputRequiredException

Request example

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("Voice creation submitted. Request ID: {}", service.getLastRequestId());
            logger.info("Generated Voice ID: {}", myVoice.getVoiceId());
        } catch (Exception e) {
            logger.error("Failed to create voice", e);
        }
    }
}

API description

def list_voices(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
    '''
    Queries all created voices.
    param: prefix The custom prefix for the voice. Only digits and lowercase letters are allowed, up to 10 characters.
    param: page_index The page index for the query.
    param: page_size The page size for the query.
    return: List[dict] A list of voices. It includes the ID, creation time, modification time, and status of each voice. 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'}]
    There are three voice statuses:
        DEPLOYING: Under review
        OK: Approved and ready to use
        UNDEPLOYED: Not approved and cannot be used
    '''

Request example

from dashscope.audio.tts_v2 import VoiceEnrollmentService

service = VoiceEnrollmentService()

# Filter by prefix, or set to None to query all.
voices = service.list_voices(prefix='myvoice', page_index=0, page_size=10)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Found voices: {voices}")

Response example

[
    {
        "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"
    }
]

Response parameters

API description

// There are three voice statuses:
//        DEPLOYING: Under review
//        OK: Approved and ready to use
//        UNDEPLOYED: Not approved and cannot be used
/**
 * Queries all created voices. The default page index is 0, and the default page size is 10.
 *
 * @param prefix The custom prefix for the voice. Only digits and lowercase letters are allowed, up to 10 characters. Can be null.
 * @return Voice[] An array of Voice objects. The Voice object encapsulates the voice ID, creation time, modification time, and status.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Voice[] listVoice(String prefix) throws NoApiKeyException, InputRequiredException 

/**
 * Queries all created voices.
 *
 * @param prefix The custom prefix for the voice. Only digits and lowercase letters are allowed, up to 10 characters.
 * @param pageIndex The page index for the query.
 * @param pageSize The page size for the query.
 * @return Voice[] An array of Voice objects. The Voice object encapsulates the voice ID, creation time, modification time, and status.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Voice[] listVoice(String prefix, int pageIndex, int pageSize) throws NoApiKeyException, InputRequiredException

Request example

You must import the third-party library 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");  // If you have not configured an environment variable, replace this with your API key.
    private static String prefix = "myvoice"; // Replace this with your actual value.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);

    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Query voices.
        Voice[] voices = service.listVoice(prefix, 0, 10);
        logger.info("List successful. Request ID: {}", service.getLastRequestId());
        logger.info("Voices Details: {}", new Gson().toJson(voices));
    }
}

Response example

[
    {
        "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"
    }
]

Response parameters

API description

def query_voice(self, voice_id: str) -> List[str]:
    '''
    Queries the details of a specific voice.
    param: voice_id The ID of the voice to query.
    return: List[str] The voice details, including status, creation time, audio link, and more.
    '''

Request example

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"Voice Details: {voice_details}")

Response example

{
    "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"
}

Response parameters

API description

/**
 * Queries the details of a specific voice.
 *
 * @param voiceId The ID of the voice to query.
 * @return Voice The voice details, including status, creation time, audio link, and more.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Request example

You must import the third-party library 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");  // If you have not configured an environment variable, replace this with your API key.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Replace this with your actual value.
    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("Query successful. Request ID: {}", service.getLastRequestId());
        logger.info("Voice Details: {}", new Gson().toJson(voice));
    }
}

Response example

{
    "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"
}

Response parameters

API description

def update_voice(self, voice_id: str, url: str) -> None:
    '''
    Updates a voice.
    param: voice_id The ID of the voice.
    param: url The URL of the audio file for voice cloning.
    '''

Request example

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"Update submitted. Request ID: {service.get_last_request_id()}")

API description

/**
 * Updates a voice.
 *
 * @param voiceId The voice to update.
 * @param url The URL of the audio file for voice cloning.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public void updateVoice(String voiceId, String url)
    throws NoApiKeyException, InputRequiredException

Request example

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");  // If you have not configured an environment variable, replace this with your API key.
    private static String fileUrl = "https://your-audio-file-url";  // Replace this with your actual value.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Replace this with your actual value.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    
    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Update the voice.
        service.updateVoice(voiceId, fileUrl);
        logger.info("Update submitted. Request ID: {}", service.getLastRequestId());
    }
}

API description

def delete_voice(self, voice_id: str) -> None:
    '''
    Deletes a voice.
    param: voice_id The voice to delete.
    '''

Request example

from dashscope.audio.tts_v2 import VoiceEnrollmentService

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

API description

/**
 * Deletes a voice.
 *
 * @param voiceId The voice to delete.
 * @throws NoApiKeyException if the API key is empty.
 * @throws InputRequiredException if a required parameter is empty.
 */
public void deleteVoice(String voiceId) throws NoApiKeyException, InputRequiredException 

Request example

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");  // If you have not configured an environment variable, replace this with your API key.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Replace this with your actual value.
    private static final Logger logger = LoggerFactory.getLogger(Main.class);
    
    public static void main(String[] args)
            throws NoApiKeyException, InputRequiredException {
        VoiceEnrollmentService service = new VoiceEnrollmentService(apiKey);
        // Delete the voice.
        service.deleteVoice(voiceId);
        logger.info("Deletion submitted. Request ID: {}", service.getLastRequestId());
    }
}