Voice cloning API reference

​

Audio requirements

​

Quick start

​

1. Workflow

1. Create a voice Call the Create a voice API and upload an audio clip. The system analyzes the audio and creates a custom cloned voice. You must specifytarget_modelin this step to declare which omni model will drive the voice. If you already have a created voice (call the List voices API to check), skip this step and proceed to the next one.
2. Use the voice in a conversation Call the Omni API (realtime or non-realtime) and pass in the voice obtained in the previous step. The omni model specified in this step must match thetarget_modelfrom the previous step.

​

2. Model configuration and prerequisites

​

Model configuration

• Voice cloning model: qwen-voice-enrollment
• Omni model that drives the voice:
  • qwen3.5-omni-plus-realtime
  • qwen3.5-omni-flash-realtime
  • qwen3.5-omni-plus
  • qwen3.5-omni-flash

​

Prerequisites

1. Get an API key: Obtain an API key. For security, configure the API key as an environment variable.
2. Install the SDK: Make sure you have installed the latest DashScope SDK.
3. Prepare the audio for cloning: The audio must meet the Audio requirements.

​

3. End-to-end example

# Requirements: dashscope >= 1.23.9, pyaudio
import os
import requests
import base64
import pathlib
import time
import pyaudio
from dashscope.audio.qwen_omni import MultiModality, OmniRealtimeCallback, OmniRealtimeConversation
import dashscope
# China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# ======= Configuration =======
DEFAULT_TARGET_MODEL = "qwen3.5-omni-plus-realtime"  # Must be the same model for cloning and conversation
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # Path to the local audio file for voice cloning

def create_voice(file_path: str,
                 target_model: str = DEFAULT_TARGET_MODEL,
                 preferred_name: str = DEFAULT_PREFERRED_NAME,
                 audio_mime_type: str = DEFAULT_AUDIO_MIME_TYPE) -> str:
    """
    Create a custom voice and return the voice parameter.
    """
    # API keys differ between the Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If you haven't set an environment variable, replace the following line with: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")

    file_path_obj = pathlib.Path(file_path)
    if not file_path_obj.exists():
        raise FileNotFoundError(f"Audio file not found: {file_path}")

    base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
    data_uri = f"data:{audio_mime_type};base64,{base64_str}"

    # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization"
    payload = {
        "model": "qwen-voice-enrollment",
        "input": {
            "action": "create",
            "target_model": target_model,
            "preferred_name": preferred_name,
            "audio": {"data": data_uri}
        }
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    resp = requests.post(url, json=payload, headers=headers)
    if resp.status_code != 200:
        raise RuntimeError(f"Failed to create voice: {resp.status_code}, {resp.text}")

    try:
        return resp.json()["output"]["voice"]
    except (KeyError, ValueError) as e:
        raise RuntimeError(f"Failed to parse voice response: {e}")

class SimpleCallback(OmniRealtimeCallback):
    def __init__(self, pya):
        self.pya = pya
        self.out = None
    def on_open(self):
        self.out = self.pya.open(
            format=pyaudio.paInt16,
            channels=1,
            rate=24000,
            output=True
        )
    def on_event(self, response):
        if response['type'] == 'response.audio.delta':
            self.out.write(base64.b64decode(response['delta']))
        elif response['type'] == 'conversation.item.input_audio_transcription.completed':
            print(f"[User] {response['transcript']}")
        elif response['type'] == 'response.audio_transcript.done':
            print(f"[LLM] {response['transcript']}")

if __name__ == '__main__':
    # If you haven't set an environment variable, replace the following line with: dashscope.api_key = "sk-xxx"
    dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
    # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    url = "wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/realtime"

    # Step 1: Clone a voice
    voice = create_voice(VOICE_FILE_PATH)
    print(f"Voice cloning complete. Voice: {voice}")

    # Step 2: Start a real-time conversation with the cloned voice
    pya = pyaudio.PyAudio()
    callback = SimpleCallback(pya)
    conv = OmniRealtimeConversation(model=DEFAULT_TARGET_MODEL, callback=callback, url=url)
    conv.connect()
    conv.update_session(
        output_modalities=[MultiModality.AUDIO, MultiModality.TEXT],
        voice=voice  # Use the cloned voice
    )
    mic = pya.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
    print("Conversation started. Speak into your microphone (Ctrl+C to exit)...")
    try:
        while True:
            audio_data = mic.read(3200, exception_on_overflow=False)
            conv.append_audio(base64.b64encode(audio_data).decode())
            time.sleep(0.01)
    except KeyboardInterrupt:
        conv.close()
        mic.close()
        callback.out.close()
        pya.terminate()
        print("\nConversation ended")

# Requirements: dashscope >= 1.23.9, soundfile, numpy
import os
import requests
import base64
import pathlib
import numpy as np
import soundfile as sf
import dashscope
# China (Beijing) region. Replace {WorkspaceId} with your Bailian workspace ID. URLs vary by region.
dashscope.base_http_api_url = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1"

# ======= Configuration =======
DEFAULT_TARGET_MODEL = "qwen3.5-omni-plus"  # Voice cloning and non-realtime calls must use the same model
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # Path to the local audio file for voice cloning

def create_voice(file_path: str,
                 target_model: str = DEFAULT_TARGET_MODEL,
                 preferred_name: str = DEFAULT_PREFERRED_NAME,
                 audio_mime_type: str = DEFAULT_AUDIO_MIME_TYPE) -> str:
    """
    Create a custom voice and return the voice parameter.
    """
    # API keys differ between Singapore and Beijing regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
    # If the environment variable is not configured, replace the following line with: api_key = "sk-xxx"
    api_key = os.getenv("DASHSCOPE_API_KEY")

    file_path_obj = pathlib.Path(file_path)
    if not file_path_obj.exists():
        raise FileNotFoundError(f"Audio file not found: {file_path}")

    base64_str = base64.b64encode(file_path_obj.read_bytes()).decode()
    data_uri = f"data:{audio_mime_type};base64,{base64_str}"

    # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization"
    payload = {
        "model": "qwen-voice-enrollment",
        "input": {
            "action": "create",
            "target_model": target_model,
            "preferred_name": preferred_name,
            "audio": {"data": data_uri}
        }
    }
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    resp = requests.post(url, json=payload, headers=headers)
    if resp.status_code != 200:
        raise RuntimeError(f"Failed to create voice: {resp.status_code}, {resp.text}")

    try:
        return resp.json()["output"]["voice"]
    except (KeyError, ValueError) as e:
        raise RuntimeError(f"Failed to parse voice response: {e}")

if __name__ == '__main__':
    # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
    dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

    # 1. Voice cloning: create a custom voice
    voice = create_voice(VOICE_FILE_PATH)
    print(f"Voice cloning complete. Voice: {voice}")

    # 2. Non-realtime conversation with the cloned voice
    messages = [{"role": "user", "content": [{"text": "Hello, please introduce yourself"}]}]

    response = dashscope.MultiModalConversation.call(
        # If the environment variable is not configured, replace with: api_key="sk-xxx"
        api_key=os.getenv("DASHSCOPE_API_KEY"),
        model=DEFAULT_TARGET_MODEL,
        messages=messages,
        modalities=["text", "audio"],
        audio={"voice": voice, "format": "wav"},  # Use the cloned voice
        stream=True
    )

    print("Model response:")
    audio_base64_string = ""
    for r in response:
        try:
            content = r.output.choices[0].message.content
            for item in content:
                if isinstance(item, dict):
                    if "audio" in item:
                        audio_base64_string += item["audio"].get("data", "")
                    elif "text" in item:
                        print(item["text"], end="")
        except Exception:
            pass

    if audio_base64_string:
        wav_bytes = base64.b64decode(audio_base64_string)
        audio_np = np.frombuffer(wav_bytes, dtype=np.int16)
        sf.write("audio_cloned.wav", audio_np, samplerate=24000)
        print("\nAudio saved to: audio_cloned.wav")

​

API reference

​

Create a voice

• URL North China 2 (Beijing):

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

• Request headers

  Parameter	Type	Required	Description
  Authorization	string	Supported	Authentication token in the format Bearer <your_api_key>. Replace <your_api_key> with your actual API key.
  Content-Type	string	Supported	Media type of the request body. Set to application/json.

• Request body The request body includes all parameters. Omit optional fields as needed. Note the distinction between:
  model: The voice cloning model. Set to qwen-voice-enrollment.target_model: The omni model that drives the voice. This must match the model used in the subsequent real-time multimodal API call. Otherwise, synthesis fails.

{
    "model": "qwen-voice-enrollment",
    "input": {
        "action": "create",
        "target_model": "qwen3.5-omni-plus-realtime",
        "preferred_name": "guanyu",
        "audio": {
            "data": "https://xxx.wav"
        },
        "text": "Optional. The transcript of the audio in audio.data.",
        "language": "Optional. The language of the audio in audio.data, such as zh."
    }
}

• Request parameters

  Parameter	Type	Default	Required	Description
  model	string		Supported	The voice cloning model. Set to qwen-voice-enrollment.
  action	string		Supported	The action type. Set to create.
  target_model	string		Supported	The omni model that drives the voice: qwen3.5-omni-plus-realtime qwen3.5-omni-flash-realtime qwen3.5-omni-plus qwen3.5-omni-flash This must match the omni model used in the subsequent API call. Otherwise, synthesis fails.
  preferred_name	string		Supported	A human-readable name for the voice. Allowed characters: digits, letters, underscores. Maximum: 16 characters. This keyword appears in the final voice name. For example, if the keyword is "guanyu", the resulting voice name is "qwen-omni-vc-guanyu-voice-20250812105009984-838b".
  audio.data	string		Supported	The audio for cloning (follow the Recording guide when recording, and make sure the audio meets the Audio requirements).Submit audio data in one of the following ways: Data URL Format: data:<mediatype>;base64,<data> <mediatype>: The MIME type WAV: audio/wav MP3: audio/mpeg M4A: audio/mp4 <data>: The Base64-encoded string of the audio Base64 encoding increases file size. Keep the encoded result under 10 MB. Example: data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9 View sample code Python Copy import base64, pathlib # input.mp3 is the local audio file for voice cloning. Replace with your own file path. Make sure the file meets the audio requirements. file_path = pathlib.Path("input.mp3") base64_str = base64.b64encode(file_path.read_bytes()).decode() data_uri = f"data:audio/mpeg;base64,{base64_str}" Audio URL (we recommend uploading your audio to OSS) File size must not exceed 10 MB. The URL must be publicly accessible without authentication.
  text	string		Unsupported	The transcript that matches the audio in audio.data.When provided, the server validates the audio against the text. If the mismatch is too large, an Audio.PreprocessError is returned.
  language	string		Unsupported	The language of the audio in audio.data.Supported values: zh (Chinese), en (English), de (German), it (Italian), pt (Portuguese), es (Spanish), ja (Japanese), ko (Korean), fr (French), ru (Russian), th (Thai), id (Indonesian), ar (Arabic), cs (Czech), da (Danish), nl (Dutch), fi (Finnish), he (Hebrew), hi (Hindi), is (Icelandic), ms (Malay), no (Norwegian), fa (Persian), pl (Polish), sv (Swedish), tl (Tagalog), tr (Turkish), ur (Urdu), vi (Vietnamese).Chinese dialects: Dongbei, Shannxi, Sichuan, Henan, Changsha, Tianjin, Hangzhou, Liaoning, Shenyang, Anshan.Set this to the actual language of the audio used for cloning.

• Response parameters
  View response example

  Copy

  {
      "output": {
          "voice": "yourVoice",
          "target_model": "qwen3.5-omni-plus-realtime"
      },
      "usage": {
          "count": 1
      },
      "request_id": "yourRequestId"
  }
  
  Key response parameters:

  Parameter	Type	Description
  voice	string	The voice name. Use this value directly as the voice parameter in the real-time multimodal API.
  target_model	string	The omni model that drives the voice: qwen3.5-omni-plus-realtime qwen3.5-omni-flash-realtime This must match the model used in the subsequent real-time multimodal API call. Otherwise, synthesis fails.
  request_id	string	Request ID.
  count	integer	The number of "create voice" operations billed for this request. The cost is $ count × 0.01. When creating a voice, count is always 1.

• Sample code
  model: The voice cloning model. Set to qwen-voice-enrollment.target_model: The omni model that drives the voice. This must match the model used in the subsequent real-time multimodal API call. Otherwise, synthesis fails.
  • curl
  • python
  • java

  If you have not set the API key as an environment variable, you must replace $DASHSCOPE_API_KEY in the example with your actual API key.

  Copy

  # ======= Important =======
  # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
  # API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # === Remove these comments before running ===
  
  curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization' \
  --header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "model": "qwen-voice-enrollment",
      "input": {
          "action": "list",
          "page_size": 10,
          "page_index": 0
      }
  }'
  

  Copy

  import os
  import requests
  
  # API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # If you haven't set an environment variable, replace the following line with: api_key = "sk-xxx"
  api_key = os.getenv("DASHSCOPE_API_KEY")
  # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
  url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization"
  
  payload = {
      "model": "qwen-voice-enrollment", # Do not modify
      "input": {
          "action": "list",
          "page_size": 10,
          "page_index": 0
      }
  }
  
  headers = {
      "Authorization": f"Bearer {api_key}",
      "Content-Type": "application/json"
  }
  
  response = requests.post(url, json=payload, headers=headers)
  
  print("HTTP status:", response.status_code)
  
  if response.status_code == 200:
      data = response.json()
      voice_list = data["output"]["voice_list"]
  
      print("Voice list:")
      for item in voice_list:
          print(f"- Voice: {item['voice']}  Created: {item['gmt_create']}  Model: {item['target_model']}")
  else:
      print("Request failed:", response.text)
  

  Copy

  import com.google.gson.Gson;
  import com.google.gson.JsonArray;
  import com.google.gson.JsonObject;
  
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  
  public class Main {
      public static void main(String[] args) {
          // API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
          // If you haven't set an environment variable, replace the following line with: String apiKey = "sk-xxx"
          String apiKey = System.getenv("DASHSCOPE_API_KEY");
          // The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
          String apiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization";
  
          // JSON request body
          String jsonPayload =
                  "{"
                          + "\"model\": \"qwen-voice-enrollment\"," // Do not modify
                          + "\"input\": {"
                          +     "\"action\": \"list\","
                          +     "\"page_size\": 10,"
                          +     "\"page_index\": 0"
                          + "}"
                          + "}";
  
          try {
              HttpURLConnection con = (HttpURLConnection) new URL(apiUrl).openConnection();
              con.setRequestMethod("POST");
              con.setRequestProperty("Authorization", "Bearer " + apiKey);
              con.setRequestProperty("Content-Type", "application/json");
              con.setDoOutput(true);
  
              try (OutputStream os = con.getOutputStream()) {
                  os.write(jsonPayload.getBytes("UTF-8"));
              }
  
              int status = con.getResponseCode();
              BufferedReader br = new BufferedReader(new InputStreamReader(
                      status >= 200 && status < 300 ? con.getInputStream() : con.getErrorStream(), "UTF-8"));
  
              StringBuilder response = new StringBuilder();
              String line;
              while ((line = br.readLine()) != null) {
                  response.append(line);
              }
              br.close();
  
              System.out.println("HTTP status: " + status);
              System.out.println("Response JSON: " + response.toString());
  
              if (status == 200) {
                  Gson gson = new Gson();
                  JsonObject jsonObj = gson.fromJson(response.toString(), JsonObject.class);
                  JsonArray voiceList = jsonObj.getAsJsonObject("output").getAsJsonArray("voice_list");
  
                  System.out.println("\n Voice list:");
                  for (int i = 0; i < voiceList.size(); i++) {
                      JsonObject voiceItem = voiceList.get(i).getAsJsonObject();
                      String voice = voiceItem.get("voice").getAsString();
                      String gmtCreate = voiceItem.get("gmt_create").getAsString();
                      String targetModel = voiceItem.get("target_model").getAsString();
  
                      System.out.printf("- Voice: %s  Created: %s  Model: %s\n",
                              voice, gmtCreate, targetModel);
                  }
              }
  
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  

​

List voices

• URL North China 2 (Beijing):

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

• Request headers

  Parameter	Type	Required	Description
  Authorization	string	Supported	Authentication token in the format Bearer <your_api_key>. Replace <your_api_key> with your actual API key.
  Content-Type	string	Supported	Media type of the request body. Set to application/json.

• Request parameters

  Parameter	Type	Default	Required	Description
  model	string	-	Supported	The voice cloning model. Set to qwen-voice-enrollment.
  action	string	-	Supported	The action type. Set to list.
  page_index	integer	0	Unsupported	Page number index. Valid values: 0 to 1,000,000.
  page_size	integer	10	Unsupported	Number of items per page. Valid values: 0 to 1,000,000.

• Response parameters
  View response example

  Copy

  {
      "output": {
          "voice_list": [
              {
                  "voice": "yourVoice1",
                  "gmt_create": "2025-08-11 17:59:32",
                  "target_model": "qwen3.5-omni-plus-realtime"
              },
              {
                  "voice": "yourVoice2",
                  "gmt_create": "2025-08-11 17:38:10",
                  "target_model": "qwen3.5-omni-plus-realtime"
              }
          ]
      },
      "usage": {
          "count": 0
      },
      "request_id": "yourRequestId"
  }
  
  Key response parameters:

  Parameter	Type	Description
  voice	string	The voice name. Use this value directly in the voice parameter of the real-time multimodal API.
  gmt_create	string	The time when the voice was created.
  target_model	string	The omni model that drives the voice: qwen3.5-omni-plus-realtime qwen3.5-omni-flash-realtime qwen3.5-omni-plus qwen3.5-omni-flash This must match the omni model used in the subsequent API call. Otherwise, synthesis fails.
  request_id	string	Request ID.
  count	integer	This request is charged based on the actual number of 'Create Voice' operations. The cost for this request is $ count × 0.01 . Listing voices is free. count is always 0.

• Sample code
  model: The voice cloning model. The value is fixed as qwen-voice-enrollment. Do not modify this value.
  • cURL
  • Python
  • Java

  If you have not set the API key as an environment variable, you must replace $DASHSCOPE_API_KEY in the example with your actual API key.

  Copy

  # ======= Important =======
  # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
  # API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # === Remove these comments before running ===
  
  curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization' \
  --header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "model": "qwen-voice-enrollment",
      "input": {
          "action": "list",
          "page_size": 10,
          "page_index": 0
      }
  }'
  

  Copy

  import os
  import requests
  
  # API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # If you haven't set an environment variable, replace the following line with: api_key = "sk-xxx"
  api_key = os.getenv("DASHSCOPE_API_KEY")
  # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
  url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization"
  
  payload = {
      "model": "qwen-voice-enrollment", # Do not modify
      "input": {
          "action": "list",
          "page_size": 10,
          "page_index": 0
      }
  }
  
  headers = {
      "Authorization": f"Bearer {api_key}",
      "Content-Type": "application/json"
  }
  
  response = requests.post(url, json=payload, headers=headers)
  
  print("HTTP status:", response.status_code)
  
  if response.status_code == 200:
      data = response.json()
      voice_list = data["output"]["voice_list"]
  
      print("Voice list:")
      for item in voice_list:
          print(f"- Voice: {item['voice']}  Created: {item['gmt_create']}  Model: {item['target_model']}")
  else:
      print("Request failed:", response.text)
  

  Copy

  import com.google.gson.Gson;
  import com.google.gson.JsonArray;
  import com.google.gson.JsonObject;
  
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  
  public class Main {
      public static void main(String[] args) {
          // API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
          // If you haven't set an environment variable, replace the following line with: String apiKey = "sk-xxx"
          String apiKey = System.getenv("DASHSCOPE_API_KEY");
          // The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
          String apiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization";
  
          // JSON request body
          String jsonPayload =
                  "{"
                          + "\"model\": \"qwen-voice-enrollment\"," // Do not modify
                          + "\"input\": {"
                          +     "\"action\": \"list\","
                          +     "\"page_size\": 10,"
                          +     "\"page_index\": 0"
                          + "}"
                          + "}";
  
          try {
              HttpURLConnection con = (HttpURLConnection) new URL(apiUrl).openConnection();
              con.setRequestMethod("POST");
              con.setRequestProperty("Authorization", "Bearer " + apiKey);
              con.setRequestProperty("Content-Type", "application/json");
              con.setDoOutput(true);
  
              try (OutputStream os = con.getOutputStream()) {
                  os.write(jsonPayload.getBytes("UTF-8"));
              }
  
              int status = con.getResponseCode();
              BufferedReader br = new BufferedReader(new InputStreamReader(
                      status >= 200 && status < 300 ? con.getInputStream() : con.getErrorStream(), "UTF-8"));
  
              StringBuilder response = new StringBuilder();
              String line;
              while ((line = br.readLine()) != null) {
                  response.append(line);
              }
              br.close();
  
              System.out.println("HTTP status: " + status);
              System.out.println("Response JSON: " + response.toString());
  
              if (status == 200) {
                  Gson gson = new Gson();
                  JsonObject jsonObj = gson.fromJson(response.toString(), JsonObject.class);
                  JsonArray voiceList = jsonObj.getAsJsonObject("output").getAsJsonArray("voice_list");
  
                  System.out.println("\n Voice list:");
                  for (int i = 0; i < voiceList.size(); i++) {
                      JsonObject voiceItem = voiceList.get(i).getAsJsonObject();
                      String voice = voiceItem.get("voice").getAsString();
                      String gmtCreate = voiceItem.get("gmt_create").getAsString();
                      String targetModel = voiceItem.get("target_model").getAsString();
  
                      System.out.printf("- Voice: %s  Created: %s  Model: %s\n",
                              voice, gmtCreate, targetModel);
                  }
              }
  
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  

​

Delete a voice

• URL North China 2 (Beijing):

POST https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/tts/customization

POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization

• Request headers

  Parameter	Type	Required	Description
  Authorization	string	Supported	Authentication token in the format Bearer <your_api_key>. Replace <your_api_key> with your actual API key.
  Content-Type	string	Supported	Media type of the request body. Set to application/json.

• Request body Omit optional fields as needed.
  model: The voice cloning model. The value is fixed as qwen-voice-enrollment. Do not modify this value.

{
    "model": "qwen-voice-enrollment",
    "input": {
        "action": "delete",
        "voice": "yourVoice"
    }
}

• Request parameters

  Parameter	Type	Default	Required	Description
  model	string	-	Supported	The voice cloning model. Set to qwen-voice-enrollment.
  action	string	-	Supported	The action type. Set to delete.
  voice	string	-	Supported	The voice to delete.

• Response parameters
  View response example

  Copy

  {
      "usage": {
          "count": 0
      },
      "request_id": "yourRequestId"
  }
  
  Key response parameters:

  Parameter	Type	Description
  request_id	string	Request ID.
  count	integer	This request is charged based on the actual number of 'Create Voice' operations. The cost for this request is $ count × 0.01 . Deleting a voice is free. count is always 0.

• Sample code
  model: The voice cloning model. The value is fixed as qwen-voice-enrollment. Do not modify this value.
  • cURL
  • Python
  • Java

  If you have not set the API key as an environment variable, you must replace $DASHSCOPE_API_KEY in the example with your actual API key.

  Copy

  # ======= Important =======
  # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
  # API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # === Remove these comments before running ===
  
  curl --location --request POST 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization' \
  --header 'Authorization: Bearer $DASHSCOPE_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
      "model": "qwen-voice-enrollment",
      "input": {
          "action": "delete",
          "voice": "yourVoice"
      }
  }'
  

  Copy

  import os
  import requests
  
  # API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
  # If you haven't set an environment variable, replace the following line with: api_key = "sk-xxx"
  api_key = os.getenv("DASHSCOPE_API_KEY")
  # The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
  url = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization"
  
  voice_to_delete = "yourVoice"  # Replace with the actual voice name
  
  payload = {
      "model": "qwen-voice-enrollment", # Do not modify
      "input": {
          "action": "delete",
          "voice": voice_to_delete
      }
  }
  
  headers = {
      "Authorization": f"Bearer {api_key}",
      "Content-Type": "application/json"
  }
  
  response = requests.post(url, json=payload, headers=headers)
  
  print("HTTP status:", response.status_code)
  
  if response.status_code == 200:
      data = response.json()
      request_id = data["request_id"]
  
      print(f"Deleted successfully")
      print(f"Request ID: {request_id}")
  else:
      print("Request failed:", response.text)
  

  Copy

  import com.google.gson.Gson;
  import com.google.gson.JsonObject;
  
  import java.io.BufferedReader;
  import java.io.InputStreamReader;
  import java.io.OutputStream;
  import java.net.HttpURLConnection;
  import java.net.URL;
  
  public class Main {
      public static void main(String[] args) {
          // API keys differ between regions. Get an API key: https://www.alibabacloud.com/help/en/model-studio/get-api-key
          // If you haven't set an environment variable, replace the following line with: String apiKey = "sk-xxx"
          String apiKey = System.getenv("DASHSCOPE_API_KEY");
          // The following is the Singapore region URL. Replace {WorkspaceId} with your actual workspace ID. URLs vary by region.
          String apiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/tts/customization";
          String voiceToDelete = "yourVoice"; // Replace with the actual voice name
  
          // Build JSON request body
          String jsonPayload =
                  "{"
                          + "\"model\": \"qwen-voice-enrollment\"," // Do not modify
                          + "\"input\": {"
                          +     "\"action\": \"delete\","
                          +     "\"voice\": \"" + voiceToDelete + "\""
                          + "}"
                          + "}";
  
          try {
              // Create POST connection
              HttpURLConnection con = (HttpURLConnection) new URL(apiUrl).openConnection();
              con.setRequestMethod("POST");
              con.setRequestProperty("Authorization", "Bearer " + apiKey);
              con.setRequestProperty("Content-Type", "application/json");
              con.setDoOutput(true);
  
              // Send request body
              try (OutputStream os = con.getOutputStream()) {
                  os.write(jsonPayload.getBytes("UTF-8"));
              }
  
              int status = con.getResponseCode();
              BufferedReader br = new BufferedReader(new InputStreamReader(
                      status >= 200 && status < 300 ? con.getInputStream() : con.getErrorStream(), "UTF-8"));
  
              StringBuilder response = new StringBuilder();
              String line;
              while ((line = br.readLine()) != null) {
                  response.append(line);
              }
              br.close();
  
              System.out.println("HTTP status: " + status);
              System.out.println("Response JSON: " + response.toString());
  
              if (status == 200) {
                  Gson gson = new Gson();
                  JsonObject jsonObj = gson.fromJson(response.toString(), JsonObject.class);
                  String requestId = jsonObj.get("request_id").getAsString();
  
                  System.out.println("Deleted successfully");
                  System.out.println("Request ID: " + requestId);
              }
  
          } catch (Exception e) {
              e.printStackTrace();
          }
      }
  }
  

​

Use in conversation

​

Voice quota and auto-cleanup

No dedicated count endpoint exists. Call the List voices API to count your voices.

​

Billing

• Voice cloning: billed at $0.01/voice. Failed creations are not billed.
  Free quota (China site Beijing region and International site Singapore region only):

  • 1,000 free voice creations within 90 days of activating Model Studio.
  • Failed creations don't consume the free quota.
  • Deleting a voice doesn't restore the free quota.
  • After the free quota is used up or the 90-day period expires, voice creation is billed at $0.01/voice.
• Conversation with a cloned voice: Billed by token usage for model invocation. For details, see Model inference pricing.

​

Copyright and legal compliance

​

Recording guide

​

Recording equipment

​

Recording environment

​

Location

• Record in a small enclosed space of 10 square meters or less.
• Choose a room with sound-absorbing materials such as acoustic foam, carpets, or curtains.
• Avoid large open halls, conference rooms, or classrooms where reverberation is high.

​

Noise control

• Outdoor noise: Close doors and windows to block traffic, construction, and other external sounds.
• Indoor noise: Turn off air conditioners, fans, and fluorescent light ballasts.
• Record ambient sound with your phone and play it back at high volume to identify hidden noise sources.

​

Reverberation control

• Reverberation causes audio to sound muffled and reduces clarity.
• Reduce reflections from smooth surfaces: close curtains, open wardrobe doors, and cover desks and shelves with clothing or blankets.
• Use irregular objects such as bookshelves and upholstered furniture to create diffuse reflections.

​

Script preparation

• Match the script to the target use case. For example, use customer service dialog style for a customer service scenario.
• Make sure the script doesn't contain sensitive or illegal content (such as political, pornographic, or violent material), as this causes cloning to fail.
• Avoid short phrases (such as "hello" or "yes"). Use complete sentences.
• Maintain semantic coherence and avoid frequent pauses when reading. At least 3 consecutive seconds without interruption is recommended.
• You can convey the target emotion (such as friendly or serious), but avoid overly dramatic or theatrical delivery. Keep the tone natural.

​

Recommended steps

1. Close doors and windows to block external noise.
2. Turn off air conditioners, fans, and other appliances.
3. Close curtains to reduce glass reflections.
4. Cover the desk surface with clothing or a blanket to reduce desktop reflections.
5. Familiarize yourself with the script, set the character's tone, and deliver naturally.
6. Maintain about 10 cm distance from the recording device to avoid plosive distortion or weak signal.

​

Error messages