跳转到主要内容
Qwen-Omni-Realtime

Qwen-Omni 声音复刻

声音复刻 API 参考:上传音频创建定制音色,用于 Qwen-Omni 对话

声音复刻依托大模型进行特征提取,无需训练即可复刻声音。仅需提供 10~20 秒的音频,即可生成高度相似且听感自然的定制音色。声音复刻与模型调用是前后关联的两个步骤。本文档聚焦于介绍声音复刻的参数和接口细节,模型调用请参见实时多模态语音非实时多模态语音 用户指南:关于模型介绍和选型建议请参见实时多模态语音非实时多模态语音
本文档专用于千问Omni和千问Omni-Realtime声音复刻接口;若您使用的是语音合成模型,请参见语音合成声音复刻

音频要求

高质量的输入音频是获得优质复刻效果的基础。
项目要求
支持格式WAV (16bit)、MP3、M4A
音频时长推荐 10~20 秒,最长不超过 60 秒
文件大小< 10 MB
采样率>= 24 kHz
声道单声道
内容音频必须包含至少 3 秒连续清晰朗读(无背景音),其余部分仅允许短暂停顿(<= 2 秒);整段音频应避免背景音乐、噪音或其他人声,确保核心朗读内容质量;请使用正常说话音频作为输入,不要上传歌曲或唱歌音频,以确保复刻效果准确和可用
语言中文(zh)、英文(en)、德语(de)、意大利语(it)、葡萄牙语(pt)、西班牙语(es)、日语(ja)、韩语(ko)、法语(fr)、俄语(ru)、泰语(th)、印尼语(id)、阿拉伯语(ar)、捷克语(cs)、丹麦语(da)、荷兰语(nl)、芬兰语(fi)、希伯来语(he)、印地语(hi)、冰岛语(is)、马来语(ms)、挪威语(no)、波斯语(fa)、波兰语(pl)、瑞典语(sv)、他加禄语(tl)、土耳其语(tr)、乌尔都语(ur)、越南语(vi)。中文方言:东北话(Dongbei)、陕西话(Shannxi)、四川话(Sichuan)、河南话(Henan)、长沙话(Changsha)、天津话(Tianjin)、杭州话(Hangzhou)、辽宁话(Liaoning)、沈阳话(Shenyang)、鞍山话(Anshan)

快速开始:复刻与使用音色

1. 工作流程

声音复刻与模型调用是紧密关联的两个独立步骤,遵循"先创建,后使用"的流程:
  1. 创建音色 调用创建音色接口,上传一段音频。系统会分析该音频,创建一个专属的复刻音色。此步骤必须指定 target_model,声明创建的音色将由哪个全模态模型驱动。 若已有创建好的音色(调用查询音色列表接口查看),可跳过这一步直接进行下一步。
  2. 使用音色进行对话 调用 Omni 接口(实时或非实时),传入上一步获得的音色。此步骤指定的全模态模型必须和上一步的 target_model 一致。

2. 模型配置与准备工作

选择合适的模型并完成准备工作。

模型配置

声音复刻时需要指定以下两个模型:
  • 声音复刻模型:qwen-voice-enrollment
  • 驱动音色的全模态模型:
    • qwen3.5-omni-plus-realtime
    • qwen3.5-omni-flash-realtime
    • qwen3.5-omni-plus
    • qwen3.5-omni-flash

准备工作

  1. 获取 API Key获取 API Key,为安全起见,推荐将 API Key 配置到环境变量。
  2. 安装 SDK:确保已安装最新版 DashScope SDK
  3. 准备待复刻音频:音频需符合音频要求

3. 端到端示例

以下示例演示了如何在对话中使用声音复刻生成的专属音色,实现与原音高度相似的输出效果。
  • 关键原则:声音复刻时,target_model(驱动音色的全模态模型)必须与后续调用 Omni 接口时指定的模型一致,否则会合成失败。
  • 示例使用本地音频文件 voice.mp3 进行声音复刻,运行代码时,请注意替换。
  • 实时
  • 非实时
适用于 Qwen-Omni-Realtime 系列模型,更多说明请参见实时多模态语音
# 依赖: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

# ======= 常量配置 =======
DEFAULT_TARGET_MODEL = "qwen3.5-omni-plus-realtime"  # 声音复刻、实时对话要使用相同的模型
DEFAULT_PREFERRED_NAME = "guanyu"
DEFAULT_AUDIO_MIME_TYPE = "audio/mpeg"
VOICE_FILE_PATH = "voice.mp3"  # 用于声音复刻的本地音频文件的相对路径


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:
  """
  创建音色,并返回 voice 参数
  """
  # 若没有配置环境变量,请用千问云 API Key 将下行替换为: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"音频文件不存在: {file_path}")

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

  url = "https://dashscope.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"创建 voice 失败: {resp.status_code}, {resp.text}")

  try:
    return resp.json()["output"]["voice"]
  except (KeyError, ValueError) as e:
    raise RuntimeError(f"解析 voice 响应失败: {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__':
  # 若没有配置环境变量,请用千问云 API Key 将下行替换为:dashscope.api_key = "sk-xxx"
  dashscope.api_key = os.getenv("DASHSCOPE_API_KEY")
  url = "wss://dashscope.aliyuncs.com/api-ws/v1/realtime"

  # 1. 声音复刻:创建专属音色
  voice = create_voice(VOICE_FILE_PATH)
  print(f"声音复刻完成,音色: {voice}")

  # 2. 使用复刻音色进行实时对话
  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  # 使用复刻生成的专属音色
  )
  mic = pya.open(format=pyaudio.paInt16, channels=1, rate=16000, input=True)
  print("对话已开始,对着麦克风说话 (Ctrl+C 退出)...")
  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("\n对话结束")

API 参考

使用不同 API 时,请确保使用同一账号进行操作。

创建音色

上传用于复刻的音频,创建自定义音色。 URL
POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
请求头
参数类型必须说明
Authorizationstring鉴权令牌,格式为 Bearer $DASHSCOPE_API_KEY
Content-Typestring请求体中传输的数据的媒体类型。固定为 application/json
消息体
注意区分如下参数:
  • model:声音复刻模型,固定为 qwen-voice-enrollment
  • target_model:驱动音色的全模态模型,须和后续调用 Omni 接口时使用的全模态模型一致,否则合成会失败
{
  "model": "qwen-voice-enrollment",
  "input": {
    "action": "create",
    "target_model": "qwen3.5-omni-plus-realtime",
    "preferred_name": "guanyu",
    "audio": {
      "data": "https://xxx.wav"
    },
    "text": "可选项,填入 audio.data 对应的文本",
    "language": "可选项,填入 audio.data 对应的语种,如 zh"
  }
}
请求参数
参数类型默认值必须说明
modelstring-声音复刻模型,固定为 qwen-voice-enrollment
actionstring-操作类型,固定为 create
target_modelstring-驱动音色的全模态模型:qwen3.5-omni-plus-realtimeqwen3.5-omni-flash-realtimeqwen3.5-omni-plusqwen3.5-omni-flash。必须与后续调用全模态接口时使用的模型一致,否则合成会失败。
preferred_namestring-为音色指定一个便于识别的名称(仅允许数字、大小写字母和下划线,不超过 16 个字符)。建议选用与角色、场景相关的标识。该关键字会在复刻的音色名中出现,例如关键字为"guanyu",最终音色名为"qwen-omni-vc-guanyu-voice-20250812105009984-838b"。
audio.datastring-用于复刻的音频。可通过以下两种方式提交**:1) Data URL**:格式为 data:&lt;mediatype&gt;;base64,&lt;data&gt;,支持 audio/wavaudio/mpegaudio/mp4。Base64 编码会增大体积,请控制原文件大小,确保编码后仍小于 10 MB。2) 音频 URL:文件大小不超过 10 MB,URL 必须公网可访问且无需鉴权。
textstring-audio.data 音频内容相匹配的文本。传入该参数后,服务端会对比音频与该文本的差异,若差异过大,将返回 Audio.PreprocessError
languagestring-audio.data 音频对应的语种。支持 zh(中文)、en(英文)、de(德语)、it(意大利语)、pt(葡萄牙语)、es(西班牙语)、ja(日语)、ko(韩语)、fr(法语)、ru(俄语)、th(泰语)、id(印尼语)、ar(阿拉伯语)等。中文方言:Dongbei(东北话)、Shannxi(陕西话)、Sichuan(四川话)等。若使用该参数,设置的语种要和实际用于复刻的音频的语种一致。
响应参数
参数类型说明
voicestring音色名称,可直接用于 Omni 接口的 voice 参数。
target_modelstring驱动音色的全模态模型。
request_idstringRequest ID。
countinteger本次请求实际计入费用的"创建音色"次数。创建音色时,count 恒为 1。
示例代码
注意区分如下参数:
  • model:声音复刻模型,固定为 qwen-voice-enrollment,请勿修改
  • target_model:驱动音色的全模态模型
curl -X POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "model": "qwen-voice-enrollment",
  "input": {
    "action": "create",
    "target_model": "qwen3.5-omni-plus-realtime",
    "preferred_name": "guanyu",
    "audio": {
      "data": "https://xxx.wav"
    }
  }
}'

查询音色列表

分页查询已创建的音色列表。 URL
POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
请求头
参数类型必须说明
Authorizationstring鉴权令牌,格式为 Bearer $DASHSCOPE_API_KEY
Content-Typestring请求体中传输的数据的媒体类型。固定为 application/json
消息体
model:声音复刻模型,固定为 qwen-voice-enrollment,请勿修改。
{
  "model": "qwen-voice-enrollment",
  "input": {
    "action": "list",
    "page_size": 2,
    "page_index": 0
  }
}
请求参数
参数类型默认值必须说明
modelstring-声音复刻模型,固定为 qwen-voice-enrollment
actionstring-操作类型,固定为 list
page_indexinteger0页码索引。取值范围:[0, 1000000]。
page_sizeinteger10每页包含数据条数。取值范围:[0, 1000000]。
响应参数
参数类型说明
voicestring音色名称,可直接用于 Omni 接口的 voice 参数。
gmt_createstring创建音色的时间。
target_modelstring驱动音色的全模态模型。
request_idstringRequest ID。
countinteger查询音色不计费,因此 count 恒为 0。
示例代码
curl --location --request POST 'https://dashscope.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
  }
}'

删除音色

删除指定音色,释放对应额度。 URL
POST https://dashscope.aliyuncs.com/api/v1/services/audio/tts/customization
请求头
参数类型必须说明
Authorizationstring鉴权令牌,格式为 Bearer $DASHSCOPE_API_KEY
Content-Typestring请求体中传输的数据的媒体类型。固定为 application/json
消息体
model:声音复刻模型,固定为 qwen-voice-enrollment,请勿修改。
{
  "model": "qwen-voice-enrollment",
  "input": {
    "action": "delete",
    "voice": "yourVoice"
  }
}
请求参数
参数类型默认值必须说明
modelstring-声音复刻模型,固定为 qwen-voice-enrollment
actionstring-操作类型,固定为 delete
voicestring-待删除的音色。
响应参数
参数类型说明
request_idstringRequest ID。
countinteger删除音色不计费,因此 count 恒为 0。
示例代码
curl --location --request POST 'https://dashscope.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"
  }
}'

对话使用

如何使用声音复刻生成的专属音色进行对话,请参见端到端示例

音色配额与自动清理规则

  • 总数限制:1000 个音色/账号。当前接口不提供音色数量查询功能,可通过调用查询音色列表接口自行统计音色数目。
  • 自动清理:若单个音色在过去一年内未被用于任何模型调用请求,系统将自动将其删除。

计费说明

声音复刻和模型调用分开计费:
  • 声音复刻创建音色按 0.01 元/个计费,创建失败不计费。
    免费额度说明:
    • 千问云开通后 90 天内,可享 1000 次免费音色创建机会。
    • 创建失败不占用免费次数。
    • 删除音色不会恢复免费次数。
    • 免费额度用完或超出 90 天有效期后,创建音色将按 0.01 元/个的价格计费。
  • 使用复刻生成的专属音色进行对话:按模型调用的 token 用量计费,详情请参见计费说明

版权与合法性

您需对所提供声音的所有权及合法使用权负责。

录音操作指南

录音设备

推荐使用具备降噪功能的麦克风,或在安静环境下使用手机近距离录音,以保证音源纯净。

录音环境

场地
  • 建议在 10 平方米以内的小型封闭空间录音。
  • 优先选择配有吸音材料(如吸音棉、地毯、窗帘)的房间。
  • 避免空旷大厅、会议室、教室等高混响场所。
噪音控制
  • 室外噪音:关闭门窗,避免交通、施工等干扰。
  • 室内噪音:关闭空调、风扇、日光灯镇流器等设备;可通过手机录制环境音并放大播放,识别潜在噪音源。
混响控制
  • 混响会导致声音模糊、清晰度下降。
  • 减少光滑表面反射:拉上窗帘、打开衣柜门、铺放衣物或床单覆盖桌面/柜面。
  • 利用不规则物体(如书架、软包家具)实现声波漫反射。

录音文案

  • 文案内容灵活,建议与目标应用场景一致(例如,若用于客服场景,文案应为客服对话风格),但必须确保不包含任何敏感或非法词汇(如政治、色情、暴力相关内容),否则会导致复刻失败。
  • 避免短句(如"你好"、"是的"),应使用完整句子。
  • 保持语义连贯,朗读时避免频繁停顿(建议至少连续 3 秒无中断)。
  • 可带入目标情绪(如亲切、严肃),但需避免过度夸张的戏剧化朗读,保持语调自然。

操作建议

以普通卧室为例:
  1. 关闭门窗,隔绝外部噪音。
  2. 关闭空调、电扇等电器。
  3. 拉上窗帘,减少玻璃反射。
  4. 在桌面铺放衣物或毛毯,降低桌面反射。
  5. 提前熟悉文案,设定角色语气,自然演绎。
  6. 与录音设备保持约 10 厘米距离,避免喷麦或信号过弱。

错误信息

如遇报错问题,请参见错误信息进行排查。
图像局部重绘

Wanx — 创建任务

异步 wanx-x-painting 图像局部重绘

POST
/services/aigc/image2image/image-synthesis
curl --location 'https://dashscope.aliyuncs.com/api/v1/services/aigc/image2image/image-synthesis' \
  --header 'X-DashScope-Async: enable' \
  --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "wanx-x-painting",
  "input": {
    "prompt": "一只狗戴着红色眼镜",
    "base_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/source3.jpg",
    "mask_image_url": "http://synthesis-source.oss-accelerate.aliyuncs.com/lingji/validation/mask2img/demo/glasses.png"
  },
  "parameters": {
    "size": "1024*1024",
    "n": 1
  }
}'
{
  "output": {
    "task_status": "PENDING",录音操作指南
  • 录音设备
  • 录音环境
  • 录音文案
  • 操作建议
  • 错误信息