Alibaba Cloud Model Studio:Voice cloning

Create a custom voice from an audio sample for speech synthesis or real-time voice conversations.

Feature overview

Voice cloning supports personalized voice assistants, brand-specific announcements, and customized audio content without model training.

Prerequisites

• Obtain an API key and set the environment variable DASHSCOPE_API_KEY.

• Obtain your workspace ID and replace YOUR_WORKSPACE_ID (or {WorkspaceId} in the SDK examples) with the real value. See Regions and endpoints.

• To use the HTTP examples, install the Python HTTP library requests:

  pip install requests
  

• To use the Python SDK examples, install the DashScope SDK (version 2.0.1 or later):

  # The examples in this documentation are based on DashScope Python SDK 2.0; version 2.0.1 or later is required
  pip install -U "dashscope>=2.0.1"
  

• Prepare an audio file that meets the audio requirements. Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice accept a public URL or a Base64 Data URI; MiniMax continues to use a public URL. The examples below use the URL of the sample audio file. For local audio encoding and parameters, see the HTTP API.

Get started

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 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="cn-beijing",
)

target_model = "qwen-audio-3.1-tts-plus"

# Create the voice.
voice = client.audio.voices.create(
    target_model=target_model,
    prefix="myvoice",
    url="https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav",
)
voice_id = voice.voice_id
print(f"voice_id: {voice_id}")

# Synthesize speech with the bound model and the returned voice ID.
audio = client.audio.tts.synthesize(
    "The weather is pleasant today. Enjoy a walk outside and have a wonderful day.",
    model=target_model,
    voice=voice_id,
    format="wav",
    sample_rate=24000,
)
with open("output.wav", "wb") as f:
    f.write(audio)

import os
import time
import requests

workspace_id = "YOUR_WORKSPACE_ID"
target_model = "qwen-audio-3.1-tts-plus"
base_url = f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}

response = requests.post(
    f"{base_url}/services/audio/tts/customization",
    headers=headers,
    json={
        "model": "voice-enrollment",
        "input": {
            "action": "create_voice",
            "target_model": target_model,
            "prefix": "myvoice",
            "audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav",
        },
    },
    timeout=60,
)
response.raise_for_status()
voice_id = response.json()["output"]["voice_id"]
print(f"voice_id: {voice_id}")

for _ in range(30):
    response = requests.post(
        f"{base_url}/services/audio/tts/customization",
        headers=headers,
        json={
            "model": "voice-enrollment",
            "input": {"action": "query_voice", "voice_id": voice_id},
        },
        timeout=60,
    )
    response.raise_for_status()
    status = response.json()["output"]["status"]
    if status == "OK":
        break
    if status != "DEPLOYING":
        raise RuntimeError(f"Voice status: {status}")
    time.sleep(1)
else:
    raise TimeoutError("Voice is not ready")

response = requests.post(
    f"{base_url}/services/audio/tts/SpeechSynthesizer",
    headers=headers,
    json={
        "model": target_model,
        "input": {
            "text": "The weather is pleasant today. Enjoy a walk outside and have a wonderful day.",
            "voice": voice_id,
            "format": "wav",
            "sample_rate": 24000,
        },
    },
    timeout=60,
)
response.raise_for_status()
audio_url = response.json()["output"]["audio"]["url"]
audio_response = requests.get(audio_url, timeout=60)
audio_response.raise_for_status()
with open("output.wav", "wb") as f:
    f.write(audio_response.content)

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 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="cn-beijing",
)

target_model = "qwen-audio-3.1-realtime-plus"

# Create the voice.
voice = client.audio.voices.create(
    target_model=target_model,
    prefix="myvoice",
    url="https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav",
)
print(f"voice_id: {voice.voice_id}")

import os
import time
import requests

workspace_id = "YOUR_WORKSPACE_ID"
target_model = "qwen-audio-3.1-realtime-plus"
base_url = f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['DASHSCOPE_API_KEY']}"}

response = requests.post(
    f"{base_url}/services/audio/tts/customization",
    headers=headers,
    json={
        "model": "voice-enrollment",
        "input": {
            "action": "create_voice",
            "target_model": target_model,
            "prefix": "myvoice",
            "audio": "https://dashscope.oss-cn-beijing.aliyuncs.com/samples/audio/cosyvoice/cosyvoice-zeroshot-sample.wav",
        },
    },
    timeout=60,
)
response.raise_for_status()
voice_id = response.json()["output"]["voice_id"]
print(f"voice_id: {voice_id}")

for _ in range(30):
    response = requests.post(
        f"{base_url}/services/audio/tts/customization",
        headers=headers,
        json={
            "model": "voice-enrollment",
            "input": {"action": "query_voice", "voice_id": voice_id},
        },
        timeout=60,
    )
    response.raise_for_status()
    status = response.json()["output"]["status"]
    if status == "OK":
        break
    if status != "DEPLOYING":
        raise RuntimeError(f"Voice status: {status}")
    time.sleep(1)
else:
    raise TimeoutError("Voice is not ready")

{
    "type": "session.update",
    "session": {
        "voice": "VOICE_ID"
    }
}

For more voice cloning parameters and examples, see the HTTP API, Python SDK, and Java SDK.

To use a cloned voice for speech synthesis or real-time voice conversations, see:

• Qwen-Audio-TTS: Model access
• CosyVoice: Model access
• Qwen-Audio-Realtime: Model access

Audio requirements

Input audio quality affects voice similarity and naturalness. Follow the target model’s specifications and the recording tips below to reduce noise, reverberation, and other speakers’ voices.

Clear, natural recordings help produce high-quality reference audio and preserve voice characteristics. Before recording, review the recording and operation tips below.

Voice management

Qwen-Audio-TTS, Qwen-Audio-Realtime, and CosyVoice share the same voice query, update, and deletion APIs. For interfaces and parameters, see the Voice cloning HTTP API reference.

• List voices: View existing custom voices under your account.
• Query voice details: View information such as creation time and the bound model.
• Update a voice: Replace the reference audio while retaining the existing voice ID.
• Delete a voice: Delete unused voices to free up quota.

Created voices remain valid by default. Save the voice ID and query the voice when needed to check its availability.

Supported models

Quotas and limits

• Voice count: Each Alibaba Cloud Model Studio account can have up to 1,000 custom voices in total. Voice cloning and voice design share this account quota across models.

  Note

  • New voice cloning or voice design creation requests fail when the quota is reached. Delete unused voices to free up quota before creating another voice.

Billing

• Qwen-Audio-TTS / Qwen-Audio-Realtime / CosyVoice: Voice creation is free. Speech synthesis and real-time conversations using cloned voices are billed according to the target model. See Model pricing.