Voice cloning Python SDK reference - Alibaba Cloud Model Studio

Service endpoint

The SDK uses the China (Beijing) region endpoint by default. To switch to a different region, set dashscope.base_http_api_url before you initialize the client.

Singapore
China (Beijing)

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1Replace {WorkspaceId} with your actual workspace ID.

Switch to the Singapore region:

import dashscope

# Set at the beginning of your code
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

Note :

API keys differ between regions. Use the API key that corresponds to the target region.

The region setting is global and affects all DashScope SDK API calls.

Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:

China (Beijing): from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
Singapore: from dashscope-intl.aliyuncs.com to {WorkspaceId}.ap-southeast-1.maas.aliyuncs.com

Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.

VoiceEnrollmentService class

Package path: dashscope.audio.tts_v2.VoiceEnrollmentService Purpose: Manage the lifecycle of Qwen-Audio-TTS/CosyVoice cloned voices, including creating, querying, updating, and deleting voices.

Constructor

VoiceEnrollmentService()

create_voice() — Create a voice

Method signature:

def create_voice(self, target_model: str, prefix: str, url: str,
                 language_hints: List[str] = None,
                 max_prompt_audio_length: float = None,
                 **kwargs) -> str

Parameters:

Parameter	Type	Required	Description
target_model	str	Yes	The text-to-speech (TTS) model that drives the cloned voice. It must match the model you specify when calling the TTS API; otherwise, synthesis fails.
prefix	str	Yes	A prefix for the voice name. Only alphanumeric characters are allowed, with a maximum length of 10 characters. The resulting voice name follows this format: `{target_model}-{prefix}-{unique_id}`.
url	str	Yes	The URL of the audio file for voice cloning. The URL must be publicly accessible.
language_hints	List[str]	No	Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is `voice-enrollment`). Supported only by qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, v3-plus, and v3-flash. Helps the model identify the language of the sample audio to extract voice features more accurately and improve cloning quality. If the specified language doesn't match the actual audio language (for example, setting `en` when the audio is in Chinese), the system ignores this value and detects the language automatically. This parameter is an array, but the current version processes only the first element. Valid values vary by model: qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash: zh: Chinese en: English fr: French de: German ja: Japanese ko: Korean ru: Russian pt: Portuguese th: Thai id: Indonesian vi: Vietnamese it: Italian es: Spanish ms: Malaysian fil: Filipino ar: Arabic cosyvoice-v3-plus: zh: Chinese en: English fr: French de: German ja: Japanese ko: Korean ru: Russian cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash: zh: Chinese en: English fr: French de: German ja: Japanese ko: Korean ru: Russian pt: Portuguese th: Thai id: Indonesian vi: Vietnamese Default: ["zh"].
max_prompt_audio_length	float	No	Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is `voice-enrollment`). Supported only by qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, and v3-flash. The maximum duration (in seconds) of the reference audio after preprocessing. Valid values: [3.0, 30.0]. Default: 10.0.
enable_preprocess	bool	No	Applies only to Qwen-Audio-TTS/CosyVoice voice cloning (when model is `voice-enrollment`). Supported only by qwen-audio-3.0-tts-plus,qwen-audio-3.0-tts-flash, cosyvoice-v3.5-plus, v3.5-flash, and v3-flash. Whether to enable audio preprocessing (noise reduction, audio enhancement, and volume normalization). Enable this for recordings with background noise. Disable it for recordings in quiet environments to preserve the original voice characteristics. Default: false.
enable_volume_normalization	bool	No	Specifies whether to normalize the volume of the sample audio used for voice cloning. Pass this parameter directly as a keyword argument. Default value: `False`. If you set this parameter to `True`, the volume of audio synthesized with the created voice may differ from that of audio synthesized with a voice created with this parameter disabled.

Return value: str — The voice ID (voice_id).

list_voices() — List voices

Method signature:

def list_voices(self, prefix: str = None, page_index: int = 0, page_size: int = 10) -> list

Parameters:

Parameter	Type	Required	Description
prefix	str	No	Filter by voice name prefix.
page_index	int	No	Page index. Default: 0.
page_size	int	No	Number of entries per page. Default: 10.

Return value: list — A list of voices.

query_voice() — Query voice details

Method signature:

def query_voice(self, voice_id: str) -> dict

Parameters:

Parameter	Type	Required	Description
voice_id	str	Yes	The voice ID to query.

Return value: dict — Voice details.

update_voice() — Update a voice

Method signature:

def update_voice(self, voice_id: str, url: str, language_hints: List[str] = None,
                 max_prompt_audio_length: float = None, enable_preprocess: bool = None) -> None

Parameters:

Parameter	Type	Required	Description
voice_id	str	Yes	The voice ID to update.
url	str	Yes	The new audio file URL.
language_hints	List[str]	No	Language hints for the sample audio.
max_prompt_audio_length	float	No	Maximum duration of the reference audio.
enable_preprocess	bool	No	Whether to enable audio preprocessing.

delete_voice() — Delete a voice

Method signature:

def delete_voice(self, voice_id: str) -> None

Parameters:

Parameter	Type	Required	Description
voice_id	str	Yes	The voice ID to delete.

Code examples

The following examples show how to use the VoiceEnrollmentService class for common voice cloning operations.

Create a voice

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

TARGET_MODEL = 'qwen-audio-3.0-tts-flash'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'
service = VoiceEnrollmentService()

# Avoid frequent calls. Each call creates a new voice, and you can't create
# more after reaching the quota limit.
voice_id = service.create_voice(
    target_model=TARGET_MODEL,
    prefix=voice_prefix,
    url=url,
    max_prompt_audio_length=10,
    # enable_preprocess=False,
    # enable_volume_normalization=True
)

print(f"Request ID: {service.get_last_request_id()}")
print(f"Voice ID: {voice_id}")

List voices

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()

# Filter by prefix, or set to None to list all voices
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}")

Query a specific voice

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
voice_id = 'qwen-audio-3.0-tts-flash-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}")

Update a voice

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.update_voice(
    voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
    url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {service.get_last_request_id()}")

Delete a voice

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# The following uses the Singapore region endpoint. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"

service = VoiceEnrollmentService()
service.delete_voice(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {service.get_last_request_id()}")

​Service endpoint

​VoiceEnrollmentService class

​Constructor

​create_voice() — Create a voice

​list_voices() — List voices

​query_voice() — Query voice details

​update_voice() — Update a voice

​delete_voice() — Delete a voice

​Code examples

​Create a voice

​List voices

​Query a specific voice

​Update a voice

​Delete a voice

Service endpoint

VoiceEnrollmentService class

Constructor

create_voice() — Create a voice

list_voices() — List voices

query_voice() — Query voice details

update_voice() — Update a voice

delete_voice() — Delete a voice

Code examples

Create a voice

List voices

Query a specific voice

Update a voice

Delete a voice