Voice cloning Python SDK reference

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.

API keys differ by region. Use the API key for the target region.
The region setting is global and affects all DashScope SDK API calls.

China (Beijing)
Singapore

https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1Replace {WorkspaceId} with your actual workspace ID.

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

VoiceEnrollmentService class

Package path: dashscope.audio.tts_v2.VoiceEnrollmentService Purpose: Manage the lifecycle of Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice cloned voices (create, query, update, and delete).

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 target model that uses the voice. It must match the model used in subsequent requests with this voice; otherwise, the requests fail.
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	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 and must contain exactly one element. Applies to qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash. Click to view supported languages by model qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-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	The maximum duration (in seconds) of the reference audio after preprocessing. Valid values: [3.0, 30.0].Default: 10.0. Applies to qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
enable_preprocess	bool	No	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. Applies to qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, qwen-audio-3.1-realtime-plus, qwen-audio-3.0-realtime-plus, qwen-audio-3.0-realtime-flash, cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash.
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) -> None

Parameters:

Parameter	Type	Required	Description
voice_id	str	Yes	The voice ID to update.
url	str	Yes	The new audio file URL.

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