API Reference

Endpoints for text-to-speech, speech retrieval, speech-to-text (sync and async), subtitles (SRT and WebVTT), and account management.

Authentication

Most endpoints expect your Speech7 API key. Send it as apiKey in the request body or use the x-api-key header (or ?apiKey=... query) for fetch requests that do not accept JSON bodies.

Admin endpoints require an admin login in the web UI or an admin API key (set isAdmin=true when creating the account).

Capabilities depend on provider keys saved on the account. Use GET https://app.speech7.com/account/capabilities with your API key to check TTS/STT availability, remaining minutes, and a breakdown of minutes used by type (minutesUsed.tts, minutesUsed.stt, minutesUsed.total).

POST /tts

Generate speech from text. Streams an MP3 response. Requires a TTS provider key saved on the account. 

POST https://app.speech7.com/tts
Content-Type: application/json
{
  "apiKey": "your_api_key",
  "text": "Hello from Speech7"
}

Limits: min 500 chars / 20 words, max 500 words.

Add "json": true to return JSON metadata instead of streaming audio (fields: audioPath and id).

Quick test: curl -o out.mp3 -X POST https://app.speech7.com/tts -H "Content-Type: application/json" -d '{"apiKey":"YOUR_KEY","text":"Hello world from the API."}'

GET /speeches

List recent speeches for your API key (newest first).

GET https://app.speech7.com/speeches?limit=50
Headers: x-api-key: your_api_key

Returns speeches array with id, timestamps, usage stats, and audioPath. Use the IDs with GET /speeches/:speechId.

Supports cursor-based pagination. Pass ?cursor=<id> (the id of the last item you received) to fetch the next page. The response includes a nextCursor field — null when there are no more results. 

# First page
GET /speeches?limit=20

# Next page (use nextCursor from previous response)
GET /speeches?limit=20&cursor=file001-1710000000000

Quick test: curl -H "x-api-key: YOUR_KEY" https://app.speech7.com/speeches

GET /speeches/:speechId

Fetch details for a specific speech. Add ?download=1 to stream the stored MP3. 

GET https://app.speech7.com/speeches/file001-123456?apiKey=your_api_key

Quick test: use an ID from /speeches then curl -L "https://app.speech7.com/speeches/ID?download=1&apiKey=YOUR_KEY" -o speech.mp3

POST /stt

Transcribe audio or video to text using the configured speech-to-text provider. Requires an STT provider key saved on the account. STT usage consumes minutes from the same pool as TTS (quantized to 0.5-minute increments). Responses include text, speakers, and transcript entries.

Speaker diarization is disabled by default; enable it by sending enableSpeakerDiarization=true. You can also override speaker labels by passing speaker1Label, speaker2Label, speaker3Label, etc. in the form data (e.g., speaker1Label=John). These labels are used in both the diarized text and the speakers array in the response.

Custom dictionaries are supported via transcriptionTerms/customDictionary (merged into context.terms) and translationTerms/translationDictionary (merged into context.translation_terms). Provide JSON or delimited text.

Also accepted for transcription dictionaries: terms and customTerms. If you already send context, dictionary fields are merged into it, not replaced.

Max upload size: 200 MB by default. Exceeding this returns HTTP 413 File too large. Supported types: audio/*, video/*.

Add json=true to get the structured transcript array: [{ transcript, text, durationMs }]. 

curl -X POST https://app.speech7.com/stt \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@sample.wav" \
  -F "transcriptionTerms=[\"Speech7\",\"Soniox\"]" \
  -F "translationTerms={\"račun\":\"invoice\"}"

Quick test (text only): curl -X POST https://app.speech7.com/stt -F "audio=@sample.mp3" | jq .text

POST /subtitle

Generate subtitles for an audio or video file. Uses the same STT provider as /stt and charges minutes from your pool.

Upload the media as audio (multipart/form-data). You can optionally include languageHints and speaker labels (speaker1Label, speaker2Label, …). The response is a subtitle file download.

Set format=vtt to receive a WebVTT file (text/vtt) instead of the default SRT (application/x-subrip). WebVTT is the native browser format for HTML5 <track> elements.

Subtitle endpoints accept the same dictionary fields as /stt (transcriptionTerms, translationTerms, etc.) and pass them to the STT provider context.

Optional formatting: maxCharsPerLine (default 70, min 30, max 120) and maxLines (default 2, min 1, max 4) to control line wrapping.

Max upload size: 25 MB. Supported: audio/*, video/*. 

# SRT (default)
curl -X POST https://app.speech7.com/subtitle \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@sample.mp4" \
  -o subtitles.srt

# WebVTT
curl -X POST https://app.speech7.com/subtitle \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@sample.mp4" \
  -F "format=vtt" \
  -o subtitles.vtt

Async subtitles (large files)

For long uploads or when your client may time out, start a job and fetch the subtitle file later. Jobs are kept for 24 hours. 

# 1) Start a job (multipart upload)
curl -X POST https://app.speech7.com/subtitle/jobs \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@movie.mp4"

# Response: {"id":"sub_ab12...","status":"queued","statusUrl":"/subtitle/jobs/sub_ab12..."}

# 2) Poll status (repeat until status=completed)
curl -H "x-api-key: YOUR_API_KEY" \
  https://app.speech7.com/subtitle/jobs/sub_ab12...

# 3) Download when ready
curl -L -H "x-api-key: YOUR_API_KEY" \
  https://app.speech7.com/subtitle/jobs/sub_ab12.../file \
  -o subtitles.srt

Set format=vtt in the job request to receive WebVTT instead of SRT. The /file download endpoint serves the correct Content-Type automatically.

Pass callbackUrl (or callback_url) to receive a webhook POST when the job finishes (or fails). The payload is the same JSON as the status endpoint. Only http:// and https:// URLs are accepted.

Status responses include minutesUsed, durationMs, and a downloadUrl when ready.

GET /subtitle/jobs

List all subtitle jobs for your API key (newest first).

GET https://app.speech7.com/subtitle/jobs?limit=20
Headers: x-api-key: your_api_key

# Next page
GET /subtitle/jobs?limit=20&cursor=sub_ab12...

Returns { jobs, total, nextCursor }. Pass the nextCursor value as ?cursor= to fetch the next page; null means no more results.

Async STT jobs

Same job-based pattern as async subtitles, but returns the raw transcript instead of a subtitle file. Useful for large uploads or when you cannot wait for a synchronous response. 

# 1) Start a job
curl -X POST https://app.speech7.com/stt/jobs \
  -H "x-api-key: YOUR_API_KEY" \
  -F "audio=@recording.mp3"

# Response (202): {"id":"sttjob_ab12...","status":"queued","statusUrl":"/stt/jobs/sttjob_ab12..."}

# 2) Poll until status=completed (returns 202 while in progress, 200 when done)
curl -H "x-api-key: YOUR_API_KEY" \
  https://app.speech7.com/stt/jobs/sttjob_ab12...

# Completed response:
{
  "id": "sttjob_ab12...",
  "status": "completed",
  "result": { "transcript": [...], "text": "...", "durationMs": 12340 },
  "minutesUsed": 0.5,
  "durationMs": 12340
}

Accepts the same body fields as POST /stt (transcription dictionaries, language hints, speaker labels, etc.) as additional form fields.

Pass callbackUrl (or callback_url) to receive a webhook POST when the job finishes or fails. Only http:// and https:// URLs are accepted.

GET /stt/jobs

List all STT jobs for your API key (newest first).

GET https://app.speech7.com/stt/jobs?limit=20
Headers: x-api-key: your_api_key

# Next page
GET /stt/jobs?limit=20&cursor=sttjob_ab12...

Returns { jobs, total, nextCursor }. Max limit is 200, default 100. Jobs expire after 24 hours.