How to Add Free Edge TTS to Your Spring Boot Application in Minutes

In scenarios that require Text‑to‑Speech (TTS) such as voice assistants or content broadcasting, the Java ecosystem lacks a native Edge TTS client like Python. UnifiedTTS provides a free Edge TTS API along with Azure, MiniMax, and Elevenlabs models, allowing seamless switching between models and voices.

Practical Example

1. Build a Spring Boot Application

Generate a Spring Boot project via start.spring.io or any other initializer and add the spring-boot-starter-web dependency if you plan to expose an HTTP interface.

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

2. Register UnifiedTTS and Obtain an API Key

Visit the UnifiedTTS website and sign up with GitHub.

From the left menu open the “API Key” page and create a new key.

Save the key for later use.

3. Integrate UnifiedTTS API

3.1 Configuration File (application.properties)

unified-tts.host=https://unifiedtts.com
unified-tts.api-key=your-api-key-here

Replace your-api-key-here with the key you created.

3.2 Configuration Properties Class

@Data
@ConfigurationProperties(prefix = "unified-tts")
public class UnifiedTtsProperties {
    private String host;
    private String apiKey;
}

3.3 Request and Response Models

@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;
    }
}

3.4 Service Implementation

@Service
public class UnifiedTtsService {
    private final RestClient restClient;
    private final UnifiedTtsProperties properties;

    public UnifiedTtsService(RestClient restClient, UnifiedTtsProperties properties) {
        this.restClient = restClient;
        this.properties = properties;
    }

    /**
     * Call UnifiedTTS synchronous TTS endpoint and return audio bytes.
     */
    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());
    }

    /**
     * Synthesize and write the audio to a file.
     */
    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.5 Unit Test

@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());
        assertNotNull(resp.getData().getAudioUrl());
        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");
    }
}

4. Run and Verify

After the test finishes, the generated audio file can be found under the test-result directory.

5. Common Parameters and Voice Selection

The most frequently used parameters are illustrated below.

For a full list of model and voice values, refer to the API documentation.

Conclusion

This article demonstrates how to integrate UnifiedTTS's Edge TTS capability into a Spring Boot application, producing MP3 audio output. UnifiedTTS abstracts the differences between various TTS models, allowing you to switch cost‑effective services without maintaining multiple SDKs. You can further enhance error handling, caching, and concurrency for production‑grade TTS services.