Speechdash API

Turn text into natural speech and manage listening documents from your own backend.

The Speechdash public API is a REST service at https://api.speechdash.com/v1. It uses the same voices, languages, and credit wallet as the Speechdash app. An official MCP server at https://mcp.speechdash.com/mcp exposes the same library actions as tools (streaming speech stays on REST).

This repository is the developer hub for that API: overview, multi-language examples, and links to the Help Center. Agent plugin skills (when to call each MCP tool) live in speechdash/speechdash-skills.

Useful links: Live API · Help Center · App & account · Website · Community · Examples · Plugin skills · Localized docs

What you can build

• Import text into a user's Speechdash library (create, list, update, delete documents)
• Translate a document into a new version, or export txt/csv/srt/vtt/pdf/docx
• Synthesize speech with the same voice presets as the app (F1–F5, M1–M5; JSON or streaming WAV)
• Support the same languages as in-app cloud playback
• Let users continue in the web app (edit, listen, export) after API import
• Connect ChatGPT, Cursor, or Claude Desktop through the official MCP server

Typical integrations: LMS read-aloud, accessibility layers, internal review tools, spoken previews in your product.

Quick start

1. Create a Speechdash account.
2. Open Settings → API and create an API key. Copy it once (sh_live_…).
3. Call the API with Authorization: Bearer <your-key>.

export SPEECHDASH_API_KEY="sh_live_your_key_here"

curl -sS "https://api.speechdash.com/v1/me" \
  -H "Authorization: Bearer $SPEECHDASH_API_KEY"

More examples: examples/ (Shell, Python, Ruby, PHP, JavaScript, TypeScript, Go, Java).

Authentication

Header	Value
Authorization	Bearer sh_live_…

Keys are created in the app. Only a hash is stored server-side; the full secret is shown once at creation. Revoked keys return 401.

Core endpoints

Method	Path	Purpose
GET	/health	Service health (no API key; not under /v1)
GET	/v1/openapi.json	OpenAPI 3.1 contract
GET	/v1/me	Account, plan, and wallet (auth test)
GET	/v1/documents	List documents (pagination, search, archived filter; includes finished transcripts)
POST	/v1/documents	Create a document from text (source=api)
GET	/v1/documents/{document_id}	Read document + text (visibility, share_url)
PUT	/v1/documents/{document_id}	Update title, text, language, is_archived, or visibility
DELETE	/v1/documents/{document_id}	Delete a document
POST	/v1/documents/{document_id}/translate	New translated version (same credits as MP3 export; transcript clocks copied unchanged)
GET	/v1/documents/{document_id}/export	Download pdf, docx, txt, csv, srt, or vtt
POST	/v1/audio/speech	Synthesize speech (JSON + base64 audio, speech marks; max 5,000 chars)
POST	/v1/audio/stream	Stream WAV sentence by sentence (max 20,000 chars)
POST	/v1/audio/stream/with-timestamps	SSE with per-sentence audio and marks
GET	/v1/voices	Voice catalog
GET	/v1/voices/{voice_id}	One voice

Document title is at most 512 characters; document text is at most 500,000 characters. Speech input is at most 5,000 characters on /audio/speech and 20,000 on the streaming routes.

There is no /v1/transcripts resource. Finished transcriptions appear as documents (source=transcription). The API does not start transcription jobs.

OpenAPI (machine-readable contract):
https://api.speechdash.com/v1/openapi.json

Generate a client with your favorite OpenAPI toolchain.

MCP tools

Hosted endpoint: https://mcp.speechdash.com/mcp. ChatGPT uses OAuth; Cursor and Claude Desktop send Authorization: Bearer sh_live_…. Setup: MCP server docs.

MCP tool	REST
speechdash_get_account	GET /v1/me
speechdash_list_documents	GET /v1/documents
speechdash_get_document	GET /v1/documents/{document_id}
speechdash_create_document	POST /v1/documents
speechdash_update_document	PUT /v1/documents/{document_id}
speechdash_translate_document	POST /v1/documents/{document_id}/translate
speechdash_export_document	GET /v1/documents/{document_id}/export
speechdash_delete_document	DELETE /v1/documents/{document_id}
speechdash_list_voices	GET /v1/voices
speechdash_get_voice	GET /v1/voices/{voice_id}
speechdash_synthesize_speech	POST /v1/audio/speech

Resource: speechdash://openapi. Streaming audio has no MCP tool: use REST.

Idempotency

POST /v1/documents and POST /v1/audio/speech accept an optional header:

Idempotency-Key: your-unique-key

Same key + same body within 24 hours replays the first successful response instead of running twice. Use this after network timeouts.

Streaming audio routes do not support idempotency.

Billing

All usage debits the account credit wallet (same as the app).

Action	Credits
Create document via API	0 (counts toward plan document quota)
File export	0
Speech synthesis	0.5 display credits per started 30 seconds of generated audio (wallet: 1 cent per started 30s)
Translate	Same as MP3 export: 0.5 display credits per started 30 seconds of estimated speech

Speech requests hold an estimate before generation, then settle to measured duration. The response field billed_credits is in wallet cents (2 cents = 1 display credit). Insufficient balance returns 402 payment_required before audio is generated. Translate answers 503 when translation is unavailable.

Details: What uses credits in the Help Center.

Rate limits

Limits apply per account, not per API key:

• 120 requests / minute on /v1/documents
• 60 requests / minute on /v1/audio/*
• At most 3 parallel speech syntheses per account
• 5,000 characters on POST /v1/audio/speech
• 20,000 characters on POST /v1/audio/stream and /v1/audio/stream/with-timestamps
• 500,000 characters of document text; 512 characters of title
• 10 active API keys per account

Responses include standard rate-limit headers. 429 and 503 may include Retry-After.

Useful links

Live API

Resource	URL
API base URL	https://api.speechdash.com/v1
Health check	https://api.speechdash.com/health
OpenAPI 3.1 (JSON)	https://api.speechdash.com/v1/openapi.json
MCP (Streamable HTTP)	https://mcp.speechdash.com/mcp
Examples (this repo)	github.com/speechdash/speechdash-public-api
Plugin skills	github.com/speechdash/speechdash-skills

Help Center

Resource	URL
Help Center home	docs.speechdash.com
API keys and MCP (user guide)	docs.speechdash.com/settings/api-and-mcp
API overview	docs.speechdash.com/api/api-overview
MCP server	docs.speechdash.com/api/mcp-server
Reference: account	docs.speechdash.com/api/account
Reference: documents	docs.speechdash.com/api/documents
Reference: audio	docs.speechdash.com/api/audio
Reference: voices	docs.speechdash.com/api/voices
What uses credits	docs.speechdash.com/billing/what-uses-credits
Credit wallet (feature)	docs.speechdash.com/features/credit-wallet
Supported languages	docs.speechdash.com/import/supported-languages

The interactive reference on docs sends try-it-out requests through a proxy to the live API (use a test key with care).

Speechdash app

Resource	URL
Web app (home, library, listening)	speechdash.com
Sign up	speechdash.com/register
Log in	speechdash.com/login
Create & manage API keys	speechdash.com/settings/api
Billing & plans	speechdash.com/settings/billing
Credit usage history	speechdash.com/settings/credit-usage
Referral program	speechdash.com/settings/referrals
Agents & MCP	speechdash.com/agents

Website

Resource	URL
Marketing site	speechdash.com
Pricing	speechdash.com/pricing
Public API feature page	speechdash.com/features/public-api
Blog: API is live	speechdash.com/blog/public-api-live
Product features hub	speechdash.com/features
Brand assets	speechdash.com/media

Community & support

Resource	URL
Discord	discord.gg/knR7Xr94Mp
LinkedIn	linkedin.com/company/speechdash

When you contact support, include the X-Request-ID header from the API response.

API overview in other languages

Help Center articles are available in 25 locales. English uses no URL prefix; other locales use /{locale}/.

Locale	API overview	API keys and MCP
English	docs.speechdash.com/api/api-overview	settings/api-and-mcp
Français	docs.speechdash.com/fr/api/api-overview	fr/settings/api-and-mcp
Español	docs.speechdash.com/es/api/api-overview	es/settings/api-and-mcp
Deutsch	docs.speechdash.com/de/api/api-overview	de/settings/api-and-mcp
Italiano	docs.speechdash.com/it/api/api-overview	it/settings/api-and-mcp
Português	docs.speechdash.com/pt/api/api-overview	pt/settings/api-and-mcp
Nederlands	docs.speechdash.com/nl/api/api-overview	nl/settings/api-and-mcp
Polski	docs.speechdash.com/pl/api/api-overview	pl/settings/api-and-mcp
Svenska	docs.speechdash.com/sv/api/api-overview	sv/settings/api-and-mcp
Dansk	docs.speechdash.com/da/api/api-overview	da/settings/api-and-mcp
Norsk	docs.speechdash.com/no/api/api-overview	no/settings/api-and-mcp
Suomi	docs.speechdash.com/fi/api/api-overview	fi/settings/api-and-mcp
Čeština	docs.speechdash.com/cs/api/api-overview	cs/settings/api-and-mcp
Magyar	docs.speechdash.com/hu/api/api-overview	hu/settings/api-and-mcp
Tiếng Việt	docs.speechdash.com/vi/api/api-overview	vi/settings/api-and-mcp
Türkçe	docs.speechdash.com/tr/api/api-overview	tr/settings/api-and-mcp
Ελληνικά	docs.speechdash.com/el/api/api-overview	el/settings/api-and-mcp
Русский	docs.speechdash.com/ru/api/api-overview	ru/settings/api-and-mcp
Українська	docs.speechdash.com/uk/api/api-overview	uk/settings/api-and-mcp
עברית	docs.speechdash.com/he/api/api-overview	he/settings/api-and-mcp
العربية	docs.speechdash.com/ar/api/api-overview	ar/settings/api-and-mcp
한국어	docs.speechdash.com/ko/api/api-overview	ko/settings/api-and-mcp
日本語	docs.speechdash.com/ja/api/api-overview	ja/settings/api-and-mcp
简体中文	docs.speechdash.com/zh/api/api-overview	zh/settings/api-and-mcp
繁體中文	docs.speechdash.com/zh-TW/api/api-overview	zh-TW/settings/api-and-mcp

License

Documentation and examples in this repository are provided under Apache-2.0 unless noted otherwise.