在一些需要高質(zhì)量文本轉(zhuǎn)語音（TTS）的場(chǎng)景中（比如：有聲書配音、播客等）。之前介紹的EdgeTTS方案可能效果沒有那么好。此時(shí)就比較推薦使用 MiniMax、CosyVoice這些提供的音色，這些音色的效果會(huì)更加擬人、逼真，接近真人發(fā)音。這里依然通過 UnifiedTTS 的統(tǒng)一接口來對(duì)接，這樣我們可以在不更換客戶端代碼的前提下，快速在 MiniMax、CosyVoice等引擎之間做無縫切換。本文將引導(dǎo)讀者從零到一把MiniMax、CosyVoice的語音合成能力整合到你的Spring Boot應(yīng)用中，最后也會(huì)給出一個(gè)可復(fù)制的 Spring Boot 集成示例，

實(shí)戰(zhàn)

1. 構(gòu)建 Spring Boot 應(yīng)用

通過 start.spring.io 或其他構(gòu)建基礎(chǔ)的Spring Boot工程，根據(jù)你構(gòu)建應(yīng)用的需要增加一些依賴，比如最后用接口提供服務(wù)的話，可以加入web模塊、lombok等常用依賴：

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>

    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>
</dependencies>

2. 注冊(cè) UnifiedTTS，獲取 API Key

• 前往 UnifiedTTS 注冊(cè)并獲取 API Key

• 記錄下創(chuàng)建的ApiKey，后續(xù)程序配置的時(shí)候需要使用

3. 集成 UnifiedTTS API（使用 MiniMax、CosyVoice）

下面給出參考實(shí)現(xiàn)，包括配置、DTO、服務(wù)與控制器。與 EdgeTTS 版本相比，主要是將 model 與 voice 改為 MiniMax/CosyVoice 支持的參數(shù)。

3.1 配置文件（application.properties）

unified-tts.host=https://unifiedtts.com
unified-tts.api-key=${UNIFIEDTTS_API_KEY}

這里 unified-tts.api-key 請(qǐng)?zhí)鎿Q為你在 UnifiedTTS 控制臺(tái)創(chuàng)建的 API Key。

3.2 配置加載類與請(qǐng)求/響應(yīng)封裝

// src/main/java/com/example/tts/config/UnifiedTtsProperties.java
@Data
@ConfigurationProperties(prefix = "unified-tts")
public class UnifiedTtsProperties {
    private String host;
    private String apiKey;
}

// src/main/java/com/example/tts/dto/UnifiedTtsRequest.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class UnifiedTtsRequest {
    private String model;   // 例：minimax-tts 或 cosyvoice-tts
    private String voice;   // 例：zh_female_1（按模型支持的音色選擇）
    private String text;
    private Double speed;   // 語速（可選）
    private Double pitch;   // 音高（可選）
    private Double volume;  // 音量（可選）
    private String format;  // mp3/wav/ogg
}

// src/main/java/com/example/tts/dto/UnifiedTtsResponse.java
@Data
@AllArgsConstructor
@NoArgsConstructor
public class UnifiedTtsResponse {
    private boolean success;
    private String message;
    private long timestamp;
    private UnifiedTtsResponseData data;

    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public static class UnifiedTtsResponseData {
        @JsonProperty("request_id")
        private String requestId;

        @JsonProperty("audio_url")
        private String audioUrl;

        @JsonProperty("file_size")
        private long fileSize;
    }
}

3.3 服務(wù)實(shí)現(xiàn)（RestClient 同步合成）

// src/main/java/com/example/tts/service/UnifiedTtsService.java
package com.example.tts.service;

import com.example.tts.dto.UnifiedTtsRequest;
import com.example.tts.config.UnifiedTtsProperties;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Path;

@Service
public class UnifiedTtsService {

    private final RestClient restClient;
    private final UnifiedTtsProperties properties;

    public UnifiedTtsService(UnifiedTtsProperties properties) {
        this.properties = properties;
        this.restClient = RestClient.builder()
                .baseUrl(properties.getHost())
                .build();
    }

    public byte[] synthesize(UnifiedTtsRequest request) {
        ResponseEntity<byte[]> response = restClient
                .post()
                .uri("/api/v1/common/tts-sync")
                .contentType(MediaType.APPLICATION_JSON)
                .accept(MediaType.APPLICATION_OCTET_STREAM, MediaType.valueOf("audio/mpeg"), MediaType.valueOf("audio/mp3"))
                .header("X-API-Key", properties.getApiKey())
                .body(request)
                .retrieve()
                .toEntity(byte[].class);

        if (response.getStatusCode().is2xxSuccessful() && response.getBody() != null) {
            return response.getBody();
        }
        throw new IllegalStateException("UnifiedTTS synthesize failed: " + response.getStatusCode());
    }

    public Path synthesizeToFile(UnifiedTtsRequest request, Path outputPath) {
        byte[] data = synthesize(request);
        try {
            if (outputPath.getParent() != null) {
                Files.createDirectories(outputPath.getParent());
            }
            Files.write(outputPath, data);
            return outputPath;
        } catch (IOException e) {
            throw new RuntimeException("Failed to write TTS output to file: " + outputPath, e);
        }
    }
}

3.4 單元測(cè)試（MiniMax/CosyVoice）

// src/test/java/com/example/tts/UnifiedTtsServiceTest.java
@SpringBootTest
class UnifiedTtsServiceTest {

    @Autowired
    private UnifiedTtsService unifiedTtsService;

    @Test
    void testSynthesizeToFileWithMiniMax() throws Exception {
        UnifiedTtsRequest req = new UnifiedTtsRequest(
            "speech-02-turbo",
            "Chinese (Mandarin)_Gentle_Youth",
            "你好，歡迎使用 UnifiedTTS 的 MiniMax 模型配音。",
            1.0,
            0.0,
            1.0,
            "mp3"
        );

        Path projectDir = Paths.get(System.getProperty("user.dir"));
        Path resultDir = projectDir.resolve("test-result");
        Files.createDirectories(resultDir);
        Path out = resultDir.resolve(System.currentTimeMillis() + ".mp3");

        Path written = unifiedTtsService.synthesizeToFile(req, out);
        assertTrue(Files.exists(written), "Output file should exist");
        assertTrue(Files.size(written) > 0, "Output file size should be > 0");
    }
}

4. 運(yùn)行與驗(yàn)證

執(zhí)行單元測(cè)試之后，可以在工程目錄 test-result 下找到生成的音頻文件：

如果你希望拿到音頻 URL 或 Base64，可將接口 accept 改為 application/json 并解析返回結(jié)果，再做下載或解碼。

5. 常用參數(shù)與音色選擇

• model：speech-02-turbo（示例），不同規(guī)格以官方為準(zhǔn)；
• voice：示例 Chinese (Mandarin)_Gentle_Youth 等；
• rate：語速（建議范圍 0.8–1.2）；
• pitch：音高（建議范圍 -3–+3）；
• volume：音量（建議范圍 0.8–1.2）；
• format：mp3（常用）、wav（無損但體積大）、ogg 等。

模型model與音色voice 這里推薦使用 minimax 或 cosyvoice的模型和音色。

具體支持的參數(shù)可以在API文檔中的接口查詢可以填入的參數(shù)，比如：

model支持，調(diào)用一下可以看到，支持的模型有：

每個(gè)模型下支持的voice，也可以調(diào)用接口查詢，比如這里嘗試調(diào)用minimax支持的voice：

6. 異常處理與重試建議

• 超時(shí)與網(wǎng)絡(luò)錯(cuò)誤：設(shè)置 timeout-ms，在 onErrorResume 中記錄原因；
• 4xx/5xx：區(qū)分鑒權(quán)失敗、限流、服務(wù)器錯(cuò)誤并上報(bào)；
• 重試策略：對(duì)臨時(shí)性錯(cuò)誤采用指數(shù)退避（帶抖動(dòng)）；
• 并發(fā)與限流：高并發(fā)場(chǎng)景實(shí)現(xiàn)隊(duì)列或令牌桶；
• 緩存：對(duì)重復(fù)合成按 text+voice+params 做緩存，降低成本與時(shí)延。

7. 生產(chǎn)化建議

• 安全：API Key 從環(huán)境變量或密鑰管理系統(tǒng)注入；
• 監(jiān)控：記錄合成耗時(shí)、失敗原因、重試比率；
• 存儲(chǔ)：落盤或?qū)ο蟠鎯?chǔ)（如 S3）并設(shè)置生命周期；
• 規(guī)范：統(tǒng)一 DTO 與服務(wù)返回結(jié)構(gòu)，便于多模型擴(kuò)展；
• 擴(kuò)展：通過配置切換 Azure/Edge/Elevenlabs/MiniMax 等模型。

小結(jié)

通過 UnifiedTTS，我們?cè)?Spring Boot 中僅需調(diào)整 model 與 voice 即可切換到 MiniMax、CosyVoice、甚至最強(qiáng)的Elevenlabs，實(shí)現(xiàn)文本轉(zhuǎn)語音。統(tǒng)一接口簡(jiǎn)化了多引擎維護(hù)成本，讓你能在成本、音色與效果間自由選擇。根據(jù)業(yè)務(wù)需求，還可進(jìn)一步完善異常處理、緩存與并發(fā)控制，構(gòu)建更可靠的生產(chǎn)級(jí) TTS 服務(wù)。

另外，對(duì)比了官方API和UnifiedTTS的價(jià)格，后者更具備價(jià)格優(yōu)勢(shì)，所以非常推薦獨(dú)立開發(fā)者或者初創(chuàng)產(chǎn)品的時(shí)候使用。不論從開發(fā)成本還是API成本角度看都是最佳選擇。