Qwen-Audio and CosyVoice voice cloning Python SDK reference

Updated at:

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 that Client.

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

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

ParameterTypeRequiredDescription

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:

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