Alibaba Cloud Model Studio:Voice Design

Create custom voices from natural language descriptions, preview them, and use them for speech synthesis.

Overview

Voice design is suited for rapid prototyping, creative content production, and game character voiceovers.

Before you begin

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

• Obtain your workspace ID and replace YOUR_WORKSPACE_ID in the example with it. For instructions, see Regions, deployment scope, and endpoints.

• Install the DashScope SDK and requests:

  pip install -U dashscope requests
  

Get started

Qwen-Audio-TTS and CosyVoice share the same voice creation, preview, and basic synthesis workflow. The following example uses qwen-audio-3.1-tts-flash.

1. Create a voice: Set the voice description voice_prompt, preview text preview_text, and target model target_model to obtain a voice ID.
2. Save the preview audio: Decode the returned preview_audio.data and save it as a WAV file for listening.
3. Synthesize speech: Pass the returned voice_id as voice and synthesize speech with the bound model.

import base64
import os

import dashscope
import requests
from dashscope.audio.tts_v2 import AudioFormat, SpeechSynthesizer

api_key = os.environ["DASHSCOPE_API_KEY"]
workspace_id = "YOUR_WORKSPACE_ID"
target_model = "qwen-audio-3.1-tts-flash"

# Create a voice and save the returned preview audio.
response = requests.post(
    f"https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "model": "voice-enrollment",
        "input": {
            "action": "create_voice",
            "target_model": target_model,
            "voice_prompt": "A calm middle-aged male announcer with a deep, resonant voice, steady speaking pace, and clear articulation, suited for news broadcasts or documentaries.",
            "preview_text": "Good evening, everyone. Welcome to the evening news.",
            "prefix": "announcer",
            "language_hints": ["en"],
        },
        "parameters": {"sample_rate": 24000, "response_format": "wav"},
    },
    timeout=120,
)
response.raise_for_status()
output = response.json()["output"]
voice_id = output["voice_id"]
print(f"voice_id: {voice_id}")
with open("preview.wav", "wb") as f:
    f.write(base64.b64decode(output["preview_audio"]["data"]))

# Synthesize speech with the same target model and the returned voice ID.
dashscope.api_key = api_key
dashscope.base_websocket_api_url = (
    f"wss://{workspace_id}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference"
)
synthesizer = SpeechSynthesizer(
    model=target_model,
    voice=voice_id,
    format=AudioFormat.WAV_24000HZ_MONO_16BIT,
)
audio = synthesizer.call("The weather is clear today, perfect for a walk outside. Have a wonderful day.")
with open("output.wav", "wb") as f:
    f.write(audio)

The example saves the preview audio to preview.wav and the synthesized audio to output.wav. Save the printed voice ID for subsequent speech synthesis calls.

For HTTP request examples, optional parameters, and response fields, see the Voice design API reference. For synthesis parameters, see the Qwen-Audio-TTS client events.

Voice description guide

The voice description (voice_prompt) specifies the desired voice qualities. Clear, specific descriptions help generate voices that meet your needs.

Description guidelines

• Be specific: Use voice qualities such as "deep," "crisp," or "fast-paced." Avoid vague judgments such as "nice" or "normal."
• Combine dimensions: Describe gender, age, pitch, speed, and emotion. "Female voice" alone provides little detail about a distinctive voice.
• Be objective: Describe perceptible qualities, such as "high-pitched and energetic," rather than subjective preferences such as "my favorite voice."
• Be original: Describe voice qualities without requesting imitation of a specific person, such as a celebrity or actor. The model does not support targeted imitation, and such requests may raise copyright concerns.
• Be concise: Remove repeated synonyms and unnecessary modifiers.

Combine the following dimensions in a voice description:

Dimension	Examples
Gender	Male, female, neutral
Age	Child (5-12), teenager (13-18), young adult (19-35), middle-aged (36-55), senior (55+)
Pitch	High, medium, low, slightly high, slightly low
Speed	Fast, medium, slow, slightly fast, slightly slow
Emotion	Cheerful, calm, gentle, serious, lively, composed, soothing
Characteristics	Resonant, crisp, husky, mellow, sweet, deep, powerful
Use case	News broadcast, advertising, audiobook, animation character, voice assistant, documentary narration

Description examples

• Standard broadcast style: clear and precise articulation with perfect enunciation
• Young and lively female voice, fast-paced with a noticeable rising intonation, suited for fashion product presentations
• Calm, slow-paced middle-aged male voice, deep and resonant, suited for news reading or documentary narration
• Gentle and thoughtful female, around 30 years old, even-toned, suited for audio book reading
• Cute child's voice, approximately an 8-year-old girl, slightly childish speech, suited for animation character voiceover

Voice management

• List voices: View existing custom voices.
• Query voice details: View the bound model, voice status, and other information.
• Delete a voice: Delete voices that are no longer needed to free up quota.

For interfaces and parameters, see the Voice design API reference.

Supported models

China (Beijing)

Use an API key from this region to call the following models:

• Qwen-Audio-TTS: qwen-audio-3.1-tts-flash, qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash

• CosyVoice: cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-plus, cosyvoice-v3-flash

NoteCosyVoice voice design is powered by the FunAudioGen-VD model.

Quotas and limits

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

  NoteNew voice cloning or voice design creation requests fail when the limit is reached. Delete voices that are no longer needed to free up quota before creating new voices.

• Voice description: voice_prompt supports Chinese and English only, with a maximum length of 500 characters.

• Preview text: preview_text supports Chinese and English only and must be 15–200 characters long.

• Model binding: A voice is bound to a speech synthesis model through target_model at creation. Use the same model for subsequent synthesis.

The generated voice can synthesize speech in multiple languages. The supported languages depend on the target speech synthesis model.

Billing

Voice creation is free.

Speech synthesis with a designed voice is billed according to the target speech synthesis model. For pricing, see Model pricing.