Package com.tnsai.tools.audio

Class TextToSpeechTools

java.lang.Object

com.tnsai.tools.audio.TextToSpeechTools

public class TextToSpeechTools
extends Object

Function-shape text-to-speech tools — non-OpenAI providers, complementing MediaTools.openaiTts(String, String, String) which already covers OpenAI TTS. Wraps three popular alternatives behind a uniform @Tool surface so an LLM can choose by quality / latency / cost at call time:

Method	Backend	Auth	Strength
elevenlabsTts(java.lang.String, java.lang.String, java.lang.String)	ElevenLabs Multilingual v2	ELEVENLABS_API_KEY	Quality leader, voice cloning
cartesiaTts(java.lang.String, java.lang.String, java.lang.String)	Cartesia Sonic-2	CARTESIA_API_KEY	Latency leader (~75ms TTFB)
deepgramTts(java.lang.String, java.lang.String)	Deepgram Aura	DEEPGRAM_API_KEY	Cheapest, simple voice picker

All three return a uniform {provider, model, audio_uri} JSON envelope where audio_uri is a data:audio/mpeg;base64,... URL — the same self-describing shape Stability uses in ImageGenTools.stabilityGenerate(java.lang.String, java.lang.String, java.lang.String). This keeps tool-calling agents from needing per-provider plumbing for what is the same logical primitive ("synthesise this text").

Implementation deliberately uses OkHttp + Jackson only — no vendor SDK is pulled in, matching the rest of tnsai-tools.

Cost notes (April 2026 list pricing — providers may change)

• ElevenLabs Multilingual v2: ~$0.18 / 1k chars (Creator tier)
• Cartesia Sonic-2: ~$0.030 / 1k chars (one of the cheapest premium voices)
• Deepgram Aura: ~$0.015 / 1k chars (cheapest of the three)

Since:

0.8.4

See Also:

• for the OpenAI TTS / Whisper STT path
• for the matching STT side

Constructor Summary

Constructors

Constructor	Description
TextToSpeechTools()	Default no-arg ctor — the only one BuiltInTool.TEXT_TO_SPEECH_TOOLS ever calls.

Method Summary

Modifier and Type	Method	Description
String	cartesiaTts(String text, String voiceId, String model)
String	deepgramTts(String text, String model)
String	elevenlabsTts(String text, String voiceId, String model)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

TextToSpeechTools

public TextToSpeechTools()

Default no-arg ctor — the only one BuiltInTool.TEXT_TO_SPEECH_TOOLS ever calls.

Method Details

elevenlabsTts

@Tool(name="elevenlabs_tts",
      description="Synthesize speech from {text} using ElevenLabs. Returns a JSON object with an `audio_uri` field \u2014 a `data:audio/mpeg;base64,\u2026` data URI ready for playback or attachment. {voiceId} accepts any ElevenLabs voice ID (default Rachel `21m00Tcm4TlvDq8ikWAM`). {model} controls quality/latency: `eleven_multilingual_v2` (best, default), `eleven_turbo_v2_5` (fast, cheaper), `eleven_flash_v2_5` (fastest). Max input 2000 chars. Requires ELEVENLABS_API_KEY.")
public String elevenlabsTts(@ToolParam(description="Text to synthesize (max 2000 chars)")
 String text,
 @ToolParam(description="ElevenLabs voice ID; default Rachel `21m00Tcm4TlvDq8ikWAM`",required=false,defaultValue="21m00Tcm4TlvDq8ikWAM")
 String voiceId,
 @ToolParam(description="Model \u2014 `eleven_multilingual_v2` (best, default), `eleven_monolingual_v1`, `eleven_turbo_v2_5`, `eleven_flash_v2_5`",required=false,defaultValue="eleven_multilingual_v2")
 String model)
                     throws IOException

Throws:

IOException

cartesiaTts

@Tool(name="cartesia_tts",
      description="Synthesize speech from {text} using Cartesia Sonic-2 \u2014 the latency leader (~75ms TTFB), good when you need realtime/streaming-feeling responses. Returns a JSON object with an `audio_uri` field (data:audio/mpeg;base64,\u2026). {voiceId} accepts any Cartesia voice ID. {model} is `sonic-2` (default), `sonic-english`, or `sonic-multilingual`. Max input 2000 chars. Requires CARTESIA_API_KEY.")
public String cartesiaTts(@ToolParam(description="Text to synthesize (max 2000 chars)")
 String text,
 @ToolParam(description="Cartesia voice ID; pick one from cartesia.ai/voices",required=false,defaultValue="a0e99841-438c-4a64-b679-ae501e7d6091")
 String voiceId,
 @ToolParam(description="Model \u2014 `sonic-2` (latest), `sonic-english`, `sonic-multilingual`",required=false,defaultValue="sonic-2")
 String model)
                   throws IOException

Throws:

IOException

deepgramTts

@Tool(name="deepgram_tts",
      description="Synthesize speech from {text} using Deepgram Aura \u2014 the cheapest of the non-OpenAI options (~$0.015/1k chars). Returns a JSON object with an `audio_uri` field (data:audio/mpeg;base64,\u2026). {model} picks the voice directly: `aura-asteria-en` (default, female), `aura-luna-en`, `aura-orion-en` (male), etc. Max input 2000 chars. Requires DEEPGRAM_API_KEY.")
public String deepgramTts(@ToolParam(description="Text to synthesize (max 2000 chars)")
 String text,
 @ToolParam(description="Deepgram Aura voice/model \u2014 e.g. `aura-asteria-en` (default), `aura-luna-en`, `aura-stella-en`, `aura-orion-en`",required=false,defaultValue="aura-asteria-en")
 String model)
                   throws IOException

Throws:

IOException