非实时语音合成CosyVoice Java SDK参考

构造方法

public HttpSpeechSynthesizer()

创建HttpSpeechSynthesizer实例，使用默认配置。SDK会自动从环境变量DASHSCOPE_API_KEY或Constants.apiKey获取API Key。

callAndReturnAudio() - 非流式调用（返回音频数据）

方法签名：

public ByteBuffer callAndReturnAudio(HttpSpeechSynthesisParam param) throws ApiException, NoApiKeyException, InputRequiredException

参数说明：

返回值：ByteBuffer，包含完整的音频数据。可通过remaining()获取音频大小（字节）。

call() - 非流式调用（返回音频URL）

方法签名：

public HttpSpeechSynthesisResult call(HttpSpeechSynthesisParam param) throws ApiException, NoApiKeyException, InputRequiredException

参数说明：

返回值：HttpSpeechSynthesisResult对象，通过getAudioInfo().getUrl()获取音频下载URL，URL有效期有限，可通过getAudioInfo().getExpiresAt()获取过期时间。

streamCall() - 流式调用

方法签名：

public void streamCall(HttpSpeechSynthesisParam param, ResultCallback<HttpSpeechSynthesisResult> callback) throws ApiException, NoApiKeyException, InputRequiredException

参数说明：

该方法为异步调用，音频数据通过回调函数分片返回，适用于对首包延迟有要求的场景。

ResultCallback 回调方法：

com.alibaba.dashscope.common.ResultCallback是DashScope SDK提供的通用回调接口，需实现以下三个方法：

非流式调用

非流式调用会等待服务端合成完成后一次性返回结果。根据返回类型的不同，提供以下两种方式：

• callAndReturnAudio()：返回音频二进制数据（ByteBuffer），适用于直接保存或处理音频的场景。

• call()：返回音频URL，适用于需要通过URL下载音频的场景。

import com.alibaba.dashscope.audio.http_tts.AudioInfo;
import com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesisParam;
import com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesisResult;
import com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesizer;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

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

public class CosyVoiceSyncExample {
    static {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    /**
     * 非流式调用示例一：返回音频数据（ByteBuffer）
     * 调用callAndReturnAudio方法，阻塞等待合成完成后返回完整音频数据。
     */
    public static void syncCallReturnAudio() {
        HttpSpeechSynthesizer synthesizer = new HttpSpeechSynthesizer();

        HttpSpeechSynthesisParam param =
            HttpSpeechSynthesisParam.builder()
                .model("cosyvoice-v3-flash")  // 更换模型时，需同步更换为对应版本的音色
                .text("我家的后面有一个很大的花园。")
                .voice("longanyang")  // 该音色适用于cosyvoice-v3系列，cosyvoice-v2请使用longxiaochun_v2等v2音色
                .format("wav")
                .sampleRate(24000)
                // 未配置环境变量时，将下行替换为：apiKey("sk-xxx")，即替换为实际的API Key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                // 通过parameter方法设置额外参数
                // .parameter("seed", 1234)
                // .parameter("enable_ssml", true)
                .build();

        try {
            ByteBuffer audioData = synthesizer.callAndReturnAudio(param);
            if (audioData != null && audioData.hasRemaining()) {
                byte[] bytes = new byte[audioData.remaining()];
                audioData.get(bytes);

                try (FileOutputStream fos = new FileOutputStream("sync_output.wav")) {
                    fos.write(bytes);
                    System.out.println("Audio saved to sync_output.wav, size: " + bytes.length + " bytes");
                } catch (IOException e) {
                    System.err.println("Failed to save audio: " + e.getMessage());
                }
            }
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.err.println("Synthesis failed: " + e.getMessage());
        }
        System.exit(0);
    }

    /**
     * 非流式调用示例二：返回音频URL
     * 调用call方法，返回包含音频URL的结果对象，可通过URL下载音频文件。
     */
    public static void syncCallReturnUrl() {
        HttpSpeechSynthesizer synthesizer = new HttpSpeechSynthesizer();

        HttpSpeechSynthesisParam param =
            HttpSpeechSynthesisParam.builder()
                .model("cosyvoice-v3-flash")  // 更换模型时，需同步更换为对应版本的音色
                .text("我家的后面有一个很大的花园。")
                .voice("longanyang")  // 该音色适用于cosyvoice-v3系列，cosyvoice-v2请使用longxiaochun_v2等v2音色
                .format("wav")
                .sampleRate(24000)
                // 未配置环境变量时，将下行替换为：apiKey("sk-xxx")，即替换为实际的API Key
                .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                .build();

        try {
            HttpSpeechSynthesisResult result = synthesizer.call(param);
            System.out.println("Request ID: " + result.getRequestId());

            if (result.hasAudioUrl()) {
                AudioInfo audioInfo = result.getAudioInfo();
                System.out.println("Audio URL: " + audioInfo.getUrl());
                System.out.println("Expires At: " + audioInfo.getExpiresAt());
                System.out.println("Remaining Time: " + audioInfo.getRemainingSeconds() + " seconds");
            }
        } catch (ApiException | NoApiKeyException | InputRequiredException e) {
            System.err.println("Synthesis failed: " + e.getMessage());
        }
    }

    public static void main(String[] args) {
        // 非流式调用示例一：返回音频数据（ByteBuffer）
        // syncCallReturnAudio();
        // 非流式调用示例二：返回音频URL
        syncCallReturnUrl();
    }
}

流式调用

流式调用通过回调函数分片返回音频数据，无需等待合成完成即可开始处理，适用于对首包延迟有要求的实时播放场景。

import com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesisParam;
import com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesisResult;
import com.alibaba.dashscope.audio.http_tts.HttpSpeechSynthesizer;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.exception.ApiException;
import com.alibaba.dashscope.exception.InputRequiredException;
import com.alibaba.dashscope.exception.NoApiKeyException;

import java.io.FileOutputStream;
import java.io.IOException;
import java.util.concurrent.CountDownLatch;

public class CosyVoiceStreamExample {
    static {
        // 以下为华北2（北京）地域的配置，调用时请将"{WorkspaceId}"替换为真实的业务空间ID，各地域的配置不同。
        Constants.baseHttpApiUrl = "https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1";
    }

    public static void streamCallWithCallback() {
        HttpSpeechSynthesizer synthesizer = new HttpSpeechSynthesizer();

        HttpSpeechSynthesisParam param =
                HttpSpeechSynthesisParam.builder()
                        .model("cosyvoice-v3-flash")  // 更换模型时，需同步更换为对应版本的音色
                        .text("今天天气真好，适合出去玩。")
                        .voice("longanyang")  // 该音色适用于cosyvoice-v3系列，cosyvoice-v2请使用longxiaochun_v2等v2音色
                        .format("wav")
                        .sampleRate(24000)
                        // 未配置环境变量时，将下行替换为：apiKey("sk-xxx")，即替换为实际的API Key
                        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
                        .build();

        CountDownLatch latch = new CountDownLatch(1);

        // 新增：创建输出文件流
        try (FileOutputStream fos = new FileOutputStream("output.wav")) {

            synthesizer.streamCall(param,
                    new ResultCallback<HttpSpeechSynthesisResult>() {
                        private int chunkCount = 0;

                        @Override
                        public void onEvent(HttpSpeechSynthesisResult result) {
                            chunkCount++;
                            if (result.hasAudioData()) {
                                System.out.println("Received chunk #" + chunkCount
                                        + ", size: " + result.getAudioDataSize() + " bytes");
                                try {
                                    fos.write(result.getAudioData());
                                } catch (IOException e) {
                                    System.err.println("Failed to write audio data: " + e.getMessage());
                                }
                            }
                            if (result.getRequestId() != null) {
                                System.out.println("Request ID: " + result.getRequestId());
                            }
                        }

                        @Override
                        public void onComplete() {
                            System.out.println("Synthesis completed, total chunks: " + chunkCount);
                            System.out.println("Audio saved to output.wav");
                            latch.countDown();
                        }

                        @Override
                        public void onError(Exception e) {
                            System.err.println("Error during synthesis: " + e.getMessage());
                            latch.countDown();
                        }
                    });

            latch.await();

        } catch (ApiException | NoApiKeyException | InputRequiredException | InterruptedException e) {
            System.err.println("Failed: " + e.getMessage());
        } catch (IOException e) {
            System.err.println("Failed to create output file: " + e.getMessage());
        }
    }

    public static void main(String[] args) {
        streamCallWithCallback();
        System.exit(0);
    }
}