SpeechifyAI Cookbook

Focused, runnable recipes for the Speechify Text-to-Speech API.

Each recipe is small, self-contained, and does one thing — copy a folder, add your API key, and run it.

Quick start

# 1. Get an API key: https://platform.speechify.ai/api-keys
# 2. Pick a recipe below and follow its README.

The fastest path:

cd recipes/audio/typescript/sdk/quickstart
cp .env.example .env        # paste your SPEECHIFY_API_KEY
pnpm install && pnpm start  # writes output.mp3

Recipes

Recipes are organized by product → language → flavor → recipe:

recipes/<product>/<language>/{sdk,native}/<recipe>/

• SDK — uses an official Speechify SDK for that language.
• Native — calls the REST API directly (no SDK), e.g. fetch in TS, requests in Python, curl in Bash.

Audio — TypeScript

Recipe	Flavor	Description
quickstart	SDK	Synthesize speech to an MP3 file.
quickstart	Native	Same, calling the REST API directly with fetch.
streaming	SDK	Stream audio to disk as it is generated.
streaming	Native	Streaming via raw fetch + pipeline.
ssml-emotion	SDK	Control emotion, pitch, rate, pauses & emphasis via SSML.
ssml-emotion	Native	Same SSML controls, via raw fetch.
speech-marks	SDK	Word-level timestamps → WebVTT captions.
speech-marks	Native	Same captions, via raw fetch.
voice-cloning	SDK	Clone a voice from a sample, synthesize, then delete it.
voice-cloning	Native	Same lifecycle, via raw fetch + multipart FormData.
multilingual	SDK	Non-English synthesis with simba-3.0 + the language param.
multilingual	Native	Same, via raw fetch.
output-formats	SDK	Pick codec/sample-rate/bitrate — telephony ulaw_8000, mp3, pcm.
output-formats	Native	Same, via raw fetch.
list-models	SDK	List TTS models to drive a picker.
list-models	Native	Same, via raw fetch.
list-voices	SDK	List available voices, with pagination.
list-voices	Native	Same, via raw fetch.
voice-language-model-support	SDK	Which model + language combos a voice supports.
voice-language-model-support	Native	Same, via raw fetch.
version-pinning-and-idempotency	SDK	Pin Speechify-Version; safe retries with Idempotency-Key.
version-pinning-and-idempotency	Native	Same, via raw fetch.
error-handling	SDK	Typed errors, error codes, Retry-After, request ids.
error-handling	Native	Same, via raw fetch.
watermark	Native	Detect/verify the Speechify audio watermark (REST-only).

Audio — Python

Recipe	Flavor	Description
quickstart	SDK	Synthesize speech to an MP3 file.
quickstart	Native	Same, calling the REST API directly with requests.
streaming	SDK	Stream audio to disk as it is generated.
streaming	Native	Streaming via raw requests with stream=True.
ssml-emotion	SDK	Control emotion, pitch, rate, pauses & emphasis via SSML.
ssml-emotion	Native	Same SSML controls, via raw requests.
speech-marks	SDK	Word-level timestamps → WebVTT captions.
speech-marks	Native	Same captions, via raw requests.
voice-cloning	SDK	Clone a voice from a sample, synthesize, then delete it.
voice-cloning	Native	Same lifecycle, via raw requests + multipart.
multilingual	SDK	Non-English synthesis with simba-3.0 + the language param.
multilingual	Native	Same, via raw requests.
output-formats	SDK	Pick codec/sample-rate/bitrate — telephony ulaw_8000, mp3, pcm.
output-formats	Native	Same, via raw requests.
list-models	SDK	List TTS models to drive a picker.
list-models	Native	Same, via raw requests.
list-voices	SDK	List available voices, with pagination.
list-voices	Native	Same, via raw requests.
voice-language-model-support	SDK	Which model + language combos a voice supports.
voice-language-model-support	Native	Same, via raw requests.
version-pinning-and-idempotency	SDK	Pin Speechify-Version; safe retries with Idempotency-Key.
version-pinning-and-idempotency	Native	Same, via raw requests.
error-handling	SDK	Typed errors, error codes, Retry-After, request ids.
error-handling	Native	Same, via raw requests.
watermark	Native	Detect/verify the Speechify audio watermark (REST-only).

Audio — Bash (curl)

Recipe	Flavor	Description
quickstart	Native	Synthesize speech to an MP3 file with curl + jq.
streaming	Native	Stream raw audio bytes straight to disk with curl --no-buffer.
ssml-emotion	Native	SSML emotion/prosody via a single curl call (jq builds JSON).
speech-marks	Native	Speech marks → WebVTT captions, formatted entirely in jq.
voice-cloning	Native	Multipart clone → speech → delete, with an EXIT trap cleanup.
multilingual	Native	Non-English synthesis with simba-3.0 + the language param.
output-formats	Native	Pick codec/sample-rate/bitrate — telephony ulaw_8000, mp3, pcm.
list-models	Native	List TTS models to drive a picker.
list-voices	Native	List available voices, with pagination.
voice-language-model-support	Native	Which model + language combos a voice supports.
version-pinning-and-idempotency	Native	Pin Speechify-Version; safe retries with Idempotency-Key.
error-handling	Native	Error envelope, error codes, Retry-After, request ids.
watermark	Native	Detect/verify the Speechify audio watermark.

Repository layout

recipes/audio/<language>/{sdk,native}/<recipe>/

• audio/ — Text-to-Speech today; the audio platform will expand.
• <language> — typescript, python, and bash (curl-only, native flavor).
• sdk — uses the official Speechify SDK for that language.
• native — calls the REST API directly (no SDK).

This is a pnpm workspace monorepo. TypeScript/JavaScript recipes are workspace members (shared dependency versions via the pnpm catalog:); Python recipes use uv and are managed per-recipe.

Path	What
recipes/	The recipes themselves.
templates/	Copy-to-start scaffolds for new recipes.
agents/	Modular maintenance/usage instructions, loaded on demand via AGENTS.md.
AGENTS.md	Entry point for AI agents and contributors.

Tooling

• Node 20+ and pnpm for JavaScript/TypeScript recipes.
• Python 3.10+ and uv for Python recipes.
• pnpm install at the root sets up all JS recipes.
• pnpm format formats the repo with Prettier.

Contributing

See CONTRIBUTING.md and agents/creating-a-recipe.md. New recipes start from templates/.

License

MIT