All Products
Search
Document Center

Alibaba Cloud Model Studio:Qwen-Audio and CosyVoice voice cloning Python SDK reference

Last Updated:Nov 10, 2026

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.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • Singapore: from dashscope-intl.aliyuncs.com to {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:

ParameterTypeRequiredDescription

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

Reference audio for voice cloning. Accepts a publicly accessible URL or a Base64 Data URI, such as data:audio/wav;base64,....

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.

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

  • 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:

    • 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.

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 extra_input dictionary. 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: 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:

ParameterTypeRequiredDescription

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:

ParameterTypeRequiredDescription

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:

ParameterTypeRequiredDescription

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 data:audio/wav;base64,....

delete() — Delete a voice

Method signature:

def delete(self, voice_id: str, ...) -> JobStatus

Parameters:

ParameterTypeRequiredDescription

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}")