CLI - Supertone API Documentation

Convert text to speech right from your terminal — no code required. The Supertone CLI synthesizes from strings, files, or stdin, streams to your speakers in real time, batches whole directories, and manages voices, usage, and credits. Source: supertone-inc/supertone-cli.

Quick start

Install

pip install "supertone-cli[stream]"

Requires Python 3.12+. The [stream] extra adds real-time playback.

Add your API key

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."

Hear it

supertone tts "My first words from the terminal." \
  --voice 91992bbd4758bdcf9c9b01 -m sona_speech_1 --stream

If you hear audio, you’re all set. ✅

Building into application code instead? Use the Python or TypeScript SDK. For AI agents, see MCP.

Installation

pip
with streaming

pip install supertone-cli

pip install "supertone-cli[stream]"

Requires Python 3.12+. The [stream] extra enables real-time playback to your system speakers via --stream.

Authenticate

Environment variable
Config file

export SUPERTONE_API_KEY="Kp9mZ3xQ7v..."

supertone config init             # interactive setup
supertone config set api_key Kp9mZ3xQ7v...

Stored at ~/.config/supertone/config.toml.

Set defaults to type less

Save defaults once and omit the matching flags on every call:

Config key	Used when omitted	Default
`api_key`	always	—
`default_voice`	`--voice` not passed	—
`default_model`	`--model` not passed	`sona_speech_2`
`default_lang`	`--lang` not passed	`ko`

supertone config set default_voice 20160a4c5ba38967330c84
supertone config set default_lang en

Synthesize speech

# From a string
supertone tts "Hello from the terminal." --voice VOICE_ID -o output.wav

# From a file
supertone tts -i input.txt -v VOICE_ID -o output.wav

# From stdin (pipe-friendly)
echo "Piped text." | supertone tts -v VOICE_ID -o output.wav

# Play in real time instead of saving (needs the [stream] extra)
supertone tts "This plays back live." -v VOICE_ID -m sona_speech_1 --stream

# Tune format and voice settings
supertone tts "Slower and lower." -v VOICE_ID --output-format mp3 --speed 0.9 --pitch -2

# Batch a whole folder — one audio file per input
supertone tts -i scripts/ --outdir audio/ -v VOICE_ID

Manage voices

supertone voices list                                  # preset voices provided by Supertone
supertone voices list --type custom                    # only your cloned voices
supertone voices search --lang en --gender female      # filter presets
supertone voices get VOICE_ID                         # full detail
supertone voices clone --name "My Voice" --sample sample.wav
supertone voices edit VOICE_ID --name "Renamed"
supertone voices delete VOICE_ID --yes               # --yes skips confirmation

Predict duration & track usage

tts-predict estimates duration and credit cost without spending credits — handy before a large batch.

supertone tts-predict "How long will this be?" -v VOICE_ID

supertone usage balance
supertone usage analytics --start 2026-04-01 --end 2026-04-30
supertone usage voices    --start 2026-04-01 --end 2026-04-30

Recipes

Narrate a folder of scripts

Drop your .txt files in one directory and synthesize them all at once:

supertone tts -i chapters/ --outdir narration/ -v VOICE_ID --output-format mp3

Speak an LLM's output live

Pipe any command’s text straight into real-time speech:

my-llm "Summarize today's headlines" | supertone tts -v VOICE_ID -m sona_speech_1 --stream

Find your custom voices with jq

--format json makes any read command scriptable:

supertone voices list --type custom --format json | jq '.[].name'

Estimate cost before a batch

Loop over inputs and sum predicted durations before spending credits:

for f in scripts/*.txt; do supertone tts-predict -i "$f" -v VOICE_ID; done

Reference

Supported models

sona_speech_1, sona_speech_2, sona_speech_2_flash, sona_speech_2t, supertonic_api_1, supertonic_api_3. See Models for capabilities and trade-offs.

Exit codes

Code	Meaning
`0`	Success
`1`	API error
`2`	Authentication error
`3`	Input validation error
`130`	Interrupted (Ctrl-C)

Troubleshooting

command not found: supertone

The install directory isn’t on your PATH, or you installed inside a virtual environment that isn’t active. Re-activate the venv, or reinstall with pip install --user supertone-cli and ensure the user scripts directory is on your PATH.

Authentication error (exit code 2)

Your API key is missing or invalid. Check echo $SUPERTONE_API_KEY, or run supertone config set api_key your-api-key. Get a key from the Developer Console.

--stream produces no audio

Real-time playback requires the streaming extra (pip install "supertone-cli[stream]") and the sona_speech_1 model — pass -m sona_speech_1. Other models return “Streaming requires sona_speech_1”; to use them, save to a file with -o output.wav instead.

Out of credits (402)

Synthesis stops when your balance runs out. Check it with supertone usage balance and top up in the Developer Console.

MCP

Let AI agents call Supertone through the Model Context Protocol.

Python SDK

The same API for application code.

​Quick start

​Installation

​Authenticate

​Synthesize speech

​Manage voices

​Predict duration & track usage

​Recipes

​Reference

​Troubleshooting

​Related

MCP