API Operation Details

Python

You can clone a voice using the create_voice method of the VoiceEnrollmentService class. Import the VoiceEnrollmentService class as follows: from dashscope.audio.tts_v2 import VoiceEnrollmentService.

The create_voice method returns a voice ID. You can use this ID for CosyVoice speech synthesis as a voice.

def create_voice(self, target_model: str, prefix: str, url: str) -> str:
    '''
    Create a voice
    param: target_model The model used for voice cloning. Supported models are cosyvoice-v1 and cosyvoice-v2.
    param: prefix A custom prefix for the voice. Only digits and lowercase letters are allowed, with a maximum of 10 characters.
    param: url The URL of the audio file used to clone the voice. This URL must be publicly accessible.
    return: The voice ID
    '''

Java

You can clone a voice using the createVoice method of the VoiceEnrollmentService class. Import the VoiceEnrollmentService class as follows: import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;.

The getVoiceId method of the Voice class, returned by createVoice, obtains the voice ID. You can use this ID for CosyVoice speech synthesis as a voice.

/**
 * Create a voice
 *
 * @param targetModel The model used for voice cloning. Supported models are cosyvoice-v1 and cosyvoice-v2.
 * @param prefix A custom prefix for the voice. Only digits and lowercase letters are allowed, with a maximum of 10 characters.
 * @param url The URL of the audio file used to clone the voice. This URL must be publicly accessible.
 * @return Voice object
 * @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) throws NoApiKeyException, InputRequiredException

RESTful

Basic information

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

Authorization: Bearer {api-key} // Replace with your API key
Content-Type: application/json

{
    "model": "voice-enrollment",
    "input": {
        "action": "create_voice",
        "target_model": "cosyvoice-v2",
        "prefix": "testpfx",
        "url": "https://yourAudioFileUrl"
    }
}

Request parameters

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": "create_voice",
        "target_model": "cosyvoice-v1",
        "prefix": "testpfx",
        "url": "https://yourAudioFileUrl"
    }
}'

Response parameters

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

Python

You can use the list_voices method of the VoiceEnrollmentService class to query all voices. Import the VoiceEnrollmentService class as follows: from dashscope.audio.tts_v2 import VoiceEnrollmentService.

There are two timbre states:

• UNDEPLOYED: cannot be invoked
• Callable

def list_voices(self, prefix=None, page_index: int = 0, page_size: int = 10) -> List[dict]:
    '''
    Queries all created voices.
    param: prefix The voice prefix. If set to None, all voices are returned.
    param: page_index The page index for the query.
    param: page_size The number of entries per page.
    return: List[dict] A list of voices. Each entry contains the voice ID, creation time, modification time, and status.
    '''

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:

Java

You can use the listVoice method of the VoiceEnrollmentService class to query all voices. Import the VoiceEnrollmentService class as follows: import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;.

Two timbre states are available:

• UNDEPLOYED: The voice cannot be invoked.
• OK: Callable

/**
 * Queries all created voices. The default page index is 0 and the default page size is 10.
 *
 * @param prefix The custom voice prefix. It can contain only digits and lowercase letters and must be less than 10 characters long. This parameter can be null.
 * @return Voice[] An array of voice objects.
 * @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 voice prefix. It can contain only digits and lowercase letters and must be less than 10 characters long.
 * @param pageIndex The page index for the query.
 * @param pageSize The number of entries per page.
 * @return Voice[] An array of voice objects.
 * @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

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:

RESTful

Basic information

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

Authorization: Bearer {api-key} // Replace {api-key} with your own API key.
Content-Type: application/json

{
    "model": "voice-enrollment",
    "input": {
        "action": "list_voice",
        "prefix": "testpfx",
        "page_index": 0,
        "page_size": 10
    }
}

Request parameters

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": "list_voice",
        "prefix": "testpfx",
        "page_index": 0,
        "page_size": 10
    }
}'

Response parameters

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

Python

You can call the query_voices method of the VoiceEnrollmentService class to query a specific voice. Import the VoiceEnrollmentService class as follows: from dashscope.audio.tts_v2 import VoiceEnrollmentService.

def query_voices(self, voice_id: str) -> List[str]:
    '''
    Query all created voices.
    param: voice_id: voice to query
    return: bytes: audio used to register the voice
    '''

Response example:

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

Response parameters:

Java

You can call the queryVoice method of the VoiceEnrollmentService class to query a specific voice. Import the VoiceEnrollmentService class as follows: import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;.

/**
 * Queries a specific voice.
 *
 * @param voiceId The ID of the voice to query.
 * @return Voice A Voice object that contains the status information and the URL of the audio file for cloning.
 * @throws NoApiKeyException If the API key is empty.
 * @throws InputRequiredException If a required parameter is empty.
 */
public Voice queryVoice(String voiceId) throws NoApiKeyException, InputRequiredException

Response example:

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

Response parameters:

RESTful

Basic information

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

Authorization: Bearer {api-key} // Replace {api-key} with your API key.
Content-Type: application/json

{
    "model": "voice-enrollment",
    "input": {
        "action": "query_voice",
        "voice_id": "yourVoiceId"
    }
}

Request parameters

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

Response parameters

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

Python

You can update a voice using the update_voice method of the VoiceEnrollmentService class. Import the VoiceEnrollmentService class as follows: from dashscope.audio.tts_v2 import VoiceEnrollmentService.

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

Java

You can update a voice using the updateVoice method of the VoiceEnrollmentService class. Import the VoiceEnrollmentService class as follows: import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;.

/**
 * Update a voice.
 *
 * @param voiceId The voice to update.
 * @param url The URL of the audio file for 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

RESTful

Basic information

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

Authorization: Bearer {api-key} // Replace {api-key} with your own API key.
Content-Type: application/json

{
    "model": "voice-enrollment",
    "input": {
        "action": "update_voice",
        "voice_id": "yourVoiceId",
        "url": "https://yourAudioFileUrl"
    }
}

Request parameters

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": "update_voice",
        "voice_id": "yourVoiceId",
        "url": "https://yourAudioFileUrl"
    }
}'

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

Python

To delete a voice, call the delete_voice method of the VoiceEnrollmentService class. The VoiceEnrollmentService class is imported as follows: from dashscope.audio.tts_v2 import VoiceEnrollmentService.

def delete_voice(self, voice_id: str) -> None:
    '''
    Delete a voice.

    Args:
        voice_id: The ID of the voice to delete.
    '''

Java

You can delete a voice using the VoiceEnrollmentService class's deleteVoice method. The VoiceEnrollmentService class is imported as follows: import com.alibaba.dashscope.audio.ttsv2.enrollment.VoiceEnrollmentService;.

/**
 * Delete a voice.
 *
 * @param voiceId The ID of 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

RESTful

Basic information

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

Authorization: Bearer {api-key} // Replace {api-key} with your own API key.
Content-Type: application/json

{
    "model": "voice-enrollment",
    "input": {
        "action": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}

Request parameters

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": "delete_voice",
        "voice_id": "yourVoiceId"
    }
}'

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