Voice Design

​

Overview

​

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

  pip install -U dashscope requests
  

​

Get started

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)

​

Voice description guide

​

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.

​

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.

​

Supported models

​

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

​

Billing