Beta: The API is currently in beta and may change.

API Reference

The Tontaube API provides text-to-speech capabilities via a simple REST interface.

Get Started

  1. 1 Create an API key in your Dashboard
  2. 2 Include the key in the X-API-Key header on every request
  3. 3 Make requests to the base URL below
Base URL https://api.tontaube.ai/v1

Authentication

All requests require an X-API-Key header with a valid API key. Keys start with ttb_live_.

Example Request 
curl https://api.tontaube.ai/v1/speech/speakers \
  -H "X-API-Key: ttb_live_..."
GET /speech/speakers

Returns a list of available speakers for speech generation.

Response Body

Returns an array of speaker objects.

Field Type Description
id string (UUID) Unique speaker identifier
name string Display name
voice_key string Internal voice key
gender string | null Speaker gender
language_restrictions string[] | null Supported languages (null = all)
curl 
curl https://api.tontaube.ai/v1/speech/speakers \
  -H "X-API-Key: ttb_live_..."
Response
[
  {
    "id": "32b39669-fe31-479c-b3e4-527998b238f7",
    "name": "Frederick",
    "voice_key": "32b39669-fe31-479c-b3e4-527998b238f7",
    "gender": "male",
    "language_restrictions": ["en"]
  },
  ...
]
POST /speech/generate

Generate speech audio from text. Deducts balance based on character count.

Request Body

Parameter Type Required Description
text string Yes Text to synthesize (max 30,000 characters)
speaker_id string Yes UUID of speaker from /speech/speakers
language string No Only English is currently supported; defaults to "en".
format string No Only opus is supported; this is also the default when omitted.
temperature number No Controls speech variability. Between 0.5 and 2.0; defaults to 1.0.

Response

Returns the generated audio as a binary stream with the appropriate content-type.

Response Headers

Header Description
X-Sample-Rate Sample rate of the generated audio
X-Audio-Duration Duration in seconds
X-Cost-USD Cost of this request in USD
X-Balance-USD Remaining account balance in USD
curl 
curl -X POST https://api.tontaube.ai/v1/speech/generate \
  -H "X-API-Key: ttb_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello world",
    "speaker_id": "32b39669-fe31-479c-b3e4-527998b238f7",
    "language": "en",
    "format": "opus"
  }' \
  --output speech.opus.m4a

Python SDK

A first-class Python client with async support, automatic retries, and type hints. Available on PyPI — install with pip install tontaube.

Python
pip install tontaube
tontaube_example.py 
import tontaube

with tontaube.Client(api_key="ttb_live_...") as client:
    speakers = client.list_speakers()
    for speaker in speakers:
        print(f"{speaker.name} ({speaker.voice_style}), id: {speaker.id}")

    response = client.generate_speech(
        text="I am here to help you with your project. Tell me what we are building today, and I will get right to work.",
        speaker_id=speakers[0].id,
        temperature=0.8,
    )

with open("speech.opus.m4a", "wb") as f:
    f.write(response.content)

print(f"Duration: {response.audio_duration}s, Cost: ${response.cost_usd}")
print("Result saved to speech.opus.m4a")