Python SDK - Qwen Cloud

CosyVoice voice cloning can be called via the DashScope Python SDK using the VoiceEnrollmentService class. This SDK covers voice cloning only — CosyVoice voice design and all Qwen voice cloning/design must use the HTTP API. User guide: Voice cloning.

Prerequisites

An API key configured as the DASHSCOPE_API_KEY environment variable
The latest DashScope SDK

Service URL

Set the base URL before creating the service:

import dashscope

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

VoiceEnrollmentService class

Package: dashscope.audio.tts_v2.VoiceEnrollmentService Manages the lifecycle of CosyVoice cloned voices (create, list, query, update, delete).

Constructor

VoiceEnrollmentService()

create_voice()

Create a cloned voice from audio.

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

Parameter	Type	Required	Description
target_model	str	Yes	Speech synthesis model for the cloned voice. Must match the model in your synthesis calls.
prefix	str	Yes	Voice name prefix. Alphanumeric only, max 10 characters. Generated name format: `{target_model}-{prefix}-{unique_id}`.
url	str	Yes	Audio file URL for cloning. Must be publicly accessible.
language_hints	List[str]	No	Language hint for the audio. Only the first element is used. Default: `["zh"]`.
max_prompt_audio_length	float	No	Max audio duration (seconds) after preprocessing. Range: [3.0, 30.0]. Default: 10.0.
enable_preprocess	bool	No	Enable audio preprocessing (noise reduction, enhancement). Default: `False`.

Returns: str — the generated voice ID (voice_id).

Show Example

import dashscope
from dashscope.audio.tts_v2 import VoiceEnrollmentService

dashscope.base_http_api_url = 'https://dashscope-intl.aliyuncs.com/api/v1'

service = VoiceEnrollmentService()

voice_id = service.create_voice(
  target_model="cosyvoice-v3-plus",
  prefix="myvoice",
  url="https://your-audio-url.wav",
  language_hints=["zh"]
)

print(f"Created voice: {voice_id}")

list_voice()

List cloned voices with optional filtering and pagination.

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

Parameter	Type	Required	Description
prefix	str	No	Filter voices by name prefix.
page_index	int	No	Page number, starting from 0. Default: 0.
page_size	int	No	Results per page. Default: 10.

Returns: list — list of voice objects.

Show Example

service = VoiceEnrollmentService()

voices = service.list_voice(prefix="myvoice", page_size=10)

for voice in voices:
  print(voice)

query_voice()

Query details of a specific cloned voice.

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

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

Returns: dict — voice details including status, resource_link, target_model, etc.

Show Example

service = VoiceEnrollmentService()

details = service.query_voice(voice_id="cosyvoice-v3-plus-myvoice-xxxxxx")

print(f"Status: {details['status']}")
print(f"Target model: {details['target_model']}")

update_voice()

Update a cloned voice with new audio.

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

Parameter	Type	Required	Description
voice_id	str	Yes	The voice ID to update.
url	str	Yes	New audio file URL. Must be publicly accessible.
language_hints	List[str]	No	Language hint for the new audio.
max_prompt_audio_length	float	No	Max audio duration (seconds) after preprocessing.
enable_preprocess	bool	No	Enable audio preprocessing.

Returns: None

Show Example

service = VoiceEnrollmentService()

service.update_voice(
  voice_id="cosyvoice-v3-plus-myvoice-xxxxxx",
  url="https://new-audio-url.wav",
  language_hints=["en"]
)

print("Voice updated successfully")

delete_voice()

Delete a cloned voice.

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

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

Returns: None

Show Example

service = VoiceEnrollmentService()

service.delete_voice(voice_id="cosyvoice-v3-plus-myvoice-xxxxxx")

print("Voice deleted successfully")

​Prerequisites

​Service URL

​VoiceEnrollmentService class

​Constructor

​create_voice()

​list_voice()

​query_voice()

​update_voice()

​delete_voice()

Prerequisites

Service URL

VoiceEnrollmentService class

Constructor

create_voice()

list_voice()

query_voice()

update_voice()

delete_voice()