跳转到主要内容
实时

CosyVoice Java SDK

CosyVoice Java 参考文档

模型概览和音色选择请参见语音合成

服务端点

SDK 默认服务端点为 wss://dashscope.aliyuncs.com/api-ws/v1/inference。如需修改,可在初始化前设置 Constants.baseWebsocketApiUrl

前提条件

如需向第三方应用提供临时访问权限,或对敏感操作进行严格管控,可使用临时认证令牌。临时令牌 60 秒后过期,可有效降低泄露风险。在代码中用临时令牌替换 API Key 即可。

模型与计费

请参见语音合成

文本与格式限制

文本长度限制

  • 非流式单向流式或 Flowable 单向流式:单次请求最多 20,000 字符。
  • 双向流式或 Flowable 双向流式:单次请求最多 20,000 字符,累计最多 200,000 字符。

字符计数规则

  • 中文汉字(简体、繁体、日文汉字、韩文汉字)每个计 2 个字符。其他字符(标点、字母、数字、假名、韩文字母)每个计 1 个字符。
  • SSML 标签不计入文本长度。
  • 示例:
    • "你好" → 2(汉字)+ 2(汉字)= 4 字符
    • "中A文123" → 2(汉字)+ 1(A)+ 2(汉字)+ 1(1)+ 1(2)+ 1(3)= 8 字符
    • "中文。" → 2(汉字)+ 2(汉字)+ 1(句号)= 5 字符
    • "中 文。" → 2(汉字)+ 1(空格)+ 2(汉字)+ 1(句号)= 6 字符
    • "<speak>你好</speak>" → 2(汉字)+ 2(汉字)= 4 字符

编码格式

使用 UTF-8 编码。

数学表达式

cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持数学表达式解析,覆盖常见的中小学数学内容,包括基本运算、代数和几何。
该功能仅支持中文。
请参见将 LaTeX 公式转为语音(仅限中文)

SSML 支持

SSML 适用于 cosyvoice-v3-flash 和 cosyvoice-v3-plus 上的自定义音色(声音设计或声音克隆),以及音色列表中标注支持 SSML 的系统音色。 使用要求:

快速开始

SpeechSynthesizer 类支持以下调用方式:
  • 非流式:发送完整文本,返回完整音频。阻塞式调用,适合短文本。
  • 单向流式:发送完整文本,通过回调返回音频。非阻塞式调用,适合对延迟敏感的短文本场景。
  • 双向流式:逐步发送文本片段,通过回调实时返回音频。非阻塞式调用,适合对延迟敏感的长文本场景。

非流式调用

同步发送文本,返回完整音频结果。
image
实例化 SpeechSynthesizer,绑定请求参数,然后调用 call 方法获取二进制音频数据。文本上限:20,000 字符。
每次调用 call 前需重新初始化 SpeechSynthesizer 实例。
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.utils.Constants;

import java.io.File;
import java.io.FileOutputStream;
import java.io.IOException;
import java.nio.ByteBuffer;

public class Main {
  private static String model = "cosyvoice-v3-flash";
  private static String voice = "longanyang";

  public static void streamAudioDataToSpeaker() {
    SpeechSynthesisParam param =
        SpeechSynthesisParam.builder()
            // 如果未配置环境变量,请将下一行替换为:.apiKey("sk-xxx")
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model(model)
            .voice(voice)
            .build();

    // 同步模式:将回调(第二个参数)设为 null。
    SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, null);
    ByteBuffer audio = null;
    try {
      // 阻塞直到音频返回。
      audio = synthesizer.call("今天天气怎么样?");
    } catch (Exception e) {
      throw new RuntimeException(e);
    } finally {
      // 任务完成后关闭 WebSocket 连接。
      synthesizer.getDuplexApi().close(1000, "bye");
    }
    if (audio != null) {
      File file = new File("output.mp3");
      // 首次调用的首包延迟包含 WebSocket 建连时间。
      System.out.println(
          "[Metric] Request ID: "
              + synthesizer.getLastRequestId()
              + ", First-packet latency (ms): "
              + synthesizer.getFirstPackageDelay());
      try (FileOutputStream fos = new FileOutputStream(file)) {
        // call() 返回的 ByteBuffer position=0 且 remaining=capacity,array() 返回完整音频数据。
        fos.write(audio.array());
      } catch (IOException e) {
        throw new RuntimeException(e);
      }
    }
  }

  public static void main(String[] args) {
    Constants.baseWebsocketApiUrl = "wss://dashscope.aliyuncs.com/api-ws/v1/inference";
    streamAudioDataToSpeaker();
    System.exit(0);
  }
}

单向流式调用

异步提交文本,通过 ResultCallback 增量接收音频数据。
image
实例化 SpeechSynthesizer,绑定请求参数ResultCallback,然后调用 call 方法。通过 onEvent 实时获取音频。文本上限:20,000 字符。
每次调用 call 前需重新初始化 SpeechSynthesizer 实例。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.concurrent.CountDownLatch;

class TimeUtils {
  private static final DateTimeFormatter formatter =
      DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");

  public static String getTimestamp() {
    return LocalDateTime.now().format(formatter);
  }
}

public class Main {
  private static String model = "cosyvoice-v3-flash";
  private static String voice = "longanyang";

  public static void streamAudioDataToSpeaker() {
    CountDownLatch latch = new CountDownLatch(1);

    // 实现 ResultCallback 接口。
    ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<SpeechSynthesisResult>() {
      @Override
      public void onEvent(SpeechSynthesisResult result) {
        // System.out.println("收到消息: " + result);
        if (result.getAudioFrame() != null) {
          // 在此添加音频处理逻辑。
          System.out.println(TimeUtils.getTimestamp() + " 收到音频");
        }
      }

      @Override
      public void onComplete() {
        System.out.println(TimeUtils.getTimestamp() + " 收到完成信号,语音合成结束。");
        latch.countDown();
      }

      @Override
      public void onError(Exception e) {
        System.out.println("发生异常:" + e.toString());
        latch.countDown();
      }
    };

    SpeechSynthesisParam param =
        SpeechSynthesisParam.builder()
            // 如果未配置环境变量,请将下一行替换为:.apiKey("sk-xxx")
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model(model)
            .voice(voice)
            .build();
    // 将回调作为第二个参数传入,启用异步模式。
    SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, callback);
    // 非阻塞:立即返回 null,结果通过 onEvent 回调返回。
    try {
      synthesizer.call("今天天气怎么样?");
      latch.await();
    } catch (Exception e) {
      throw new RuntimeException(e);
    } finally {
      // 任务完成后关闭 WebSocket 连接。
      synthesizer.getDuplexApi().close(1000, "bye");
    }
    // 首次调用的首包延迟包含 WebSocket 建连时间。
    System.out.println(
        "[Metric] Request ID: "
            + synthesizer.getLastRequestId()
            + ", First-packet latency (ms): "
            + synthesizer.getFirstPackageDelay());
  }

  public static void main(String[] args) {
    Constants.baseWebsocketApiUrl = "wss://dashscope.aliyuncs.com/api-ws/v1/inference";
    streamAudioDataToSpeaker();
    System.exit(0);
  }
}

双向流式调用

分多次发送文本片段,通过 ResultCallback 增量接收音频。
  • 多次调用 streamingCall 提交文本片段。服务端自动分句:完整句子立即合成,不完整的句子会缓存直到补全。调用 streamingComplete() 可强制合成所有缓存文本。
  • 文本片段发送间隔不得超过 23 秒,否则会触发超时错误。发送完毕后请调用 streamingComplete()
    23 秒的服务端超时不可在客户端修改。
image
1

实例化 SpeechSynthesizer

2

发送文本流

多次调用 streamingCall 分段发送文本。服务端通过 onEvent 实时返回音频。每次 streamingCall 的文本片段上限:20,000 字符。所有片段累计上限:200,000 字符。
3

完成合成

调用 streamingComplete 完成合成。该方法会阻塞直到 onCompleteonError 触发。务必调用此方法,否则尾部文本可能无法被合成。
import com.alibaba.dashscope.audio.tts.SpeechSynthesisResult;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisAudioFormat;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

class TimeUtils {
  private static final DateTimeFormatter formatter =
      DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");

  public static String getTimestamp() {
    return LocalDateTime.now().format(formatter);
  }
}


public class Main {
  private static String[] textArray = {"流式语音合成 SDK ",
      "可以将输入文本 ", "转换为二进制音频数据。", "相比非流式合成,",
      "流式合成具有更好的实时性。", "您几乎可以在输入文本的同时听到音频输出,",
      "这极大地提升了用户体验 ", "并减少了等待时间。",
      "这非常适合使用大型 ", "语言模型(LLM)",
      "从文本流中合成语音的应用场景。"};
  private static String model = "cosyvoice-v3-flash";
  private static String voice = "longanyang";

  public static void streamAudioDataToSpeaker() {
    // 配置回调。
    ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<SpeechSynthesisResult>() {
      @Override
      public void onEvent(SpeechSynthesisResult result) {
        // System.out.println("收到消息: " + result);
        if (result.getAudioFrame() != null) {
          // 在此添加音频处理逻辑。
          System.out.println(TimeUtils.getTimestamp() + " 收到音频");
        }
      }

      @Override
      public void onComplete() {
        System.out.println(TimeUtils.getTimestamp() + " 收到完成信号,语音合成结束。");
      }

      @Override
      public void onError(Exception e) {
        System.out.println("发生异常:" + e.toString());
      }
    };

    // 请求参数
    SpeechSynthesisParam param =
        SpeechSynthesisParam.builder()
            // 如果未配置环境变量,请将下一行替换为:.apiKey("sk-xxx")
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model(model)
            .voice(voice)
            .format(SpeechSynthesisAudioFormat
                .PCM_22050HZ_MONO_16BIT) // 流式合成请使用 PCM 或 MP3 格式。
            .build();
    SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, callback);
    try {
      for (String text : textArray) {
        // 发送文本片段,音频通过 onEvent 实时返回。
        synthesizer.streamingCall(text);
      }
      // 等待流式合成完成。
      synthesizer.streamingComplete();
    } catch (Exception e) {
      throw new RuntimeException(e);
    } finally {
      // 任务完成后关闭 WebSocket 连接。
      synthesizer.getDuplexApi().close(1000, "bye");
    }

    // 首次调用的首包延迟包含 WebSocket 建连时间。
    System.out.println(
        "[Metric] Request ID: "
            + synthesizer.getLastRequestId()
            + ", First-packet latency (ms): "
            + synthesizer.getFirstPackageDelay());
  }

  public static void main(String[] args) {
    Constants.baseWebsocketApiUrl = "wss://dashscope.aliyuncs.com/api-ws/v1/inference";
    streamAudioDataToSpeaker();
    System.exit(0);
  }
}

Flowable 调用

Flowable 是 Apache 2.0 协议下的开源响应式编程框架,详情请参见 Flowable API 文档。使用前请先集成 RxJava 库并了解响应式编程基础。
  • 单向流式调用
  • 双向流式调用
通过 Flowable 对象的 blockingForEach 方法阻塞获取每个 SpeechSynthesisResult。所有流式数据返回后,也可通过 getAudioFrame 获取完整结果。
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesisParam;
import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;

import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;

class TimeUtils {
  private static final DateTimeFormatter formatter =
      DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");

  public static String getTimestamp() {
    return LocalDateTime.now().format(formatter);
  }
}

public class Main {
  private static String model = "cosyvoice-v3-flash";
  private static String voice = "longanyang";

  public static void streamAudioDataToSpeaker() throws NoApiKeyException {
    SpeechSynthesisParam param =
        SpeechSynthesisParam.builder()
            // 如果未配置环境变量,请将下一行替换为:.apiKey("sk-xxx")
            .apiKey(System.getenv("DASHSCOPE_API_KEY"))
            .model(model)
            .voice(voice)
            .build();
    SpeechSynthesizer synthesizer = new SpeechSynthesizer(param, null);
    synthesizer.callAsFlowable("今天天气怎么样?").blockingForEach(result -> {
      // System.out.println("收到消息: " + result);
      if (result.getAudioFrame() != null) {
        // 在此添加音频处理逻辑。
        System.out.println(TimeUtils.getTimestamp() + " 收到音频");
      }
    });
    // 任务完成后关闭 WebSocket 连接。
    synthesizer.getDuplexApi().close(1000, "bye");
    // 首次调用的首包延迟包含 WebSocket 建连时间。
    System.out.println(
        "[Metric] Request ID: "
            + synthesizer.getLastRequestId()
            + ", First-packet latency (ms): "
            + synthesizer.getFirstPackageDelay());
  }

  public static void main(String[] args) throws NoApiKeyException {
    Constants.baseWebsocketApiUrl = "wss://dashscope.aliyuncs.com/api-ws/v1/inference";
    streamAudioDataToSpeaker();
    System.exit(0);
  }
}

高并发调用

DashScope Java SDK 使用 OkHttp3 连接池来减少连接开销。请参见高并发管理

请求参数

通过 SpeechSynthesisParam 的链式方法配置 model、voice 等参数,将配置好的对象传给 SpeechSynthesizer 构造函数。
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("longanyang")
  .format(SpeechSynthesisAudioFormat.WAV_8000HZ_MONO_16BIT) // 音频格式和采样率
  .volume(50) // 音量:[0, 100]
  .speechRate(1.0f) // 语速:[0.5, 2]
  .pitchRate(1.0f) // 音调:[0.5, 2]
  .build();
参数类型是否必选说明
modelString语音合成模型。所有可选项请参见音色列表
voiceString合成使用的音色。可用的系统音色请参见音色列表
formatenum音频格式和采样率。默认:22.05 kHz 的 MP3。默认采样率为音色最佳采样率,支持降采样和升采样。

支持的格式:
  • 所有模型:
    • SpeechSynthesisAudioFormat.WAV_8000HZ_MONO_16BIT:WAV,8 kHz
    • SpeechSynthesisAudioFormat.WAV_16000HZ_MONO_16BIT:WAV,16 kHz
    • SpeechSynthesisAudioFormat.WAV_22050HZ_MONO_16BIT:WAV,22.05 kHz
    • SpeechSynthesisAudioFormat.WAV_24000HZ_MONO_16BIT:WAV,24 kHz
    • SpeechSynthesisAudioFormat.WAV_44100HZ_MONO_16BIT:WAV,44.1 kHz
    • SpeechSynthesisAudioFormat.WAV_48000HZ_MONO_16BIT:WAV,48 kHz
    • SpeechSynthesisAudioFormat.MP3_8000HZ_MONO_128KBPS:MP3,8 kHz
    • SpeechSynthesisAudioFormat.MP3_16000HZ_MONO_128KBPS:MP3,16 kHz
    • SpeechSynthesisAudioFormat.MP3_22050HZ_MONO_256KBPS:MP3,22.05 kHz
    • SpeechSynthesisAudioFormat.MP3_24000HZ_MONO_256KBPS:MP3,24 kHz
    • SpeechSynthesisAudioFormat.MP3_44100HZ_MONO_256KBPS:MP3,44.1 kHz
    • SpeechSynthesisAudioFormat.MP3_48000HZ_MONO_256KBPS:MP3,48 kHz
    • SpeechSynthesisAudioFormat.PCM_8000HZ_MONO_16BIT:PCM,8 kHz
    • SpeechSynthesisAudioFormat.PCM_16000HZ_MONO_16BIT:PCM,16 kHz
    • SpeechSynthesisAudioFormat.PCM_22050HZ_MONO_16BIT:PCM,22.05 kHz
    • SpeechSynthesisAudioFormat.PCM_24000HZ_MONO_16BIT:PCM,24 kHz
    • SpeechSynthesisAudioFormat.PCM_44100HZ_MONO_16BIT:PCM,44.1 kHz
    • SpeechSynthesisAudioFormat.PCM_48000HZ_MONO_16BIT:PCM,48 kHz
  • Opus(需 DashScope 2.21.0+)。可通过 bit_rate 调整比特率:
    • SpeechSynthesisAudioFormat.OGG_OPUS_8KHZ_MONO_32KBPS:Opus,8 kHz,32 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_16KHZ_MONO_16KBPS:Opus,16 kHz,16 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_16KHZ_MONO_32KBPS:Opus,16 kHz,32 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_16KHZ_MONO_64KBPS:Opus,16 kHz,64 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_24KHZ_MONO_16KBPS:Opus,24 kHz,16 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_24KHZ_MONO_32KBPS:Opus,24 kHz,32 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_24KHZ_MONO_64KBPS:Opus,24 kHz,64 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_48KHZ_MONO_16KBPS:Opus,48 kHz,16 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_48KHZ_MONO_32KBPS:Opus,48 kHz,32 kbps
    • SpeechSynthesisAudioFormat.OGG_OPUS_48KHZ_MONO_64KBPS:Opus,48 kHz,64 kbps
volumeint音量。默认:50。范围:[0, 100]。线性缩放,0 为静音,100 为最大音量。
speechRatefloat语速。默认:1.0。范围:[0.5, 2.0]。小于 1.0 语速减慢,大于 1.0 语速加快。
pitchRatefloat音调倍率。默认:1.0。范围:[0.5, 2.0]。与感知音高的关系非线性:大于 1.0 升高音调,小于 1.0 降低音调。建议实际测试以找到合适的值。
bit_rateintOpus 格式的音频比特率(kbps)。默认:32。范围:[6, 510]。

通过 SpeechSynthesisParamparameterparameters 方法设置。请参见下方示例。
enableWordTimestampboolean是否启用字级时间戳。默认:false。适用于 cosyvoice-v3-flash、cosyvoice-v3-plus 和 cosyvoice-v2 模型的复刻音色,以及音色列表中标注支持此功能的系统音色。

时间戳结果仅通过回调接口返回。
seedint随机种子。不同的种子产生不同的合成结果,相同种子和相同参数可复现相同输出。默认:0。范围:[0, 65535]。
languageHintsList合成目标语言。当数字、缩写或符号的发音不准确,或不常见语种需要改善时使用。可选值:zh(中文)、en(英文)、fr(法文)、de(德文)、ja(日文)、ko(韩文)、ru(俄文)、pt(葡萄牙文)、th(泰文)、id(印尼文)、vi(越南文)。注意:此参数为数组,但仅处理第一个元素,请只传入一个值。
instructionString通过指令控制方言、情感或说话风格。适用于音色列表中标注支持 Instruct 的系统音色。最大长度:100 字符。请参见下方指令示例。
enable_aigc_tagboolean在音频中添加不可见的 AIGC 标识。设为 true 时,在支持的格式(WAV、MP3、Opus)中嵌入不可见标识。默认:false。cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持。
aigc_propagatorString设置 AIGC 标识中的 ContentPropagator 字段,用于标识内容传播者。仅在 enable_aigc_tag 为 true 时生效。默认:UID。cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持。
aigc_propagate_idString设置 AIGC 标识中的 PropagateID 字段,用于唯一标识一次传播行为。仅在 enable_aigc_tag 为 true 时生效。默认:当前请求 ID。cosyvoice-v3-flash 和 cosyvoice-v3-plus 支持。
hotFixParamHotFix文本热补丁配置。可自定义特定词语的发音或在合成前替换文本。仅 cosyvoice-v3-flash 支持。请参见下方 hotFix 示例。
enable_markdown_filterboolean合成前移除输入文本中的 Markdown 符号,防止其被朗读。默认:false。仅 cosyvoice-v3-flash 支持。

设置 bit_rate

  • 使用 parameter()
  • 使用 parameters()
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("longanyang")
  .parameter("bit_rate", 32)
  .build();

设置 enable_aigc_tag

  • 使用 parameter()
  • 使用 parameters()
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("longanyang")
  .parameter("enable_aigc_tag", true)
  .build();

设置 aigc_propagator

  • 使用 parameter()
  • 使用 parameters()
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("longanyang")
  .parameter("enable_aigc_tag", true)
  .parameter("aigc_propagator", "xxxx")
  .build();

设置 aigc_propagate_id

  • 使用 parameter()
  • 使用 parameters()
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("longanyang")
  .parameter("enable_aigc_tag", true)
  .parameter("aigc_propagate_id", "xxxx")
  .build();

设置 enable_markdown_filter

  • 使用 parameter()
  • 使用 parameters()
SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("your_voice") // 替换为 cosyvoice-v3-flash 的克隆音色
  .parameter("enable_markdown_filter", true)
  .build();

instruction 示例

cosyvoice-v3-flash
  • 克隆音色:可使用任意自然语言指令控制合成效果。 指令示例:
请用粤语说话。(支持的方言:粤语、东北话、甘肃话、贵州话、河南话、湖北话、江西话、闽南语、宁夏话、山西话、陕西话、山东话、上海话、四川话、天津话、云南话。)
请尽可能大声地说一句话。
请尽可能慢地说一句话。
请尽可能快地说一句话。
请用很轻的声音说一句话。
你能说慢一点吗?
你能说得非常快吗?
你能说得非常慢吗?
你能说快一点吗?
请用非常生气的语气说一句话。
请用非常开心的语气说一句话。
请用非常恐惧的语气说一句话。
请用非常悲伤的语气说一句话。
请用非常惊讶的语气说一句话。
请尽量用坚定的语气说话。
请尽量用愤怒的语气说话。
请用亲切的语气说话。
请用冷淡的语气说话。
请用威严的语气说话。
我想体验自然的语气。
我想看看你怎么表达威胁。
我想看看你怎么表达智慧。
我想看看你怎么表达诱惑。
我想听你用活泼的方式说话。
我想听你用充满激情的方式说话。
我想听你用沉稳的方式说话。
我想听你用自信的方式说话。
你能用兴奋的情绪跟我说话吗?
你能展示一下傲慢的情绪吗?
你能展示一下优雅的情绪吗?
你能开心地回答这个问题吗?
你能做一个温柔的情绪示范吗?
你能用平静的语气跟我说话吗?
你能用深沉的方式回答我吗?
你能用粗犷的态度跟我说话吗?
用阴森的声音告诉我答案。
用坚韧的声音告诉我答案。
用自然友好的聊天风格来叙述。
用广播剧播客的语气来朗读。
  • 系统音色:指令必须使用固定格式。详情请参见音色列表

hotFix 示例

List<ParamHotFix.PronunciationItem> pronunciationItems = new ArrayList<>();
pronunciationItems.add(new ParamHotFix.PronunciationItem("天气", "tian1 qi4"));

List<ParamHotFix.ReplaceItem> replaceItems = new ArrayList<>();
replaceItems.add(new ParamHotFix.ReplaceItem("今天", "今日"));

ParamHotFix paramHotFix = new ParamHotFix();
paramHotFix.setPronunciation(pronunciationItems);
paramHotFix.setReplace(replaceItems);

SpeechSynthesisParam param = SpeechSynthesisParam.builder()
  .model("cosyvoice-v3-flash")
  .voice("your_voice") // 替换为 cosyvoice-v3-flash 的克隆音色
  .hotFix(paramHotFix)
  .build();

核心接口

SpeechSynthesizer

通过 import com.alibaba.dashscope.audio.ttsv2.SpeechSynthesizer; 导入。
接口/方法参数返回值说明
public SpeechSynthesizer(SpeechSynthesisParam param, ResultCallback<SpeechSynthesisResult> callback)param请求参数callback:流式调用传 ResultCallback,非流式/Flowable 调用传 nullSpeechSynthesizer 实例构造函数。单向流式双向流式调用时将 callback 设为 ResultCallback非流式Flowable 调用时设为 null。
public ByteBuffer call(String text)text:待合成文本(UTF-8)。ByteBuffernull将文本(纯文本或 SSML)转换为语音。未设置 callback 时:阻塞直到完成。设置了 callback 时:立即返回 null,结果通过 onEvent 返回。
public void streamingCall(String text)text:待合成文本(UTF-8)。发送文本进行流式合成。不支持 SSML。可多次调用以分段发送文本,结果通过 onEvent 返回。请参见双向流式调用
public void streamingComplete() throws RuntimeException结束流式合成。阻塞直到合成完成、会话中断或 10 分钟超时。请参见双向流式调用
public Flowable<SpeechSynthesisResult> callAsFlowable(String text)text:待合成文本(UTF-8)。Flowable<SpeechSynthesisResult>将非流式文本输入转为流式语音输出。不支持 SSML。请参见 Flowable 调用
boolean getDuplexApi().close(int code, String reason)code:WebSocket 关闭码。reason:关闭原因。请参见 The WebSocket Protocoltrue每次任务完成后关闭 WebSocket 连接以防止连接泄漏。连接复用请参见高并发管理
public Flowable<SpeechSynthesisResult> streamingCallAsFlowable(Flowable<String> textStream)textStream:封装待合成文本的 Flowable。Flowable<SpeechSynthesisResult>将流式文本输入转为流式语音输出。不支持 SSML。请参见 Flowable 调用
public String getLastRequestId()上一次任务的请求 ID。通过 callstreamingCallcallAsFlowablestreamingCallAsFlowable 启动新任务后获取请求 ID。
public long getFirstPackageDelay()首包延迟(毫秒)。获取从发送文本到收到首个音频包的时间。请在任务完成后调用。
使用须知
  • 每次调用 call 前需重新初始化 SpeechSynthesizer 实例。
  • 双向流式调用时务必调用 streamingComplete,否则可能丢失合成语音。
影响首包延迟的因素
  • WebSocket 建连(首次调用)
  • 音色加载时间(不同音色有差异)
  • 服务负载(高峰时段排队)
  • 网络延迟
典型延迟
  • 复用连接且音色已加载:约 500 ms
  • 首次连接或切换音色:1,500-2,000 ms
如果延迟持续超过 2,000 ms:
  1. 使用连接池预建连接(高并发场景)。
  2. 检查网络质量。
  3. 避开高峰时段。

ResultCallback 接口

单向流式双向流式调用中通过 ResultCallback 获取合成结果。通过 import com.alibaba.dashscope.common.ResultCallback; 导入。
ResultCallback<SpeechSynthesisResult> callback = new ResultCallback<SpeechSynthesisResult>() {
  @Override
  public void onEvent(SpeechSynthesisResult result) {
    System.out.println("Request ID: " + result.getRequestId());
    // 实时处理音频片段(如播放或写入缓冲区)。
  }

  @Override
  public void onComplete() {
    System.out.println("任务完成");
    // 处理合成完成逻辑(如释放播放器)。
  }

  @Override
  public void onError(Exception e) {
    System.out.println("任务失败:" + e.getMessage());
    // 处理异常(网络错误或服务端错误码)。
  }
};
接口/方法参数返回值说明
public void onEvent(SpeechSynthesisResult result)result:SpeechSynthesisResult 实例。服务端推送音频数据时触发。通过 SpeechSynthesisResultgetAudioFrame 获取二进制音频,通过 getUsage 获取当前已计费字符数。
public void onComplete()所有合成数据返回后触发。
public void onError(Exception e)e:异常信息。发生异常时触发。请在此方法中实现异常日志记录和资源清理。

响应

服务端返回二进制音频数据: SpeechSynthesisResult 核心接口:
接口/方法参数返回值说明
public ByteBuffer getAudioFrame()二进制音频数据返回当前片段的二进制音频。如果没有新数据则可能为空。可将多个片段拼接为完整文件,也可使用流式播放器逐段播放。
public String getRequestId()请求 ID获取任务请求 ID。当 getAudioFrame 返回数据时,此方法返回 null
public SpeechSynthesisUsage getUsage()SpeechSynthesisUsagenull通过 getCharacters() 返回当前已计费字符数。以最后一次收到的值为准。
public Sentence getTimestamp()SentencenullenableWordTimestamp 为 true 时返回时间戳数据。Sentence 方法:getBeginTime(句子开始时间,ms)、getEndTime(句子结束时间,ms)、getWords(返回 List<Word>)。Word 方法:getTextgetBeginIndexgetEndIndexgetBeginTimegetEndTimegetPhonemes(返回 List<Phoneme>,可能为空)。Phoneme 方法:getBeginTimegetEndTimegetTextgetTone(音调:英文中 0/1/2 分别为轻音/重音/次重音;拼音中 1-5 分别为一声至轻声)。
流式合成使用压缩格式(MP3、Opus)时,请使用流式播放器。逐帧播放会导致解码失败。常用的流式播放器包括 FFmpeg、PyAudio(Python)、AudioFormat(Java)和 MediaSource(JavaScript)。拼接音频为完整文件时,请使用追加模式写入。WAV 和 MP3 流式音频中,仅首帧包含头信息。

更多示例

更多示例请参见 GitHub
Qwen-Omni-Realtime

Qwen-Omni Java SDK

Qwen-Omni-Realtime Java SDK 接口说明

Qwen-Omni-Realtime DashScope Java SDK 的核心接口与请求参数。

快速开始

需要 DashScope Java SDK 2.20.9 及以上版本。教程、示例代码和交互模式详解请参见实时多模态语音

请求参数

通过 OmniRealtimeParam 对象的链式方法或 setter 配置以下请求参数,然后将该对象与回调实例一起传入 OmniRealtimeConversation 构造函数。
参数类型说明
modelStringQwen-Omni 实时模型名称。参见模型列表
urlString端点 URL,默认值为 wss://dashscope.aliyuncs.com/api-ws/v1/realtime
通过 OmniRealtimeConfig 对象的链式方法或 setter 配置以下请求参数,然后将该对象作为参数传入 updateSession 接口。
参数类型说明
modalitiesList<OmniRealtimeModality>模型的输出模态。设置为 [OmniRealtimeModality.TEXT] 仅输出文本,或设置为 [OmniRealtimeModality.TEXT, OmniRealtimeModality.AUDIO] 同时输出音频和文本。
voiceString模型音频输出所使用的声音。支持的声音列表请参见声音列表。默认声音:Qwen3.5-Omni-Realtime"Tina"Qwen3-Omni-Flash-Realtime"Cherry"Qwen-Omni-Turbo-Realtime"Chelsie"
inputAudioFormatOmniRealtimeAudioFormat用户输入音频的格式,当前仅支持设为 PCM_16000HZ_MONO_16BIT,表示 16 kHz 采样率的 PCM 音频流。
outputAudioFormatOmniRealtimeAudioFormat模型输出音频的格式,当前仅支持设为 PCM_24000HZ_MONO_16BIT,表示 24 kHz 采样率的 PCM 音频流。当前不支持自定义输出采样率。
smooth_outputBooleanQwen3-Omni-Flash-Realtime 系列支持。true:口语化回复。false:书面化回复(内容不易朗读时效果可能不佳)。null:模型自动选择口语化或书面化回复风格。
instructionsString系统消息,用于设定模型的目标或角色。示例:"你是一家五星级酒店的 AI 客服,负责解答客户关于房型、设施、价格和预订政策的问题。"
enableInputAudioTranscroffset-[-1px] text-[var(--qwencloud-sidebar-text-size)] leading-[var(--qwencloud-sidebar-text-leading)] font-normal text-neutral-700" style="padding:6px 12px 6px 24px" aria-label="展开/收起 GUI-Plus" aria-expanded="false">GUI-Plus
  • 语音合成
    语音识别
    语音对话
    音乐生成
    图片翻译
    多模态向量
    平台 API
    工具包与框架