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 for the voice. This must match the model used in subsequent speech synthesis API calls, otherwise synthesis will fail. Recommended models are cosyvoice-v3-flash or cosyvoice-v3-plus.
    param: prefix A recognizable name for the voice (only digits, uppercase and lowercase letters, and underscores are allowed, up to 10 characters). We recommend using an identifier related to the role or scenario. This keyword appears in the cloned voice name. Generated voice name format: model_name-prefix-unique_identifier, such as 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 language of the sample audio for extracting voice features. This parameter applies only to the cosyvoice-v3-flash and cosyvoice-v3-plus models.
            It helps the model identify the language of the sample audio to extract features more accurately and improve cloning results.
            If the language hint does not match the actual audio language (for example, setting en for Chinese audio), the system ignores the hint and automatically detects the language from audio content.
            Valid values: zh (default), en, fr, de, ja, ko, ru. This parameter is an array, but the current version processes only the first element. Pass only one value.
    return: voice_id The voice ID. It can be used directly as 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=['zh']
)

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 for the voice. This must match the model used in subsequent speech synthesis API calls, otherwise synthesis will fail. Recommended models are cosyvoice-v3-flash or cosyvoice-v3-plus.
 * @param prefix A recognizable name for the voice (only digits, uppercase and lowercase letters, and underscores are allowed, up to 10 characters). We recommend using an identifier related to the role or scenario. This keyword appears in the cloned voice name. Generated voice name format: model_name-prefix-unique_identifier, such as 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 languageHints here.
 *                  languageHints specifies the language of the sample audio for extracting voice features. This parameter applies only to the cosyvoice-v3-flash and cosyvoice-v3-plus models.
 *                  This parameter helps the model identify the language of the sample audio (original reference audio) to extract voice features more accurately and improve cloning results.
 *                  If the language hint does not match the actual audio language (for example, setting en for Chinese audio), the system ignores the hint and automatically detects the language from audio content.
 *                  Valid values: zh (default), en, fr, de, ja, ko, ru. This parameter is an array, but the current version processes only the first element. Pass only one value.
 * @return Voice The newly created voice. You can get the voice ID using the getVoiceId method of the Voice object. The voice ID can be used directly as 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("zh")).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 of 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, including 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'}]
    Three voice statuses:
        DEPLOYING: Under review
        OK: Approved and ready to use
        UNDEPLOYED: Rejected and not usable
    '''

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

// Three voice statuses:
//        DEPLOYING: Under review
//        OK: Approved and ready to use
//        UNDEPLOYED: Rejected and not usable
/**
 * Queries all created voices. The default page index is 0, and the default page size is 10.
 *
 * @param prefix The custom prefix of 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 ID, creation time, modification time, and status of the voice.
 * @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 of 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 ID, creation time, modification time, and status of the voice.
 * @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 need to 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 the 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 details of a specific voice.
    param: voice_id The ID of the voice to query.
    return: List[str] 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 details of a specific voice.
 *
 * @param voiceId The ID of the voice to query.
 * @return Voice 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 need to 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 the 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 the actual value.
    private static String voiceId = "cosyvoice-v3-plus-myvoice-xxx"; // Replace this with the 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 the 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());
    }
}