Qwen-Audio and CosyVoice voice cloning Python SDK reference
Clone and manage Qwen-Audio and CosyVoice voices with the DashScope Python SDK.
Service endpoint
The SDK service endpoint is determined by the workspace/region parameters of the Client constructor (corresponding to the addresses below, which include the WorkspaceId). To switch to a different region, change the Client constructor parameters to the values for that region.
Note
- API keys differ by region. Use the API key for the target region.
- The region setting is a
Client-level setting and affects all DashScope SDK API calls made by thatClient.
China (Beijing)
https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
ImportantAlibaba 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.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.com - Singapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Core resource (client.audio.voices)
Purpose: Manage the lifecycle of Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice cloned voices (create, query, update, and delete).
Client construction (authentication and region)
import os
import dashscope
client = dashscope.Client(
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
workspace="{WorkspaceId}",
region="cn-beijing",
)
create() — Create a voice
Method signature:
def create(self, *, target_model: str, prefix: str, url: str,
language_hints: List[str] = None,
max_prompt_audio_length: float = None,
extra_input: Dict = None,
parameters: Dict = None, ...) -> Voice
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: |
url | str | Yes | Reference audio for voice cloning. Accepts a publicly accessible URL or a Base64 Data URI, such as |
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 This parameter is an array and must contain exactly one element. NoteApplies 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.1-realtime-flash, 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
Default: ["zh"]. |
max_prompt_audio_length | float | No | The maximum duration (in seconds) of the reference audio used for voice cloning after preprocessing. Valid values: [3.0, 30.0]. Default: 10.0. NoteApplies 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.1-realtime-flash, 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. NoteApplies 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.1-realtime-flash, 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 through the |
Return value: A Voice object, whose voice_id is the voice ID and whose request_id is the request ID.
list() — List voices
Method signature:
def list(self, *, prefix: str = None, page_index: int = 0, page_size: int = 10, ...) -> VoiceList
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: A VoiceList object, whose voices is the list of voices and whose request_id is the request ID. Each list item is a dictionary. Use voice.get("target_model") to get the target model ID.
get() — Query voice details
Method signature:
def get(self, voice_id: str, ...) -> Voice
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
voice_id | str | Yes | The voice ID to query. |
Return value: A Voice object containing the voice details. Use voice.target_model to get the target model ID.
update() — Update a voice
Method signature:
def update(self, voice_id: str, *, url: str, ...) -> JobStatus
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
voice_id | str | Yes | The voice ID to update. |
url | str | Yes | New reference audio. Accepts a publicly accessible URL or a Base64 Data URI, such as |
delete() — Delete a voice
Method signature:
def delete(self, voice_id: str, ...) -> JobStatus
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
voice_id | str | Yes | The voice ID to delete. |
Code examples
Create a voice
import os
import dashscope
# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
TARGET_MODEL = 'qwen-audio-3.1-tts-plus'
voice_prefix = 'myvoice'
url = 'https://your-audio-file-url'
# Avoid frequent calls. Each call creates a new voice, and you can't create
# more after reaching the quota limit.
voice = client.audio.voices.create(
target_model=TARGET_MODEL,
prefix=voice_prefix,
url=url,
max_prompt_audio_length=10,
# extra_input={'enable_preprocess': False, 'enable_volume_normalization': True}
)
print(f"Request ID: {voice.request_id}")
print(f"Voice ID: {voice.voice_id}")
For a local WAV file, replace the url assignment above with the following code before calling client.audio.voices.create(). To update a voice, also pass the Data URI through the url parameter of client.audio.voices.update(). 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 os
import dashscope
# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
# Filter by prefix, or set to None to list all voices
voices = client.audio.voices.list(prefix='myvoice', page_index=0, page_size=10)
print(f"Request ID: {voices.request_id}")
print(f"Found voices: {voices.voices}")
for voice in voices.voices:
print(f"Target model: {voice.get('target_model')}")
Query a specific voice
import os
import dashscope
# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
voice_id = 'qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx'
voice_details = client.audio.voices.get(voice_id=voice_id)
print(f"Request ID: {voice_details.request_id}")
print(f"Voice Details: {voice_details}")
print(f"Target model: {voice_details.target_model}")
Update a voice
import os
import dashscope
# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
result = client.audio.voices.update(
voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx',
url='https://your-new-audio-file-url'
)
print(f"Update submitted. Request ID: {result.request_id}")
Delete a voice
import os
import dashscope
# The following is the configuration for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not configured an environment variable, replace the following line with your Model Studio API key: api_key="sk-xxx"
api_key=os.getenv("DASHSCOPE_API_KEY"),
workspace="{WorkspaceId}",
region="cn-beijing",
)
result = client.audio.voices.delete(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {result.request_id}")