Overview and SDK Code Examples

Scenarios

• Companionship: Use cloned voices of family members for personalized companionship in smart assistants, in-car navigation systems, and home entertainment—such as reading picture books aloud, controlling home appliances, or providing educational tutoring.

• Education: Use cloned teacher voices to strengthen student-teacher interaction, enrich teaching videos and course materials, and create more friendly and engaging learning experiences.

• Audio and video production: Clone streamer voices to simplify post-recording, dubbing, and other production tasks—and speed up audio and video creation.

• Intelligent customer service: Use cloned account manager voices to deliver voice services—including customer follow-ups and marketing calls—to make interactions more personal and human-like.

Benefits

• Low audio sample requirement: You can clone a voice using only 10–20 seconds of audio. This significantly reduces recording costs and improves efficiency.

• High fidelity: Powered by the CosyVoice generative neural network speech LLM, developed by Alibaba Tongyi Lab, and enhanced with zero-shot learning technology, the service accurately reproduces tone, rhythm, and emotional expression—making cloned voices nearly indistinguishable from real recordings.

• Real-time synthesis: You can clone authentic voice characteristics in seconds, delivering fast, real-time voice cloning.

Important notes

• Voice cloning limit: Each UID can clone up to 1,000 voices (shared across versions 1.0 and 2.0). If you need more, contact our pre-sales team in advance. Voices unused for over one year are unpublished. Deleting cloned voices is not currently supported.

• Copyright and legality: You are responsible for owning or having lawful rights to use any voice you provide. Review the Terms of Service for Intelligent Speech Interaction—Streaming Text-to-Speech before enabling the service.

• Using cloned voices: Cloned voices (VoiceName) work the same way as preset voices (such as longxiaoxia) in the speech synthesis CosyVoice Large Language Model (LLM).

  Important

  You can use CosyVoice-cloned voices only in the speech synthesis CosyVoice Large Language Model (LLM). Do not use them in other speech synthesis services—or synthesis will fail.

• Service invocation method: Voice cloning is available only through API calls.

Billing

Voice cloning is free. After successful cloning, using text-to-speech incurs charges for the speech synthesis CosyVoice Large Language Model (LLM) API. Current pricing is CNY 2 per 10,000 characters. For details, see Billing—Pay-as-you-go.

Prerequisites

• Review the terms and enable the commercial edition of Intelligent Speech Interaction—Streaming Text-to-Speech. To enable the service, go to Intelligent Speech Interaction.

• You must prepare an audio URL accessible over the public network. We recommend that you upload your audio file to OSS. For instructions, see Upload objects to OSS. Audio requirements:

  • Sound channels: mono or stereo

  • Audio bit depth: 16 bit

  • Sample rate: greater than 16,000 Hz

  • Format: WAV, MP3, M4A

  • File size: up to 10 MB

  • Audio duration: 10–20 seconds. The duration must not exceed 60 seconds. You must speak continuously during recording. You must include at least one segment of uninterrupted speech longer than 5 seconds.

Usage examples

This topic provides examples using the Alibaba Cloud Python SDK and Java SDK. For SDKs in other languages, see Alibaba Cloud SDK development reference.

Python example

Step 1: Install the Alibaba Cloud SDK

You can run the following command to install the latest version of the Alibaba Cloud Python SDK.

pip install aliyun-python-sdk-core

Step 2: Implement the feature

The following code demonstrates how to call the voice cloning API.

import os
import json
import time


from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest

# Get your Alibaba Cloud AccessKey ID and AccessKey secret from environment variables to avoid hardcoding credentials
# If you have not set environment variables, replace os.environ.get('ALIYUN_AK_ID') with your AccessKey ID and os.environ.get('ALIYUN_AK_SECRET') with your AccessKey secret
client = AcsClient(os.environ.get('ALIYUN_AK_ID'), os.environ.get('ALIYUN_AK_SECRET'))
domain = 'nls-slp.cn-shanghai.aliyuncs.com'
version = '2019-08-19'


def build_request(api_name, method):
    request = CommonRequest()
    request.set_domain(domain)
    request.set_version(version)
    request.set_action_name(api_name)
    request.set_method(method)
    request.set_protocol_type('https')
    return request


def cosy_clone(voice_prefix, url):
    clone_request = build_request('CosyVoiceClone', 'POST')
    clone_request.add_body_params('Url', url)
    clone_request.add_body_params('VoicePrefix', voice_prefix)
    # Set read timeout to 15 seconds
    clone_request.set_read_timeout(15)
    begin = int(round(time.time() * 1000))
    clone_response = client.do_action_with_exception(clone_request)
    end = int(round(time.time() * 1000))
    print(json.loads(clone_response))
    print('cost: {}'.format(end - begin))


def cosy_list(voice_prefix, page_index=1, page_size=10):
    list_request = build_request('ListCosyVoice', 'POST')
    list_request.add_body_params('VoicePrefix', voice_prefix)
    list_request.add_body_params('PageIndex', page_index)
    list_request.add_body_params('PageSize', page_size)
    list_response = client.do_action_with_exception(list_request)
    print(json.loads(list_response))


if __name__ == '__main__':
    # 1. Call the CosyVoiceClone API to clone a voice
    audio_url = 'https://your-url'
    prefix = 'tongyi'  # Must contain only letters or numbers
    cosy_clone(prefix, audio_url)
    # On success, the API returns VoiceName synchronously in this format: cosyvoice-${voice_prefix}-${7 random characters}

    # 2. Call the ListCosyVoice API to check the status of all voices with a given prefix
    cosy_list(prefix)

For more information about the CosyVoice voice cloning API, see CosyVoice voice cloning API.

Step 3: Use the cloned voice

You can use cloned voices the same way you use built-in CosyVoice voices. When calling the CosyVoice Large Language Model (LLM), you must set the voice field to your cloned VoiceName. For instructions, see speech synthesis CosyVoice Large Language Model (LLM).

Java example

Step 1: Install the Alibaba Cloud SDK

You can download the latest SDK version from Maven.

<dependency>
    <groupId>com.aliyun</groupId>
    <artifactId>aliyun-java-sdk-core</artifactId>
    <version>4.6.4</version>
</dependency>

Step 2: Implement the feature

The following code demonstrates how to call the voice cloning API.

package org.example;

import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.MethodType;
import com.aliyuncs.http.ProtocolType;
import com.aliyuncs.profile.DefaultProfile;

public class CosyVoiceDemo {
    // Domain
    private static final String DOMAIN = "nls-slp.cn-shanghai.aliyuncs.com";
    // API version
    private static final String API_VERSION = "2019-08-19";

    private static final IAcsClient client;

    static {
        // Create and initialize a DefaultAcsClient instance
        DefaultProfile profile = DefaultProfile.getProfile(
                "cn-shanghai",
                // Get your Alibaba Cloud AccessKey ID from environment variables to avoid hardcoding credentials
                // If you have not set environment variables, replace System.getenv("AK_ID") with your AccessKey ID
                System.getenv("AK_ID"),
                // Get your Alibaba Cloud AccessKey secret from environment variables to avoid hardcoding credentials
                // If you have not set environment variables, replace System.getenv("AK_SECRET") with your AccessKey secret
                System.getenv("AK_SECRET"));
        client = new DefaultAcsClient(profile);
    }

    public static void main(String[] args) throws InterruptedException {
        String voicePrefix = "your-voice-prefix";
        String url = "your-file-url";
        cosyClone(voicePrefix, url);
        cosyList(voicePrefix);
    }

    private static void cosyList(String voicePrefix) {
        CommonRequest request = buildRequest("ListCosyVoice");
        request.putBodyParameter("VoicePrefix", voicePrefix);
        String response = sendRequest(request);
        System.out.println(response);
    }

    private static void cosyClone(String voicePrefix, String url) {
        CommonRequest cloneRequest = buildRequest("CosyVoiceClone");
        cloneRequest.putBodyParameter("VoicePrefix", voicePrefix);
        cloneRequest.putBodyParameter("Url", url);
        // Set read timeout to 15 seconds
        cloneRequest.setSysReadTimeout(15000);
        long startTime = System.currentTimeMillis();
        String response = sendRequest(cloneRequest);
        long endTime = System.currentTimeMillis();
        System.out.println(response);
        System.out.println("cost: "+ (endTime - startTime) + " ms");
    }

    private static CommonRequest buildRequest(String popApiName) {
        CommonRequest request = new CommonRequest();
        request.setMethod(MethodType.POST);
        request.setDomain(DOMAIN);
        request.setVersion(API_VERSION);
        request.setAction(popApiName);
        request.setProtocol(ProtocolType.HTTPS);
        return request;
    }

    private static String sendRequest(CommonRequest request) {
        try {
            CommonResponse response = client.getCommonResponse(request);
            return response.getData();
        } catch (ServerException e) {
            e.printStackTrace();
        } catch (ClientException e) {
            e.printStackTrace();
        }
        return null;
    }
}

For more information about the CosyVoice voice cloning API, see CosyVoice voice cloning API.

Step 3: Use the cloned voice

You can use cloned voices the same way you use built-in CosyVoice voices. When calling the CosyVoice Large Language Model (LLM), you must set the voice field to your cloned VoiceName. For instructions, see speech synthesis CosyVoice Large Language Model (LLM).

Status codes

References

• CosyVoice voice cloning API

• speech synthesis CosyVoice Large Language Model (LLM)