廖咽薪倨通过 start.spring.io 或其他构建基础的Spring Boot工程，根据你构建应用的需要增加一些依赖，比如最后用接口提供服务的话，可以加入web模块：
org.springframework.boot
spring-boot-starter-web
- 注册 UnifiedTTS，获取 API Key
前往 UnifiedTTS 官网注册账号（直接GitHub登录即可）
从左侧菜单进入"API密钥"页面，创建 API Key；
创建API Key
存好API Key，后续需要使用
- 集成 UnifiedTTS API
下面根据API 文档：https://unifiedtts.com/zh/api-docs/tts-sync 实现一个可运行的参考实现，包括配置文件、请求模型、服务类与控制器。
3.1 配置文件（application.properties）
unified-tts.host=https://unifiedtts.com
unified-tts.api-key=your-api-key-here
这里unifiedtts.api-key参数记得替换成之前创建的ApiKey。
3.2 配置加载类
@Data
@ConfigurationProperties(prefix = "unified-tts")
public class UnifiedTtsProperties {
private String host;
private String apiKey;
}
3.3 请求封装和响应封装
@Data
@AllArgsConstructor
@NoArgsConstructor
public class UnifiedTtsRequest {
private String model;
private String voice;
private String text;
private Double speed;
private Double pitch;
private Double volume;
private String format;
}
@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;
}
}
UnifiedTTS 抽象了不同模型的请求，这样用户可以用同一套请求参数标准来实现对不同TTS模型的调用，这个非常方便。所以，为了简化TTS的客户端调用，非常推荐使用 UnifiedTTS。
3.3 服务实现（调用 UnifiedTTS）
使用 Spring Boot自带的RestClient HTTP客户端来实现UnifiedTTS的功能实现类，提供两个实现：
接收音频字节并返回。
@Service
public class UnifiedTtsService {
private final RestClient restClient;
private final UnifiedTtsProperties properties;
public UnifiedTtsService(RestClient restClient, UnifiedTtsProperties properties) {
this.restClient = restClient;
this.properties = properties;
}
/**
* 调用 UnifiedTTS 同步 TTS 接口，返回音频字节数据。
*
*
请求头：
*
-
*
- Content-Type: application/json
*
- X-API-Key: 来自配置的 API Key
*
- Accept: 接受二进制流或常见 mp3/mpeg 音频类型
*
*
* @param request 模型、音色、文本、速度/音调/音量、输出格式等参数
* @return 音频二进制字节（例如 mp3）
* @throws IllegalStateException 当服务端返回非 2xx 或无内容时抛出
*/
public byte[] synthesize(UnifiedTtsRequest request) {
ResponseEntity 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());
}
/**
* 调用合成并将音频写入指定文件。
*
*
若输出路径的父目录不存在，会自动创建；失败时抛出运行时异常。
*
* @param request TTS 请求参数
* @param outputPath 目标文件路径（例如 output.mp3）
* @return 实际写入的文件路径
*/
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 单元测试
@SpringBootTest
class UnifiedTtsServiceTest {
@Autowired
private UnifiedTtsService unifiedTtsService;
@Test
void testRealSynthesizeAndDownloadToFile() throws Exception {
UnifiedTtsRequest req = new UnifiedTtsRequest(
"edge-tts",
"en-US-JennyNeural",
"Hello, this is a test of text to speech synthesis.",
1.0,
1.0,
1.0,
"mp3"
);
// 调用真实接口，断言返回结构
UnifiedTtsResponse resp = unifiedTtsService.synthesize(req);
assertNotNull(resp);
assertTrue(resp.isSuccess(), "Response should be success");
assertNotNull(resp.getData(), "Response data should not be null");
assertNotNull(resp.getData().getAudioUrl(), "audio_url should be present");
// 在当前工程目录下生成测试结果目录并写入文件
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);
System.out.println("UnifiedTTS test output: " + written.toAbsolutePath());
assertTrue(Files.exists(written), "Output file should exist");
assertTrue(Files.size(written) > 0, "Output file size should be > 0");
}
}
- 运行与验证
执行单元测试之后，可以在工程目录test-result下找到生成的音频文件：
- 常用参数与音色选择
目前支持的常用参数如下图所示：
对于model和voice参数可以因为内容较多，可以前往API文档查看。
小结
本文展示了如何在 Spring Boot 中集成 UnifiedTTS 的 EdgeTTS 能力，实现文本转语音并输出为 mp3。UnifiedTTS 通过统一的 API 屏蔽了不同 TTS 模型的差异，使你无需维护多个 SDK，即可在成本与效果之间自由切换。根据业务需求，你可以进一步完善异常处理、缓存与并发控制，实现更可靠的生产级 TTS 服务。