---
name: tts-buddy
description: Generate natural-sounding text-to-speech audio with TTS Buddy. Use when converting text, Markdown, documents, or webpages into MP3 audio, selecting voices, using the TTSBuddy CLI, or calling the Agent TTS API.
---
# TTS Buddy

Use TTS Buddy to convert text, Markdown, documents, and webpages into downloadable MP3 audio. Prefer the CLI for local files and shell pipelines. Use the HTTP API for apps, services, MCP tools, and automation that need direct request/response control.

## References

- API reference: https://www.ttsbuddy.com/docs/developers/api-reference
- CLI guide: https://www.ttsbuddy.com/docs/developers/cli
- API keys: https://www.ttsbuddy.com/docs/developers/api-keys
- Text-to-speech features: https://www.ttsbuddy.com/docs/features/text-to-speech
- Markdown access: https://www.ttsbuddy.com/docs/guides/markdown-access

## Authentication

Create API keys in Dashboard -> Settings. Keys use `ttsb_<public_id>_<secret>` format and are shown only once. Send direct API requests with `Authorization: Bearer ttsb_<public_id>_<secret>`. Prefer `TTSBUDDY_API_KEY` or `ttsbuddy config set key ...` for CLI usage. Never expose `ttsb_` secrets in client-side code, git, logs, shell history, or shared transcripts.

## CLI Workflow

Install with Homebrew (`brew install ngelik/tap/ttsbuddy`), Go (`go install github.com/ngelik/ttsbuddy-cli@latest`), or GitHub Releases.

```bash
ttsbuddy config set key ttsb_your_key_here
ttsbuddy speak "Hello world"
ttsbuddy speak -f article.md -o article.mp3
cat notes.txt | ttsbuddy speak -
ttsbuddy voices
ttsbuddy status <job_id> --watch
```

Markdown files are preprocessed by default for cleaner narration; use `--raw` only when literal Markdown should be spoken.

## Direct API Workflow

Base endpoint: `https://ttsbuddy.com/v1/agent-tts`. Submit with `POST /v1/agent-tts` and JSON fields `text`, optional `voice`, optional `speed`. Include `Content-Type: application/json`, `Authorization`, and an `Idempotency-Key` for safe retries. A `200` response includes `audio_url`; a `202` response means poll `GET /v1/agent-tts?id=<job_id>` until `completed`.

## Defaults And Limits

Default voice is `af_heart`. Fast voices for automation are `st_f1`, `st_f2`, `st_m1`, and `st_m2`. Speed range is `0.5` to `1.5`; fast voices should not exceed `1.0`. Max text length is 500,000 characters per request. Rate limits are POST 1 request/minute and GET 30 requests/minute per API key. Audio URLs are temporary; download completed audio promptly.

## Error Handling

Retry `RATE_LIMITED`, `TTS_PROVIDER_ERROR`, and `INTERNAL_ERROR` with backoff. For `INVALID_KEY`, ask the user to create or configure a new key. For `TEXT_TOO_LONG`, split the input. For `USAGE_LIMIT_EXCEEDED` or `INACTIVE_SUBSCRIPTION`, direct the user to billing or plan settings.