Referência da API de clonagem de voz

​

Requisitos de áudio

​

Início rápido

​

1. Fluxo de trabalho

1. Crie uma voz Chame a API Create a voice e envie um clipe de áudio. O sistema analisa o áudio e cria uma voz clonada personalizada. Especifiquetarget_modelnesta etapa para declarar qual modelo omni conduzirá a voz. Se já possuir uma voz criada (chame a API List voices para verificar), pule esta etapa e prossiga para a próxima.
2. Use a voz em uma conversa Chame a API Omni (em tempo real ou não) e passe a voz obtida na etapa anterior. O modelo omni especificado nesta etapa deve corresponder aotarget_modelda etapa anterior.

​

2. Configuração do modelo e pré-requisitos

​

Configuração do modelo

• Modelo de clonagem de voz: qwen-voice-enrollment
• Modelo Omni que conduz a voz:
  • qwen3.8-omni-flash-realtime
  • qwen3.5-omni-plus-realtime
  • qwen3.5-omni-flash-realtime
  • qwen3.5-omni-plus
  • qwen3.5-omni-flash

​

Pré-requisitos

1. Obtenha uma chave de API: Obtain an API key. Por segurança, configure a chave de API como variável de ambiente.
2. Instale o SDK: Certifique-se de ter instalado a versão mais recente do DashScope SDK.
3. Prepare o áudio para clonagem: O áudio deve atender aos requisitos de áudio.

​

3. Exemplo de ponta a ponta

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

​

Referência da API

​

Criar uma voz

• 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

• Cabeçalhos da solicitação

  Parameter	Tipo	Obrigatório	Descrição
  Authorization	string	Supported	Token de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.
  Content-Type	string	Supported	Tipo de mídia do corpo da solicitação. Defina como application/json.

• Corpo da solicitação O corpo da solicitação inclui todos os parâmetros. Omita campos opcionais conforme necessário. Observe a distinção entre:
  model: O modelo de clonagem de voz. Defina como qwen-voice-enrollment.target_model: O modelo omni que conduz a voz. Este deve corresponder ao modelo usado na chamada subsequente da API multimodal em tempo real. Caso contrário, a síntese falhará.

{
    "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."
    },
    "parameters": {
        "voice_clone_mode": "normal",
        "skip_audio_process": false
    }
}

• Parâmetros da solicitação

  Parâmetro	Tipo	Padrão	Obrigatório	Descrição
  model	string		Supported	O modelo de clonagem de voz. Defina como qwen-voice-enrollment.
  action	string		Supported	O tipo de ação. Defina como create.
  target_model	string		Supported	O modelo omni que conduz a voz: qwen3.8-omni-flash-realtime qwen3.5-omni-plus-realtime qwen3.5-omni-flash-realtime qwen3.5-omni-plus qwen3.5-omni-flash Este deve corresponder ao modelo omni usado na chamada subsequente da API. Caso contrário, a síntese falhará.
  preferred_name	string		Supported	Um nome legível para a voz. Caracteres permitidos: dígitos, letras, sublinhados. Máximo: 16 caracteres. Esta palavra-chave aparece no nome final da voz. Por exemplo, se a palavra-chave for "guanyu", o nome da voz resultante será "qwen-omni-vc-guanyu-voice-20250812105009984-838b".
  audio.data	string		Supported	O áudio para clonagem (siga o guia de gravação ao gravar e certifique-se de que o áudio atenda aos requisitos de áudio).Envie os dados de áudio de uma das seguintes formas: Data URL Formato: data:<mediatype>;base64,<data> <mediatype>: O tipo MIME WAV: audio/wav MP3: audio/mpeg M4A: audio/mp4 <data>: A string codificada em Base64 do áudio A codificação Base64 aumenta o tamanho do arquivo. Mantenha o resultado codificado abaixo de 10 MB. Exemplo: data:audio/wav;base64,SUQzBAAAAAAAI1RTU0UAAAAPAAADTGF2ZjU4LjI5LjEwMAAAAAAAAAAAAAAA//PAxABQ/BXRbMPe4IQAhl9 Ver código de exemplo 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}" URL do áudio (recomendamos enviar seu áudio para o OSS) O tamanho do arquivo não deve exceder 10 MB. A URL deve ser publicamente acessível sem autenticação.
  text	string		Unsupported	A transcrição correspondente ao áudio em audio.data.Quando fornecida, o servidor valida o áudio em relação ao texto. Se a discrepância for muito grande, um Audio.PreprocessError será retornado.
  language	string		Unsupported	O idioma do áudio em audio.data.Valores suportados: zh (Chinês), en (Inglês), de (Alemão), it (Italiano), pt (Português), es (Espanhol), ja (Japonês), ko (Coreano), fr (Francês), ru (Russo), th (Tailandês), id (Indonésio), ar (Árabe), cs (Tcheco), da (Dinamarquês), nl (Holandês), fi (Finlandês), he (Hebraico), hi (Hindi), is (Islandês), ms (Malaio), no (Norueguês), fa (Persa), pl (Polonês), sv (Sueco), tl (Tagalo), tr (Turco), ur (Urdu), vi (Vietnamita).Dialetos chineses: Dongbei, Shannxi, Sichuan, Henan, Changsha, Tianjin, Hangzhou, Liaoning, Shenyang, Anshan.Defina este campo como o idioma real do áudio usado para clonagem.

• Parâmetros de resposta
  Ver exemplo de resposta

  Copy

  {
      "output": {
          "voice": "yourVoice",
          "target_model": "qwen3.5-omni-plus-realtime"
      },
      "usage": {
          "count": 1
      },
      "request_id": "yourRequestId"
  }
  
  Principais parâmetros de resposta:

  Parâmetro	Tipo	Descrição
  voice	string	O nome da voz. Use este valor diretamente como o parâmetro voice na API multimodal em tempo real.
  target_model	string	O modelo omni que conduz a voz: qwen3.8-omni-flash-realtime qwen3.5-omni-plus-realtime qwen3.5-omni-flash-realtime Este deve corresponder ao modelo usado na chamada subsequente da API multimodal em tempo real. Caso contrário, a síntese falhará.
  request_id	string	ID da solicitação.
  count	integer	O número de operações "criar voz" faturadas para esta solicitação. O custo é $ count × 0.01. Ao criar uma voz, count é sempre 1.

• Código de exemplo
  model: O modelo de clonagem de voz. Defina como qwen-voice-enrollment.target_model: O modelo omni que conduz a voz. Este deve corresponder ao modelo usado na chamada subsequente da API multimodal em tempo real. Caso contrário, a síntese falhará.
  • curl
  • python
  • java

  Se você não definiu a chave de API como variável de ambiente, substitua $DASHSCOPE_API_KEY no exemplo pela sua chave de API real.

  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();
          }
      }
  }
  

​

Listar vozes

• 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

• Cabeçalhos da solicitação

  Parameter	Tipo	Obrigatório	Descrição
  Authorization	string	Supported	Token de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.
  Content-Type	string	Supported	Tipo de mídia do corpo da solicitação. Defina como application/json.

• Parâmetros da solicitação

  Parâmetro	Tipo	Padrão	Obrigatório	Descrição
  model	string	-	Supported	O modelo de clonagem de voz. Defina como qwen-voice-enrollment.
  action	string	-	Supported	O tipo de ação. Defina como list.
  page_index	integer	0	Unsupported	Índice do número da página. Valores válidos: 0 a 1.000.000.
  page_size	integer	10	Unsupported	Número de itens por página. Valores válidos: 0 a 1.000.000.

• Parâmetros de resposta
  Ver exemplo de resposta

  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"
  }
  
  Principais parâmetros de resposta:

  Parâmetro	Tipo	Descrição
  voice	string	O nome da voz. Use este valor diretamente no parâmetro voice da API multimodal em tempo real.
  gmt_create	string	O momento em que a voz foi criada.
  target_model	string	O modelo omni que conduz a voz: qwen3.8-omni-flash-realtime qwen3.5-omni-plus-realtime qwen3.5-omni-flash-realtime qwen3.5-omni-plus qwen3.5-omni-flash Este deve corresponder ao modelo omni usado na chamada subsequente da API. Caso contrário, a síntese falhará.
  request_id	string	ID da solicitação.
  count	integer	Esta solicitação é cobrada com base no número real de operações 'Criar Voz'. O custo para esta solicitação é $ count × 0.01 . Listar vozes é gratuito. count é sempre 0.

• Código de exemplo
  model: O modelo de clonagem de voz. O valor é fixo como qwen-voice-enrollment. Não modifique este valor.
  • cURL
  • Python
  • Java

  Se você não definiu a chave de API como variável de ambiente, substitua $DASHSCOPE_API_KEY no exemplo pela sua chave de API real.

  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();
          }
      }
  }
  

​

Excluir uma voz

• 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

• Cabeçalhos da solicitação

  Parameter	Tipo	Obrigatório	Descrição
  Authorization	string	Supported	Token de autenticação no formato Bearer <your_api_key>. Substitua <your_api_key> pela sua chave de API real.
  Content-Type	string	Supported	Tipo de mídia do corpo da solicitação. Defina como application/json.

• Corpo da solicitação Omita campos opcionais conforme necessário.
  model: O modelo de clonagem de voz. O valor é fixo como qwen-voice-enrollment. Não modifique este valor.

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

• Parâmetros da solicitação

  Parâmetro	Tipo	Padrão	Obrigatório	Descrição
  model	string	-	Supported	O modelo de clonagem de voz. Defina como qwen-voice-enrollment.
  action	string	-	Supported	O tipo de ação. Defina como delete.
  voice	string	-	Supported	A voz a ser excluída.

• Parâmetros de resposta
  Ver exemplo de resposta

  Copy

  {
      "usage": {
          "count": 0
      },
      "request_id": "yourRequestId"
  }
  
  Principais parâmetros de resposta:

  Parâmetro	Tipo	Descrição
  request_id	string	ID da solicitação.
  count	integer	Esta solicitação é cobrada com base no número real de operações 'Criar Voz'. O custo para esta solicitação é $ count × 0.01 . Excluir uma voz é gratuito. count é sempre 0.

• Código de exemplo
  model: O modelo de clonagem de voz. O valor é fixo como qwen-voice-enrollment. Não modifique este valor.
  • cURL
  • Python
  • Java

  Se você não definiu a chave de API como variável de ambiente, substitua $DASHSCOPE_API_KEY no exemplo pela sua chave de API real.

  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();
          }
      }
  }
  

​

Usar em conversa

​

Cota de vozes e limpeza automática

Não existe um endpoint dedicado para contagem. Chame a API Listar vozes para contar suas vozes.

​

Faturamento

• Clonagem de voz: faturada a $0,01/voz. Criações com falha não são faturadas.
  Cota gratuita (apenas região de Beijing do site China e região de Singapore do site Internacional):

  • 1.000 criações de voz gratuitas dentro de 90 dias após a ativação do Model Studio.
  • Criações com falha não consomem a cota gratuita.
  • Excluir uma voz não restaura a cota gratuita.
  • Após o esgotamento da cota gratuita ou o término do período de 90 dias, a criação de voz é faturada a $0,01/voz.
• Conversa com uma voz clonada: Faturada pelo uso de tokens na invocação do modelo. Para detalhes, consulte Model inference pricing.

​

Direitos autorais e conformidade legal

​

Guia de gravação

​

Equipamento de gravação

​

Ambiente de gravação

​

Local

• Grave em um espaço pequeno e fechado, com 10 metros quadrados ou menos.
• Escolha uma sala com materiais de absorção sonora, como espuma acústica, carpetes ou cortinas.
• Evite grandes salões abertos, salas de conferência ou salas de aula onde a reverberação seja alta.

​

Controle de ruído

• Ruído externo: Feche portas e janelas para bloquear trânsito, obras e outros sons externos.
• Ruído interno: Desligue ar-condicionados, ventiladores e reatores de lâmpadas fluorescentes.
• Grave o som ambiente com seu telefone e reproduza-o em volume alto para identificar fontes de ruído ocultas.

​

Controle de reverberação

• A reverberação faz o áudio soar abafado e reduz a clareza.
• Reduza reflexões de superfícies lisas: feche cortinas, abra portas de armários e cubra mesas e prateleiras com roupas ou cobertores.
• Use objetos irregulares, como estantes e móveis estofados, para criar reflexões difusas.

​

Preparação do roteiro

• Adapte o roteiro ao caso de uso alvo. Por exemplo, use o estilo de diálogo de atendimento ao cliente para um cenário de suporte.
• Certifique-se de que o roteiro não contenha conteúdo sensível ou ilegal (como material político, pornográfico ou violento), pois isso causa falha na clonagem.
• Evite frases curtas (como "olá" ou "sim"). Use sentenças completas.
• Mantenha a coerência semântica e evite pausas frequentes durante a leitura. Recomenda-se pelo menos 3 segundos consecutivos sem interrupção.
• Você pode transmitir a emoção desejada (como amigável ou séria), mas evite uma entrega excessivamente dramática ou teatral. Mantenha o tom natural.

​

Passos recomendados

1. Feche portas e janelas para bloquear ruídos externos.
2. Desligue ar-condicionados, ventiladores e outros aparelhos.
3. Feche cortinas para reduzir reflexões do vidro.
4. Cubra a superfície da mesa com roupas ou um cobertor para reduzir reflexões da mesa.
5. Familiarize-se com o roteiro, defina o tom do personagem e faça uma entrega natural.
6. Mantenha cerca de 10 cm de distância do dispositivo de gravação para evitar distorção por plosivas ou sinal fraco.

​

Mensagens de erro