Clone and manage Qwen-Audio and CosyVoice voices with the DashScope Python SDK.
Service endpoint
The SDK endpoint is determined by the workspace and region parameters of the Client constructor (corresponding to the endpoints 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 Client-level and affects all DashScope SDK API calls made through that Client.
Singapore
https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1
Replace {WorkspaceId} with your actual workspace ID.
China (Beijing)
https://{WorkspaceId}.cn-beijing.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 set 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 Singapore (ap-southeast-1) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
workspace="{WorkspaceId}",
region="ap-southeast-1",
)
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 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 in 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.
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 with the voice details.
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 Singapore (ap-southeast-1) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not set 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="ap-southeast-1",
)
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; once the quota limit is reached, no more voices can be created.
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 Singapore (ap-southeast-1) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not set 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="ap-southeast-1",
)
# Filter by prefix, or set to None to list all
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}")
Query a specific voice
import os
import dashscope
# The following is the configuration for the Singapore (ap-southeast-1) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not set 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="ap-southeast-1",
)
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}")
Update a voice
import os
import dashscope
# The following is the configuration for the Singapore (ap-southeast-1) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not set 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="ap-southeast-1",
)
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 Singapore (ap-southeast-1) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration differs by region.
client = dashscope.Client(
# If you have not set 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="ap-southeast-1",
)
result = client.audio.voices.delete(voice_id='qwen-audio-3.0-tts-flash-myvoice-xxxxxxxx')
print(f"Deletion submitted. Request ID: {result.request_id}")