Skip to main content
QwenCloud home page
Docs
Voice Cloning API reference

Voice cloning Python SDK reference

Qwen-Audio-TTS/Qwen-Audio-Realtime/CosyVoice voice cloning is accessible through the DashScope Python SDK.

Service endpoint

Set the endpoint below before initialization. To use another 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.
https://ap-southeast-1.maas.qwencloudapi.com/api/v1 This is the Singapore endpoint. For another region, replace ap-southeast-1 in the URL. See Regions.

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:
ParameterTypeRequiredDescription
target_modelstrYesThe target model that uses the voice. It must match the model used in subsequent requests with this voice; otherwise, the requests fail.
prefixstrYesA 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}.
urlstrYesReference audio for voice cloning. Accepts a publicly accessible URL or a Base64 Data URI, such as data:audio/wav;base64,....
language_hintsList[str]NoHelps 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. Note: Applies to qwen-audio-3.1-tts-plus, 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 (cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China North 2 (Beijing)).
  • qwen-audio-3.1-tts-plus, 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_lengthfloatNoThe maximum duration (in seconds) of the reference audio after preprocessing. Valid values: [3.0, 30.0]. Default: 10.0. Note: Applies to qwen-audio-3.1-tts-plus, 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 (cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China North 2 (Beijing)).
enable_preprocessboolNoWhether 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. Note: Applies to qwen-audio-3.1-tts-plus, 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 (cosyvoice-v3.5-plus and cosyvoice-v3.5-flash are available only in China North 2 (Beijing)).
enable_volume_normalizationboolNoSpecifies 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:
ParameterTypeRequiredDescription
prefixstrNoFilter by voice name prefix.
page_indexintNoPage index. Default: 0.
page_sizeintNoNumber 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:
ParameterTypeRequiredDescription
voice_idstrYesThe 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:
ParameterTypeRequiredDescription
voice_idstrYesThe voice ID to update.
urlstrYesNew reference audio. Accepts a publicly accessible URL or a Base64 Data URI, such as data:audio/wav;base64,....

delete_voice() — Delete a voice

Method signature: 
def delete_voice(self, voice_id: str) -> None
Parameters:
ParameterTypeRequiredDescription
voice_idstrYesThe 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
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.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}")
For a local WAV file, replace the url assignment above with the following code before calling create_voice. To update a voice, also pass the Data URI through the url parameter of update_voice. Replace sample.wav with your local audio path. 
import base64
from pathlib import Path

url = "data:audio/wav;base64," + base64.b64encode(
  Path("sample.wav").read_bytes()
).decode("ascii")

List voices

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.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
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.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
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.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
# Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
# API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
dashscope.base_http_api_url = "https://ap-southeast-1.maas.qwencloudapi.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()}")