API overview

The Speechdash API lets your own application create documents and generate speech with the same voices as the app. Everything you create through the API also shows up in your library. Finished audio and video transcripts created in the app appear as library documents too (source is transcription, with a transcript_id). There is no /transcripts REST resource: use the document endpoints. The API does not start transcription jobs.

Base URL:

https://api.speechdash.com/v1

Health check (no API key): GET https://api.speechdash.com/health

The machine-readable contract is published at https://api.speechdash.com/v1/openapi.json, so you can generate a client for your language.

Endpoints

Interactive OpenAPI pages: Account, Documents, Audio, Voices.

MCP server (for AI assistants)

If you use Cursor, Claude Desktop, or another MCP client, you can add the official Speechdash MCP server instead of calling HTTP yourself. It exposes the same library (including finished transcripts), translate, export, voices, account snapshot, and non-streaming speech synthesis as tools backed by the same API keys and billing as this guide. Streaming speech stays on REST.

See MCP server for the full tool list and setup (stdio or Streamable HTTP). You can also read the Agents hub on the marketing site for machine-readable docs aimed at AI systems. End users can start from API keys and MCP in this Help Center.

Create an API key

You can keep up to 10 active keys, rename them at any time, and see when each one was last used. Revoking a key stops its requests immediately.

Authenticate a request

Send the key as a bearer token:

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

Requests without a valid key answer 401 with the code unauthorized.

GET /me returns your account id, email, plan, and wallet balance (wallet_cents and display_credits), plus metadata about the API key used. Use it to verify a key after setup (for example in Zapier).

POST /documents and POST /audio/speech accept an optional Idempotency-Key header. Retrying the same key with the same body replays the first successful response for 24 hours, so a network blip does not create a second document or bill speech twice. If a speech response is too large to store, a retry with the same key answers 409 instead of regenerating (the original request was already billed). A client disconnect on /audio/speech answers 204, settles any audio already produced, and releases the key so a retry can regenerate. Streaming audio endpoints reject the header.

Credits

Speech synthesis spends credits from the same wallet as the app: 0.5 credits (1 wallet cent) per started 30 seconds of generated audio. Each request holds an estimate (plus a small margin) before generation starts, then settles to the audio that was actually produced. Unused hold is refunded; each settled request appears in Settings → Credit usage as API speech synthesis. The billed_credits field in API responses is wallet cents (2 cents = 1 display credit). If a stream is interrupted mid-way, the sentences already delivered are still billed.

If your balance cannot cover the hold, the API answers 402 with the code payment_required before generating anything.

Creating documents does not spend credits, but it counts toward your plan's daily document cap (Free: 3 per day; Unlimited: no daily cap) and upload duration limits. File export does not spend credits.

Billing vs in-app Cloud playback

In-app Cloud replay reuses per-document sentence cache: replaying a sentence that was already generated on the server may cost 0 display credits. REST and MCP speech endpoints always synthesize fresh audio and bill per started 30 seconds at the same rate when generation occurs. There is no replay cache on API or MCP synthesis.

Limits

Rate limits are counted per account, not per key, so extra keys do not raise your quota. Every response carries X-Request-ID, and /documents plus /audio/* also return X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Quote X-Request-ID when you contact support.

Speech requests also have a parallelism cap: a fourth simultaneous request answers 429 while three are still running, so one integration cannot monopolize synthesis. Retry 429 and 503 after the Retry-After header.

For content longer than the speech limits, create a document with POST /v1/documents and export its audio from the app.

Documents: share, translate, export

Serialized documents include visibility and share_url (null when private). PUT /v1/documents/{id} accepts visibility to publish an unlisted read-only page at /share/document/{id}, and is_archived to archive or restore. Shared pages are text-only. They do not play billed audio.

POST /v1/documents/{id}/translate creates a new translated version. It bills the same credit wallet as MP3 export (0.5 display credits / 1 wallet cent per started 30 seconds of estimated speech) and answers 402 when the wallet is short. It answers 503 when translation is not configured or down. Transcript clocks (**0:34**, **SPEAKER_00** · 0:34, (0:34)) are playback references: they are copied unchanged and are not sent through the translation engine.

GET /v1/documents/{id}/export?format=pdf|docx|txt|csv|srt|vtt downloads the current version as an attachment. Add timestamps=1 to include section times on PDF, DOCX, TXT, and CSV. SRT and VTT need a transcription or complete sentence timings. Stored text on GET /v1/documents/{id} keeps transcript timestamp headers. Hiding them is an app reader toggle only.

Related