API Reference
Complete reference for the Scriptivox transcription API. All endpoints require an API key, passed in one of:
Authorization: sk_live_…(theBearerprefix is accepted but not required)X-Api-Key: sk_live_…
Header names are case-insensitive. Each account can have at most 5 active API keys at a time. Revoke an unused key in the dashboard before creating a new one if you hit this ceiling.
Base URL: https://api.scriptivox.com/v1
Service status: real-time uptime + incident history at status.scriptivox.com.
Transcribe
Send audio for transcription. You can either pass a URL (we download it) or upload your own file.
From a URL
The simplest path: one POST request. We download the file, validate it, and start transcription automatically. Supports Google Drive, Dropbox and OneDrive sharing links, and public TikTok, Instagram, Facebook, X and Snapchat posts.
/v1/transcribeStart a transcription from a public URL. The file is downloaded and validated in the background. Poll GET /v1/transcribe/{id} for status updates. Duration and cost are determined after download.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Required | Anonymously accessible http or https URL. An anonymous GET must return the raw file bytes, not an HTML preview, login form or password page. Direct and presigned URLs (S3, GCS, Azure SAS) always work. Share links work only when set to "anyone with the link can view": Google Drive, Dropbox files (not /scl/fo/ folder links), and OneDrive personal /redir or onedrive.live.com links. OneDrive 1drv.ms/v/c/ and /p/c/ photo shares cannot be used — Microsoft routes them through SharePoint Photos, which requires sign-in. A public post on TikTok, Instagram, Facebook, X and Snapchat also works: send the post's own link (a video or a reel). It is checked when you send it, and a post that is private, deleted or has no video is refused at once with 400 URL_NOT_ACCESSIBLE (see `error.reason`), with nothing created or charged. Maximum 2048 characters. |
| language | string | Optional | ISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST. |
| diarize | boolean | Optional | Identify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment. Default: false. |
| speaker_count | integer | Optional | Expected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation. Range: 1–50. |
| align | boolean | Optional | Produce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true. Default: true. |
| webhook_url | string | Optional | URL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks. |
| speech_threshold | number | Optional | The share of the audio, from 0 to 1, that must be speech. Below it the job fails with SPEECH_BELOW_THRESHOLD and is not charged. Without it, a file with no speech (silence, music or noise only) completes with an empty transcript and `result.no_speech: true`, and is charged on its length. The share is measured reliably from about 30 seconds of audio. 0 is the same as not setting it. Range: 0–1. |
urlstringRequiredAnonymously accessible http or https URL. An anonymous GET must return the raw file bytes, not an HTML preview, login form or password page. Direct and presigned URLs (S3, GCS, Azure SAS) always work. Share links work only when set to "anyone with the link can view": Google Drive, Dropbox files (not /scl/fo/ folder links), and OneDrive personal /redir or onedrive.live.com links. OneDrive 1drv.ms/v/c/ and /p/c/ photo shares cannot be used — Microsoft routes them through SharePoint Photos, which requires sign-in. A public post on TikTok, Instagram, Facebook, X and Snapchat also works: send the post's own link (a video or a reel). It is checked when you send it, and a post that is private, deleted or has no video is refused at once with 400 URL_NOT_ACCESSIBLE (see `error.reason`), with nothing created or charged. Maximum 2048 characters.
languagestringOptionalISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST.
diarizebooleanOptionalIdentify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment. Default: false.
speaker_countintegerOptionalExpected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation. Range: 1–50.
alignbooleanOptionalProduce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true. Default: true.
webhook_urlstringOptionalURL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks.
speech_thresholdnumberOptionalThe share of the audio, from 0 to 1, that must be speech. Below it the job fails with SPEECH_BELOW_THRESHOLD and is not charged. Without it, a file with no speech (silence, music or noise only) completes with an empty transcript and `result.no_speech: true`, and is charged on its length. The share is measured reliably from about 30 seconds of audio. 0 is the same as not setting it. Range: 0–1.
Response
{"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "created","message": "Transcription created. The file will be downloaded and processed. Poll GET /v1/transcribe/{id} for status updates."}
Code Examples
resp = requests.post("https://api.scriptivox.com/v1/transcribe",headers={"Authorization": "sk_live_YOUR_KEY"},json={"url": "https://example.com/podcast-episode.mp3","diarize": True,"language": "en"})job = resp.json()# Poll for statusimport timewhile True:result = requests.get(f"https://api.scriptivox.com/v1/transcribe/{job['id']}",headers={"Authorization": "sk_live_YOUR_KEY"}).json()if result["status"] in ("completed", "failed"):breaktime.sleep(5)
Social posts
Send the post's own link (a video or a reel) from TikTok, Instagram, Facebook, X or Snapchat. The post is checked when you send it, the same check the Scriptivox website runs, so this call takes a few seconds. A good post is answered 200 with status: "created" like any other link, and its video is downloaded in the background.
A post that can't be transcribed is refused at once: nothing is created or charged, error.reason says why and error.platform names the site. Sending the same link again gives the same answer.
HTTP/1.1 400 Bad Request{"error": {"code": "URL_NOT_ACCESSIBLE","message": "This link could not be checked. It may be private, deleted or not available in your region.","reason": "link_not_verifiable","platform": "instagram","request_id": "req_6fe725fffa7d9b98","docs_url": "https://platform.scriptivox.com/docs/api-reference#error-codes"}}
error.reason | Meaning |
|---|---|
link_not_verifiable | The post is private, deleted or not available in your region. |
link_not_found | The video can't be opened. Check that it plays in a browser. |
link_unsupported | The link is not a video, for example a Facebook Page or a profile. Open the video itself and send its own link. |
link_no_media | The post has no audio or video, for example a photo post. |
If the link check is busy or does not answer, the answer is 503 LINK_CHECK_UNAVAILABLE with a Retry-After header: send the same request again after that many seconds. All the codes are in error codes.
From a file upload
Upload your own file when you need full control or don't have a public URL.
/v1/uploadGet a presigned URL to upload an audio or video file. The URL expires in 1 hour. Upload your file to the returned URL with a PUT request, then pass the upload_id to POST /v1/transcribe.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| filename | string | Required | Name of the file being uploaded, e.g. "meeting.mp3". ASCII only, no path separators, and it must carry a supported extension. Maximum 255 characters. |
filenamestringRequiredName of the file being uploaded, e.g. "meeting.mp3". ASCII only, no path separators, and it must carry a supported extension. Maximum 255 characters.
Response
{"upload_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890","upload_url": "https://uploads.example/presigned-url","expires_in": 3600,"method": "PUT","headers": {"Content-Type": "audio/mpeg"}}
Code Examples
import requestsresp = requests.post("https://api.scriptivox.com/v1/upload",headers={"Authorization": "sk_live_YOUR_KEY"},json={"filename": "meeting.mp3"})upload = resp.json()with open("meeting.mp3", "rb") as f:requests.put(upload["upload_url"],headers=upload["headers"], data=f)
/v1/transcribeStart a transcription from an uploaded file. Pass the upload_id from POST /v1/upload. The file is validated in the background. Poll GET /v1/transcribe/{id} for status updates. Duration and cost are determined after validation.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| upload_id | string | Required | The upload_id returned by POST /v1/upload. |
| language | string | Optional | ISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST. |
| diarize | boolean | Optional | Identify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment. Default: false. |
| speaker_count | integer | Optional | Expected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation. Range: 1–50. |
| align | boolean | Optional | Produce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true. Default: true. |
| webhook_url | string | Optional | URL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks. |
| speech_threshold | number | Optional | The share of the audio, from 0 to 1, that must be speech. Below it the job fails with SPEECH_BELOW_THRESHOLD and is not charged. Without it, a file with no speech (silence, music or noise only) completes with an empty transcript and `result.no_speech: true`, and is charged on its length. The share is measured reliably from about 30 seconds of audio. 0 is the same as not setting it. Range: 0–1. |
upload_idstringRequiredThe upload_id returned by POST /v1/upload.
languagestringOptionalISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST.
diarizebooleanOptionalIdentify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment. Default: false.
speaker_countintegerOptionalExpected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation. Range: 1–50.
alignbooleanOptionalProduce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true. Default: true.
webhook_urlstringOptionalURL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks.
speech_thresholdnumberOptionalThe share of the audio, from 0 to 1, that must be speech. Below it the job fails with SPEECH_BELOW_THRESHOLD and is not charged. Without it, a file with no speech (silence, music or noise only) completes with an empty transcript and `result.no_speech: true`, and is charged on its length. The share is measured reliably from about 30 seconds of audio. 0 is the same as not setting it. Range: 0–1.
Response
{"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "created","message": "Transcription created. The file will be validated and processed. Poll GET /v1/transcribe/{id} for status updates."}
Code Examples
resp = requests.post("https://api.scriptivox.com/v1/transcribe",headers={"Authorization": "sk_live_YOUR_KEY"},json={"upload_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890","diarize": True,"speaker_count": 2,"language": "en"})job = resp.json()# Poll for statusimport timewhile True:result = requests.get(f"https://api.scriptivox.com/v1/transcribe/{job['id']}",headers={"Authorization": "sk_live_YOUR_KEY"}).json()if result["status"] in ("completed", "failed"):breaktime.sleep(5)
Again, from an earlier job
Transcribe a finished job again with other options, such as another language or speaker labels, from the audio Scriptivox still holds: no upload and no download. A job's audio is kept for 24 hours after the job ends. Within that time, pass the job's id as source_transcription_id. The new job is a new transcription, charged like any other, and the earlier job and its transcript stay as they are.
/v1/transcribeStart a transcription from the audio of an earlier completed job of yours. Pass its id as source_transcription_id, with this request's own options. Poll GET /v1/transcribe/{id} for status updates. Duration and cost are determined after validation.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| source_transcription_id | string | Required | The id of a completed transcription of yours that ended less than 24 hours ago. A job not completed: 400 INVALID_REQUEST with `error.current_status`; not yours or deleted: 404 TRANSCRIPTION_NOT_FOUND; its audio deleted: 409 SOURCE_EXPIRED. |
| language | string | Optional | ISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST. |
| diarize | boolean | Optional | Identify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment. Default: false. |
| speaker_count | integer | Optional | Expected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation. Range: 1–50. |
| align | boolean | Optional | Produce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true. Default: true. |
| webhook_url | string | Optional | URL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks. |
| speech_threshold | number | Optional | The share of the audio, from 0 to 1, that must be speech. Below it the job fails with SPEECH_BELOW_THRESHOLD and is not charged. Without it, a file with no speech (silence, music or noise only) completes with an empty transcript and `result.no_speech: true`, and is charged on its length. The share is measured reliably from about 30 seconds of audio. 0 is the same as not setting it. Range: 0–1. |
source_transcription_idstringRequiredThe id of a completed transcription of yours that ended less than 24 hours ago. A job not completed: 400 INVALID_REQUEST with `error.current_status`; not yours or deleted: 404 TRANSCRIPTION_NOT_FOUND; its audio deleted: 409 SOURCE_EXPIRED.
languagestringOptionalISO 639-1 language code (with BCP-47 fallbacks such as `yue` and `kea`), e.g. "en", "es", "fr". Omit or pass null for auto-detection. Passing the language explicitly is recommended: it is faster (the model skips its detection pass) and avoids known auto-detect failure modes on short clips, code-switched audio, and files that open with music. Forcing a language the audio is not in can produce a translation rather than a transcription. Invalid codes return 400 INVALID_REQUEST.
diarizebooleanOptionalIdentify who said what and attach a speaker label to every utterance. Implies align: true, because speaker assignment needs word-level alignment. Default: false.
speaker_countintegerOptionalExpected number of speakers. Requires diarize: true; passing it without diarize returns 400 INVALID_REQUEST. This is a soft prior, not a hard ceiling — the result may contain slightly more or fewer labels. Strongly recommended whenever the count is known: it measurably reduces over- and under-segmentation. Range: 1–50.
alignbooleanOptionalProduce word-level start/end timestamps plus per-word confidence where the alignment model supports it. Confidence is language-dependent and may be null. Ignored (treated as true) when diarize is true. Default: true.
webhook_urlstringOptionalURL to receive the job's webhooks (processing, then completed or failed). Must be https://. Signed with the key's webhook signing secret and retried with backoff until your server answers 2xx — see https://platform.scriptivox.com/docs/webhooks.
speech_thresholdnumberOptionalThe share of the audio, from 0 to 1, that must be speech. Below it the job fails with SPEECH_BELOW_THRESHOLD and is not charged. Without it, a file with no speech (silence, music or noise only) completes with an empty transcript and `result.no_speech: true`, and is charged on its length. The share is measured reliably from about 30 seconds of audio. 0 is the same as not setting it. Range: 0–1.
Response
{"id": "c3d4e5f6-a7b8-9012-cdef-123456789012","status": "created","message": "Transcription created from the audio of transcription b2c3d4e5-f6a7-8901-bcde-f12345678901. It will be validated and processed. Poll GET /v1/transcribe/{id} for status updates."}
Code Examples
# The same recording again, in Spanish with speaker labels: no upload, no download.resp = requests.post("https://api.scriptivox.com/v1/transcribe",headers={"Authorization": "sk_live_YOUR_KEY"},json={"source_transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","language": "es","diarize": True})job = resp.json()if resp.status_code == 409 and job["error"]["code"] == "SOURCE_EXPIRED":pass # the audio is gone: send the file again with upload_id or url
- The options are this request's own. Nothing is copied from the earlier job: leave out
languageand the language is detected again. - After 24 hours the answer is
409 SOURCE_EXPIREDand nothing is created or charged: send the file again withupload_idorurl. - Only a
completedjob. A job in another status answers400 INVALID_REQUESTwitherror.current_status; an id that is not one of yours answers404 TRANSCRIPTION_NOT_FOUND. Idempotency-Keyworks as on any start: the same key and body give the same job.
Get result
/v1/transcribe/{id}Get the status and result of a transcription. Poll this endpoint until status is completed or failed, or use webhooks for real-time notifications. Pass ?format=srt|vtt|text to export the transcript directly as captions or plain text instead of JSON.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transcription ID returned by POST /v1/transcribe. |
| format | string | Optional | Output format. `json` (default) returns the full structured response and works at any status. `srt`, `vtt` and `text` return the transcript directly with the matching Content-Type and require status=completed; otherwise they return 400 INVALID_REQUEST with the job's status in `error.current_status`. |
| max_words | integer | Optional | Caption segmentation: maximum words per cue. Only applies to format=srt|vtt (format=text is built from whole utterances and ignores the segmentation options). Whichever of max_words, max_chars and max_duration is exceeded first ends the cue. Range: 1–50. Default: 4. |
| max_chars | integer | Optional | Caption segmentation: maximum characters per cue. The subtitle convention is about 80 (roughly 37 characters across two lines). Range: 10–500. Default: 80. |
| max_duration | integer | Optional | Caption segmentation: maximum seconds a single cue stays on screen. Range: 1–60. Default: 10. |
| sentence_aware | boolean | Optional | Caption segmentation: end a cue at sentence-ending punctuation (. ! ?). Produces more natural breaks at the cost of more variable cue lengths. Default: true. |
| include_speakers | string | Optional | Whether cues are prefixed with the speaker label. `auto` includes labels only when the job has more than one distinct speaker. Only meaningful for jobs created with diarize: true. One of: "true", "false", "auto". Default: auto. |
| strip_chars | string | Optional | Characters to remove from cue text before output, e.g. `strip_chars=,.` drops all commas and periods. Maximum 32 characters. |
| include_timestamps | boolean | Optional | format=text only: return one paragraph per utterance, each starting with its start time, e.g. `[02:14] Speaker 1: …` (`[01:02:14]` once the transcript reaches an hour). srt and vtt always include timestamps; json carries them as fields. Default: false. |
idstringRequiredTranscription ID returned by POST /v1/transcribe.
formatstringOptionalOutput format. `json` (default) returns the full structured response and works at any status. `srt`, `vtt` and `text` return the transcript directly with the matching Content-Type and require status=completed; otherwise they return 400 INVALID_REQUEST with the job's status in `error.current_status`.
max_wordsintegerOptionalCaption segmentation: maximum words per cue. Only applies to format=srt|vtt (format=text is built from whole utterances and ignores the segmentation options). Whichever of max_words, max_chars and max_duration is exceeded first ends the cue. Range: 1–50. Default: 4.
max_charsintegerOptionalCaption segmentation: maximum characters per cue. The subtitle convention is about 80 (roughly 37 characters across two lines). Range: 10–500. Default: 80.
max_durationintegerOptionalCaption segmentation: maximum seconds a single cue stays on screen. Range: 1–60. Default: 10.
sentence_awarebooleanOptionalCaption segmentation: end a cue at sentence-ending punctuation (. ! ?). Produces more natural breaks at the cost of more variable cue lengths. Default: true.
include_speakersstringOptionalWhether cues are prefixed with the speaker label. `auto` includes labels only when the job has more than one distinct speaker. Only meaningful for jobs created with diarize: true. One of: "true", "false", "auto". Default: auto.
strip_charsstringOptionalCharacters to remove from cue text before output, e.g. `strip_chars=,.` drops all commas and periods. Maximum 32 characters.
include_timestampsbooleanOptionalformat=text only: return one paragraph per utterance, each starting with its start time, e.g. `[02:14] Speaker 1: …` (`[01:02:14]` once the transcript reaches an hour). srt and vtt always include timestamps; json carries them as fields. Default: false.
Response
{"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "completed","audio_duration_seconds": 120,"file_size_bytes": 1920000,"language": "en","diarize": true,"speaker_count": 2,"align": true,"cost_cents": 0.666667,"source_url": "https://example.com/podcast.mp3","progress": "Transcription completed successfully.","created_at": "2025-01-15T10:30:00Z","started_at": "2025-01-15T10:30:01Z","completed_at": "2025-01-15T10:30:45Z","result": {"full_transcript": "Hello, thanks for joining...","language": "en","duration_seconds": 120,"speakers": ["SPEAKER 1", "SPEAKER 2"],"utterances": [{"start": 0.5,"end": 3.2,"text": "Hello, thanks for joining the call today.","speaker": "SPEAKER 1","confidence": 0.95,"words": [{"word": "Hello,","start": 0.5,"end": 0.9,"confidence": 0.98,"speaker": "SPEAKER 1"}]}]}}
Code Examples
resp = requests.get(f"https://api.scriptivox.com/v1/transcribe/{job['id']}",headers={"Authorization": "sk_live_YOUR_KEY"})result = resp.json()if result["status"] == "completed":print(result["result"]["full_transcript"])
Status values
The status lifecycle is created → downloading (URL flow only) → processing → completed | failed.
| Status | Description |
|---|---|
created | Job accepted. Download (URL flow) or validation (upload flow) is about to start. |
downloading | URL flow only: the file is being fetched from the provided URL. |
processing | The file has been validated and is being transcribed. |
completed | Transcription finished successfully. The result object is now populated. |
failed | The job failed. Inspect error.code and error.message. |
When the service is busy, a job can stay created for a few minutes before it starts. It starts by itself: keep polling (or wait for the webhook), and do not send it again.
Caption / text export
GET /v1/transcribe/{id}?format=srt|vtt|text returns the transcript in the requested format with the appropriate Content-Type:
format | Content-Type | Body |
|---|---|---|
json (default) | application/json | Full structured response with result.utterances[] |
srt | text/plain; charset=utf-8 | SubRip Text |
vtt | text/vtt; charset=utf-8 | WebVTT, with <v Speaker> voice tags when speaker labels are shown |
text | text/plain; charset=utf-8 | Plain text. Diarized jobs get a Speaker: prefix per turn with blank lines between turns. |
srt, vtt, and text require status=completed; otherwise returns 400 INVALID_REQUEST, with the job's status in error.current_status (for example processing or failed). JSON format works at any status.
Segmentation controls
The caption formats (srt and vtt) accept the same segmentation knobs as the dashboard's Advanced Export modal. Pass them as query params alongside format. format=text is built from whole utterances: it uses include_speakers, strip_chars and include_timestamps, and ignores the four segmentation knobs.
| Param | Default | Range | Effect |
|---|---|---|---|
max_words | 4 | 1–50 | Maximum words per cue. Only applies to format=srt/vtt (format=text is built from whole utterances and ignores the segmentation options). Whichever of max_words, max_chars and max_duration is exceeded first ends the cue. |
max_chars | 80 | 10–500 | Maximum characters per cue. The subtitle convention is about 80 (roughly 37 characters across two lines). |
max_duration | 10 | 1–60 | Maximum seconds a single cue stays on screen. |
sentence_aware | true | true / false | End a cue at sentence-ending punctuation (. ! ?). Produces more natural breaks at the cost of more variable cue lengths. |
include_speakers | auto | true / false / auto | Whether cues are prefixed with the speaker label. auto includes labels only when the job has more than one distinct speaker. Only meaningful for jobs created with diarize: true. |
strip_chars | (empty) | up to 32 chars | Characters to remove from cue text before output, e.g. strip_chars=,. drops all commas and periods. |
include_timestamps | false | true / false | format=text only: return one paragraph per utterance, each starting with its start time, e.g. [02:14] Speaker 1: … ([01:02:14] once the transcript reaches an hour). srt and vtt always include timestamps; json carries them as fields. |
Whichever of max_words, max_chars, max_duration is exceeded first ends the current cue. sentence_aware adds a sentence-ending punctuation rule on top of those.
Examples:
# Short cues (TikTok-style, max 3 words, 2.5s each, no sentence-awareness)curl "https://api.scriptivox.com/v1/transcribe/{id}?format=srt&max_words=3&max_duration=3&sentence_aware=false" \-H "Authorization: sk_live_YOUR_KEY"# Standard SRT with default settingscurl "https://api.scriptivox.com/v1/transcribe/{id}?format=srt" \-H "Authorization: sk_live_YOUR_KEY"# WebVTT, always show speaker tags, strip filler punctuationcurl "https://api.scriptivox.com/v1/transcribe/{id}?format=vtt&include_speakers=true&strip_chars=,." \-H "Authorization: sk_live_YOUR_KEY"# Plain text without speaker prefixescurl "https://api.scriptivox.com/v1/transcribe/{id}?format=text&include_speakers=false" \-H "Authorization: sk_live_YOUR_KEY"# Plain text with a timestamp at the start of every paragraphcurl "https://api.scriptivox.com/v1/transcribe/{id}?format=text&include_timestamps=true" \-H "Authorization: sk_live_YOUR_KEY"
When the job was made with align: false (no per-word timestamps), the segmentation falls back to utterance-level: max_words/max_chars/max_duration still cap each cue but cuts can only happen at utterance boundaries. For best segmentation control, keep align on (the default).
List transcriptions
/v1/transcriptionsList your transcriptions with optional filters and cursor-based pagination. Newest first by default. Soft-deleted transcriptions are excluded.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| status | string | Optional | Only return jobs in this status. One of: "created", "downloading", "pending", "processing", "completed", "failed". |
| from | string | Optional | Inclusive lower bound on created_at. An ISO 8601 timestamp. |
| to | string | Optional | Exclusive upper bound on created_at. An ISO 8601 timestamp. |
| limit | integer | Optional | Page size. Range: 1–200. Default: 50. |
| order | string | Optional | Sort direction on created_at. One of: "desc", "asc". Default: desc. |
| cursor | string | Optional | Opaque cursor from the next_cursor field of a previous response. |
statusstringOptionalOnly return jobs in this status. One of: "created", "downloading", "pending", "processing", "completed", "failed".
fromstringOptionalInclusive lower bound on created_at. An ISO 8601 timestamp.
tostringOptionalExclusive upper bound on created_at. An ISO 8601 timestamp.
limitintegerOptionalPage size. Range: 1–200. Default: 50.
orderstringOptionalSort direction on created_at. One of: "desc", "asc". Default: desc.
cursorstringOptionalOpaque cursor from the next_cursor field of a previous response.
Response
{"items": [{"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "completed","audio_duration_seconds": 120,"file_size_bytes": 1920000,"language": "en","diarize": true,"speaker_count": 2,"align": true,"cost_cents": 0.666667,"created_at": "2026-05-18T10:30:00Z","started_at": "2026-05-18T10:30:01Z","completed_at": "2026-05-18T10:30:45Z","source_url": "https://example.com/podcast.mp3"}],"next_cursor": "eyJ0IjoiMjAyNi0wNS0xOFQxMDozMDowMFoiLCJpIjoiYjJjM2Q0ZTUtZjZhNy04OTAxLWJjZGUtZjEyMzQ1Njc4OTAxIn0="}
Code Examples
resp = requests.get("https://api.scriptivox.com/v1/transcriptions",headers={"Authorization": "sk_live_YOUR_KEY"},params={"status": "completed", "limit": 20})page = resp.json()for item in page["items"]:print(item["id"], item["status"])if page["next_cursor"]:# fetch the next pageresp = requests.get("https://api.scriptivox.com/v1/transcriptions",headers={"Authorization": "sk_live_YOUR_KEY"},params={"cursor": page["next_cursor"]})
Each item matches the shape of GET /v1/transcribe/{id} except that the heavy result object is omitted; fetch individual transcriptions for the full transcript. Pagination is stable across new inserts: pass the next_cursor value from the response into the cursor query param to get the next page. next_cursor is null when there are no more pages.
Cancel transcription
/v1/transcribe/{id}/cancelStop a transcription before it starts transcribing. Fires the transcription.failed webhook (if configured) with error.code=CANCELLED. You are not charged. Idempotent: calling cancel on an already-cancelled job returns the same response.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transcription ID returned by POST /v1/transcribe. |
idstringRequiredTranscription ID returned by POST /v1/transcribe.
Response
{"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","status": "failed","error": {"code": "CANCELLED","message": "Cancelled by customer"},"released_cents": 0}
Code Examples
requests.post(f"https://api.scriptivox.com/v1/transcribe/{transcription_id}/cancel",headers={"Authorization": "sk_live_YOUR_KEY"})
Cancel is allowed while the job is in created, downloading or pending state, before transcription starts; you are not charged. Once the job is processing, it is already being transcribed: cancel returns 409 CONFLICT, and the job finishes and is billed as usual (delete it afterwards if you don't need it). Cancelling a completed or failed job also returns 409 CONFLICT.
Resend a webhook
/v1/transcribe/{id}/webhook/resendSend a finished job's final webhook (transcription.completed or transcription.failed) again now, with the same X-Scriptivox-Delivery id. One try; automatic retries still left carry on as scheduled. Answers 200 when the try was made; delivered says whether your server answered 2xx.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transcription ID returned by POST /v1/transcribe. |
idstringRequiredTranscription ID returned by POST /v1/transcribe.
Response
{"transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","delivery_id": "6f1c2d3e-4a5b-4c6d-8e7f-9a0b1c2d3e4f","event": "transcription.completed","attempt": 4,"delivered": true,"response_code": 200,"error": null,"duration_ms": 231,"status": "succeeded","next_attempt_at": null}
Code Examples
requests.post(f"https://api.scriptivox.com/v1/transcribe/{transcription_id}/webhook/resend",headers={"Authorization": "sk_live_YOUR_KEY"})
A job that finished without a webhook URL is sent to your account's default webhook URL; with neither, the call returns 400 INVALID_REQUEST. A job still in progress returns 409 CONFLICT: its final event is sent when it finishes. See Webhooks: delivery behavior.
Send a test webhook
/v1/webhooks/testSend a signed webhook.test event to url (or, without one, to your account's default webhook URL) now, with the same headers as real events. One try. Use it to check your endpoint and your signature check before going live.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | Optional | Where to send the test event (https:// only). Without it, your account's default webhook URL is used. |
urlstringOptionalWhere to send the test event (https:// only). Without it, your account's default webhook URL is used.
Response
{"url": "https://example.com/webhooks/scriptivox","delivery_id": "0a1b2c3d-4e5f-4a6b-8c7d-8e9f0a1b2c3d","event": "webhook.test","attempt": 1,"delivered": false,"response_code": 401,"error": "HTTP 401","duration_ms": 118,"status": "failed","next_attempt_at": null}
Code Examples
requests.post("https://api.scriptivox.com/v1/webhooks/test",headers={"Authorization": "sk_live_YOUR_KEY"},json={"url": "https://example.com/webhooks/scriptivox"})
Send feedback on a job
/v1/transcribe/{id}/feedbackRate a completed transcription from 1 to 5, report a problem with any of your transcriptions, or both in one call. Every feedback needs words, at least 20 characters. Every reported problem is resolved within 24 hours; the reply goes to your account's email.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transcription ID returned by POST /v1/transcribe. |
| rating | integer | Optional | How good the transcript is, 1 (poor) to 5 (excellent). Completed jobs only. Needs comment or their_words, at least 20 characters. Range: 1–5. |
| topics | array | Optional | Optional: what the feedback is about. |
| comment | string | Optional | What made it that rating, in words. With a rating: comment or their_words, at least 20 characters. Maximum 1000 characters. |
| their_words | string | Optional | Your end user's own words, unchanged, if you have them. Counts as the words for a rating or a problem report. Maximum 1000 characters. |
| problem | boolean | Optional | true to report a problem with this job (failed, empty or wrong). Needs what_happened. |
| what_happened | string | Optional | What went wrong, for a problem report: what_happened or their_words, at least 20 characters. Maximum 1000 characters. |
idstringRequiredTranscription ID returned by POST /v1/transcribe.
ratingintegerOptionalHow good the transcript is, 1 (poor) to 5 (excellent). Completed jobs only. Needs comment or their_words, at least 20 characters. Range: 1–5.
topicsarrayOptionalOptional: what the feedback is about.
commentstringOptionalWhat made it that rating, in words. With a rating: comment or their_words, at least 20 characters. Maximum 1000 characters.
their_wordsstringOptionalYour end user's own words, unchanged, if you have them. Counts as the words for a rating or a problem report. Maximum 1000 characters.
problembooleanOptionaltrue to report a problem with this job (failed, empty or wrong). Needs what_happened.
what_happenedstringOptionalWhat went wrong, for a problem report: what_happened or their_words, at least 20 characters. Maximum 1000 characters.
Response
{"transcription_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901","rating_saved": true,"problem_report": {"id": "7d1e2f3a-4b5c-4d6e-8f70-819a2b3c4d5e","status": "open","added_to_open_report": false,"opened_by_rating": true}}
Code Examples
requests.post(f"https://api.scriptivox.com/v1/transcribe/{transcription_id}/feedback",headers={"Authorization": "sk_live_YOUR_KEY"},json={"rating": 2, "topics": ["speakers"], "comment": "Speaker labels are swapped after minute 3."})
Every feedback needs words, at least 20 characters: a rating needs comment or their_words (what made it that rating), a problem report what_happened or their_words. Without them the answer is 400 INVALID_REQUEST with "A rating needs words: comment or their_words, at least 20 characters." Topics are optional: accuracy, clarity, speakers, timing, language, formatting, other.
A second rating of the same job replaces the first. A rating of 1 or 2 also opens a problem report, so it is looked at within the same 24 hours. Send problem: true with what_happened for a job that failed, came back empty, or is wrong; a report on a job whose report is still open is added to it. A rating on a job that has not completed returns 409 CONFLICT. At most 5 new problem reports a day per account (429 RATE_LIMIT_EXCEEDED after that).
If a kind of feedback is switched off, what you send is kept as the nearest kind that is on, so your words are never lost: rating_saved is false, saved_as names the kind it was kept as (a rating of 1 or 2 becomes a problem report), and notice says so. If no other kind can keep it, the answer is 409 CONFLICT.
Delete transcription
/v1/transcribe/{id}Soft-delete a completed or failed transcription. Removes the stored transcript from our storage. The job record is kept for 7 days for audit, then hard-deleted. In-flight jobs cannot be deleted; cancel them first.
Authorization: sk_live_YOUR_KEYRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
| id | string | Required | Transcription ID returned by POST /v1/transcribe. |
idstringRequiredTranscription ID returned by POST /v1/transcribe.
Response
(204 No Content: empty body)
Code Examples
requests.delete(f"https://api.scriptivox.com/v1/transcribe/{transcription_id}",headers={"Authorization": "sk_live_YOUR_KEY"})
Returns 204 No Content on success. Idempotent: deleting an already-deleted transcription also returns 204. Trying to delete an in-flight transcription returns 409 CONFLICT with a message telling you to cancel first.
Balance
A balance above zero is required to start an upload or submit a transcription: POST /v1/upload and POST /v1/transcribe return 402 ZERO_BALANCE when your balance is $0 or below. balance_cents can be below zero after a refunded deposit. The exact cost is reserved once the audio duration is known (after download/validation), not on submission.
Auto top-up. In Add Funds or on the Billing page you can save a card and turn on auto top-up: each time available_cents falls below your threshold, we charge the card your top-up amount. auto_topup in the response shows whether it is on and its two amounts. The check runs after each job's cost is reserved and charged, on GET /v1/balance, and every few minutes, so a top-up shows on a later call. See Pricing.
/v1/balanceReturns your current account balance in cents, the amount reserved for in-progress transcriptions, the amount available for new jobs, and an estimate of remaining hours at the current per-hour price.
Authorization: sk_live_YOUR_KEYResponse
{"balance_cents": 1500,"reserved_cents": 100,"available_cents": 1400,"price_per_hour_cents": 20,"estimated_hours_available": 70,"deposit_url": "https://platform.scriptivox.com/billing","updated_at": "2025-01-15T10:30:00Z","auto_topup": {"enabled": true,"threshold_cents": 500,"amount_cents": 2000}}
Code Examples
resp = requests.get("https://api.scriptivox.com/v1/balance",headers={"Authorization": "sk_live_YOUR_KEY"})balance = resp.json()print(f"Available: ${balance['available_cents'] / 100:.2f}")print(f"Hours remaining: {balance['estimated_hours_available']:.1f}")
Error Codes
All errors follow the same format:
{"error": {"code": "ERROR_CODE","message": "Human-readable description","docs_url": "https://platform.scriptivox.com/docs/api-reference#error-codes","request_id": "req_8f3a1c2b9d4e6f70"}}
code is stable and safe to branch on. message is a sanitized, customer-safe string (never a raw stack trace), and its wording may change. docs_url points back at this table. request_id identifies the request.
Request IDs
Every response, successful or not, carries an X-Request-Id header: req_ followed by 16 hex characters. Error bodies repeat the same value as error.request_id. Log it with failed calls, and include it when you contact support: it lets us find that exact request on our side. A refused submit (400, 402, 429) has no transcription ID, so the request ID is the way to point us at it. Every response also carries a Link: <https://platform.scriptivox.com/openapi.json>; rel="service-desc" header pointing at the machine-readable OpenAPI specification.
New fields may be added to the error object over time; treat unknown keys as ignorable rather than as a parse failure.
Synchronous errors (returned immediately on the request)
| HTTP | Code | Description |
|---|---|---|
| 400 | INVALID_REQUEST | Malformed request body or missing required fields. Also returned at once for a link to a site whose links cannot be transcribed right now (error.reason platform_disabled, error.platform names the site); the message says what to send instead. |
| 400 | INVALID_FILENAME | Filename is missing, too long, contains invalid characters, or has no extension |
| 400 | INVALID_MEDIA_FORMAT | Unsupported file extension at upload time (e.g. .txt, .pdf). Also returned later if the contents turn out not to be readable audio or video. |
| 400 | FILE_NOT_UPLOADED | File not found at the upload URL |
| 400 | FILE_TOO_LARGE | File exceeds 5 GB limit |
| 400 | UPLOAD_ALREADY_USED | Upload already used for a transcription |
| 400 | UPLOAD_EXPIRED | Upload URL expired (1 hour TTL) |
| 400 | URL_NOT_ACCESSIBLE | A TikTok, Instagram, Facebook, X or Snapchat post that can't be transcribed, refused when you send it: nothing is created or charged. error.reason says why: link_not_verifiable (private, deleted or not available in the region), link_not_found (the video can't be opened), link_unsupported (a kind of link that is not a video, such as a Facebook Page or profile), link_no_media (no audio or video, such as a photo post); error.platform names the site. Sending the same link again gives the same answer. Also returned at once for a Google Drive link while Google has paused downloads of your files (error.reason drive_paused): a Drive job of yours ended with Google's download limit, so new Drive links are refused until error.paused_until (24 hours later); upload the file instead. Other links that can't be downloaded fail later on GET /v1/transcribe/{id}. |
| 400 | DURATION_TOO_LONG | A social post whose video is longer than 10 hours, refused when you send it (error.platform names the site). Nothing is created or charged. |
| 401 | INVALID_API_KEY | Invalid or missing API key |
| 401 | API_KEY_REVOKED | API key has been revoked |
| 402 | INSUFFICIENT_BALANCE | Not enough balance for this transcription |
| 402 | ZERO_BALANCE | Balance is $0 or below: deposit required |
| 403 | FORBIDDEN | Request rejected upstream (e.g. by the network layer) before it reached the API. |
| 404 | UPLOAD_NOT_FOUND | Upload ID does not exist |
| 404 | TRANSCRIPTION_NOT_FOUND | Transcription ID does not exist |
| 404 | NOT_FOUND | Path doesn't match any endpoint |
| 405 | METHOD_NOT_ALLOWED | The path exists but only accepts a different HTTP method. The response includes an Allow header naming the accepted method (e.g. Allow: GET if you POST to /v1/balance). |
| 409 | CONFLICT | Action not allowed in the current state (e.g. delete on an in-flight job, cancel on a job that is already transcribing or completed) |
| 409 | IDEMPOTENCY_KEY_LOCKED | Another request with the same Idempotency-Key is mid-flight. Retry after a few seconds (Retry-After header sent). |
| 409 | SOURCE_EXPIRED | source_transcription_id names a job whose audio was deleted 24 hours after it ended, so it cannot be transcribed again: nothing is created or charged. Send the file again with upload_id or url. |
| 410 | ENDPOINT_REMOVED | This endpoint has been removed. The message says what to use instead (for POST /v1/accounts: create the account at https://www.scriptivox.com/signup). |
| 413 | PAYLOAD_TOO_LARGE | Request body exceeds 100KB. This is the JSON body, not the media file. Large files go to the presigned upload URL, which has its own 5 GB limit. |
| 415 | UNSUPPORTED_MEDIA_TYPE | Request body sent without Content-Type: application/json on a POST/PUT/PATCH. The response includes an Accept-Post: application/json header. Parameters are allowed (application/json; charset=utf-8 works). |
| 422 | IDEMPOTENCY_KEY_CONFLICT | Idempotency-Key reused with a different request body. Use a fresh key for a different operation. |
| 422 | NO_SPEECH | A link whose transcriptions for your account already found no speech twice in the last 30 days (each completed with an empty transcript), refused when you send it again: nothing is created. error.transcription_ids names the earlier jobs. Send a recording with audible speech, or a different file. |
| 429 | RATE_LIMIT_EXCEEDED | Too many requests (see Rate Limits), or 25 jobs already in progress on POST /v1/transcribe. On POST /v1/transcribe with a social post link, also a limit on social links set on your account (error.reason social_link_limit, with error.limit and error.window_seconds; accounts have none unless Scriptivox sets one); uploads and other links are not affected. Wait the seconds in the Retry-After header. |
| 500 | INTERNAL_ERROR | Server error |
| 503 | LINK_CHECK_UNAVAILABLE | A social post link could not be checked right now, so nothing was created or charged. error.reason verify_rate_limited: link checks are busy (Retry-After: 600); link_check_failed: the check did not answer (Retry-After: 60). Send the same request again after that many seconds. Links to files and to Google Drive, Dropbox or OneDrive are not checked and are not affected. |
| 503 | TEMPORARILY_UNAVAILABLE | Your data could not be read just now (a brief problem on our side), so the request was not completed: nothing was created, changed or charged. Send the same request again after the number of seconds in the Retry-After header. |
| 503 | MAINTENANCE | The API is briefly paused for maintenance. Nothing was created or charged. Retry after the number of seconds in the Retry-After header. |
| 503 | ISSUER_UNCONFIGURED | OAuth sign-in is not configured on this deployment. |
Asynchronous errors (surface only on GET /v1/transcribe/{id})
POST /v1/transcribe accepts the job and returns {"status":"created"} even if the input will ultimately fail. The one exception is a link to a social post, which is checked on the submit call (see social posts). The errors below only appear on the GET endpoint, with the top-level status set to "failed" and the failure reason in the error object. Your client must handle these on the poll path, not on submit.
| Code | When it appears |
|---|---|
| URL_NOT_ACCESSIBLE | URL flow only. Covers several non-fetchable cases: the URL returned 4xx/5xx; DNS didn't resolve; the connection was refused; the response was an HTML page instead of media (login/preview/folder/expired-link, or a video site's page instead of its video); the share requires sign-in (e.g. OneDrive 1drv.ms/v/c/… SharePoint Photos shares); or the server returned a 200 with an empty body. For a social post that passed the check: its video file could not be downloaded, or the download links the site gave expired before the download and checking the post again did not give working ones. The message field names the specific cause when detectable. |
| DOWNLOAD_FAILED | URL flow only: the download started but was interrupted. |
| INVALID_MEDIA_FORMAT | The file downloaded but could not be read: not actually audio/video, no audio track, or shorter than the 1-second minimum (message names the measured duration, e.g. "Audio too short (0.10s). Minimum duration is 1 second."). |
| FILE_TOO_LARGE | The file is larger than 5 GB. For a URL this is only known once the download reaches the limit. |
| DURATION_TOO_LONG | Audio exceeds the 10-hour limit (only known after probing duration). |
| INSUFFICIENT_BALANCE | Once the length was measured, the job cost more than your available balance. Nothing was charged. The message names the amount needed; add funds and submit again. |
| PROCESSING_ERROR | Transcription failed after all retries. |
| SPEECH_BELOW_THRESHOLD | You set speech_threshold and less of the audio than that was speech (the message gives both shares). Nothing was charged and the job is not retried: sending the same file again gives the same result. Without speech_threshold, a file with no speech completes with an empty transcript and result.no_speech: true, and is charged on its length. |
| CREATED_TIMEOUT | Job sat in created for more than 30 minutes: the validation step never started. |
| DOWNLOAD_TIMEOUT | Job sat in downloading for more than 15 minutes: the file download stalled. |
| PROCESSING_TIMEOUT | Job sat in processing for more than 45 minutes without a result. |
| BILLING_ERROR | Internal accounting issue while finalizing the charge. Your balance was not debited and the transcript was not delivered. Safe to retry. |
| INTERNAL_ERROR | A server-side step (e.g. queueing the job to our processing layer) failed after we accepted the request. Safe to retry. |
| CANCELLED | The transcription was cancelled by the customer via POST /v1/transcribe/{id}/cancel. You are not charged. |
Failed transcriptions are free. The reserved balance is released back to your account, so a failure costs $0 regardless of how far the job got.
error.message is always a sanitized, customer-safe string; we never forward raw internal errors. If you need more detail than the message provides for a PROCESSING_ERROR, contact support with the transcription ID and we can look up the raw error on our side.
Important notes
Language parameter behavior
Recommended: always pass language explicitly. Auto-detection works in most cases but has a small failure rate that's fully avoidable. Passing the actual language gives more accurate transcripts, faster turnaround (the model skips its detection pass), and protects you from the known edge cases below.
When you specify a language code, the model is forced to interpret the audio as that language. If the audio is actually in a different language, the model may translate rather than transcribe. For example, setting language: "es" on English audio can produce a Spanish translation of the speech. Omit language (or pass null) to let the model auto-detect.
Auto-detect picks a single dominant language for the whole file and is not perfect:
- Code-switched audio (e.g. English/Spanish in the same clip) typically gets transcribed as the dominant language, and segments in the other language may be dropped or mistranscribed.
- Hindi audio is sometimes routed to Urdu by the detector. If you know the language in advance, pass it explicitly.
- Short clips (under 30s) give the detector less signal and are more likely to mis-route.
- Music or background noise during the first few seconds can throw the detector off.
If you know the language up front, even probabilistically, pass it. The accuracy cost of being wrong is roughly the same as the cost of auto-detect picking the wrong language, but passing it is faster and works on the edge cases above.
Silence and very short clips
Speech recognition can misfire on near-silent or sub-second audio, sometimes producing a phantom "Thank you." or similar filler. If your pipeline can produce silent or extremely short clips, filter them on your side before submitting.
Files with no speech
Billing is on the length of the audio, not on how much of it is speech. A file with no speech (silence, music or noise only) completes with an empty transcript (full_transcript: "", utterances: []) and result.no_speech: true, and is charged on its length.
To skip files with too little speech, set speech_threshold on POST /v1/transcribe: the share of the audio, from 0 to 1, that must be speech. A job below it fails with SPEECH_BELOW_THRESHOLD, its message gives both shares, and nothing is charged. The share is measured reliably from about 30 seconds of audio. A file with no audio track at all fails with INVALID_MEDIA_FORMAT and is not charged.
Size, duration, and retention limits
- Max file size: 5 GB. Anything larger is rejected with
400 FILE_TOO_LARGE. Very large uploads can also be rejected by the network layer with an HTML413page before they reach the API, so your client should handle non-JSON error bodies gracefully. - Max duration: 10 hours. Files probing longer than this fail with
DURATION_TOO_LONG(asynchronous; you'll see it on the GET endpoint after probing completes). - Min duration: 1 second. Shorter files fail asynchronously with
INVALID_MEDIA_FORMATand a message naming the actual measured duration. (Sub-second clips have too little speech signal to transcribe reliably.) - Request body Content-Type: every
POST/PUT/PATCHthat carries a JSON body must sendContent-Type: application/json(parameters allowed, e.g.application/json; charset=utf-8). Anything else is rejected at the gateway with415 UNSUPPORTED_MEDIA_TYPEand anAccept-Post: application/jsonheader. - Presigned URL TTL: 1 hour. Uploads must
PUTto the URL withinexpires_inseconds of receiving it; after that the URL returns400 UPLOAD_EXPIRED. - Audio retention: uploaded source audio is retained for 24 hours after the job ends, then deleted. Transcripts themselves remain available via
GET /v1/transcribe/{id}.
Filename rules
The filename you pass to POST /v1/upload must satisfy all of the following:
- ASCII only (rename files with accents, CJK, or emoji before upload; storage rejects non-ASCII object keys).
- No path separators:
/and\are rejected. - No `< > " ' ``: rejected to prevent injection into dashboards that render filenames unescaped.
- Must include a supported extension (e.g.
.mp3,.wav,.mp4). See Supported Formats for the full list. - 255 characters or fewer.
Violations return 400 INVALID_FILENAME (or 400 INVALID_MEDIA_FORMAT if the extension is present but unsupported).
audio_duration_seconds is an integer
audio_duration_seconds in GET /v1/transcribe/{id} is rounded to the nearest whole second (so an 11.7-second clip returns 11). cost_cents, by contrast, is fractional and exact (e.g. 0.061111 for an 11-second clip at $0.20/hour). Your account balance is debited against the precise value, not a rounded one.
speaker_count is a soft prior, not a hard ceiling
When you set speaker_count: N with diarize: true, you're giving the diarizer a hint about how many speakers to expect, not a hard cap. The result may include slightly more or fewer speaker labels than N (e.g. requesting 5 may produce 6). Values outside 1–50, or speaker_count without diarize: true, are rejected with 400 INVALID_REQUEST.
Recommended: whenever you know how many speakers are on the recording, pass speaker_count. It noticeably improves diarization accuracy: the model uses it as a prior instead of guessing, which cuts down on over-segmentation (one speaker split across two labels) and under-segmentation (two speakers merged into one).
Per-word leading whitespace
Word objects in align: true output have whitespace pre-stripped (e.g. {"word":"The"}, not {"word":" The"}). Reconstruct sentence text from utterance.text if you need exact spacing.
diarize forces align
diarize requires word-level alignment to map speakers onto each word, so any request with diarize: true is processed as if align: true, even when the caller explicitly passes align: false. The stored job and webhook payload reflect the effective value (align: true), and word objects are present on the result. If you don't want alignment data, leave diarize off.
Idempotency
Both POST /v1/upload and POST /v1/transcribe accept an optional Idempotency-Key HTTP header. When present, we cache the response for 24 hours and replay it byte-for-byte on subsequent requests with the same key and body. This protects you against double-billed transcriptions if your network drops the response and your client retries.
curl -X POST https://api.scriptivox.com/v1/transcribe \-H "Authorization: sk_live_YOUR_KEY" \-H "Idempotency-Key: 7c8f5b3a-1234-4d56-90ab-cdef01234567" \-H "Content-Type: application/json" \-d '{"url": "https://example.com/audio.mp3"}'
Rules:
- Key is opaque; we don't parse it. Generate one per logical operation (a UUID is conventional). Reuse the same key when retrying after a failure.
- 1–255 printable ASCII characters.
- Same key + same body within 24 hours → cached response is replayed. The replayed response carries a
Idempotent-Replay: trueheader so you can tell it was cached. - Same key + different body →
422 IDEMPOTENCY_KEY_CONFLICT. This is a bug in your retry logic. Use a fresh key for a different operation. - Same key while a previous request is still in progress →
409 IDEMPOTENCY_KEY_LOCKEDwith aRetry-Afterheader. Sleep briefly and retry; the cached response will be available once the first request finishes. - No header sent → endpoint behaves normally (no caching).
The replay cache covers 200 success responses only. 4xx and 5xx errors are not cached, so you can retry freely.
Unknown fields are rejected
Request bodies on POST /v1/upload and POST /v1/transcribe are strict: any top-level field that isn't in the documented parameter list returns 400 INVALID_REQUEST with the offending key name. This is to surface typos ({"dirize": true}) immediately instead of silently ignoring them. Nested objects (e.g. inside a future metadata field) are not currently inspected.
Response shape changes with diarize and align
The GET /v1/transcribe/{id} example above shows the response with diarize: true and align: true (the maximal case). When you turn flags off, some result fields become null or empty:
| Field | diarize: false | align: false |
|---|---|---|
result.speakers | null | unchanged |
result.utterances[].speaker | null | unchanged |
result.utterances[].words | unchanged | [] (empty array) |
result.utterances[].words[].speaker | key absent | n/a (no words) |
Top-level metadata (status, cost_cents, audio_duration_seconds, etc.) is identical regardless of flags. result.utterances[].confidence and result.utterances[].words[].confidence may be null: confidence scores depend on the alignment model used for the detected language, and not every language is covered. Always handle null defensively (e.g. skip filtering by confidence rather than dropping the word).
Speaker labels are "SPEAKER 1", "SPEAKER 2", … (space, 1-indexed), not "SPEAKER_00". source_url is only present on URL-flow transcriptions; upload-flow jobs omit it.
Rate Limits
Limits are enforced per API key per endpoint, plus a per-IP cap across all endpoints. Exceeding any limit returns 429 RATE_LIMIT_EXCEEDED with a Retry-After header.
| Scope | Limit | Notes |
|---|---|---|
POST /v1/upload (per key) | 60/min | Create a presigned upload URL |
POST /v1/transcribe (per key) | 60/min | Start a transcription |
GET /v1/transcribe/{id} (per key) | 200/min | Get a transcription |
DELETE /v1/transcribe/{id} (per key) | 30/min | Delete a transcription |
POST /v1/transcribe/{id}/cancel (per key) | 30/min | Cancel a transcription before it starts transcribing |
POST /v1/transcribe/{id}/webhook/resend (per key) | 30/min | Send a finished job's final webhook again |
POST /v1/transcribe/{id}/feedback (per key) | 10/min | Rate a job or report a problem with it |
POST /v1/webhooks/test (per key) | 10/min | Send a test webhook to your URL |
GET /v1/transcriptions (per key) | 60/min | List transcriptions |
GET /v1/balance (per key) | 100/min | Get account balance |
GET /v1 (per IP) | 100/min | Describe the API |
| Per source IP (across all endpoints) | 300/min | Edge-level cap to prevent abuse |
Limits use a sliding 60-second window, not a fixed-window counter: short bursts above the per-minute number are tolerated as long as the rolling 60-second total stays under the limit. Plan against the steady-state number, not the burst.
Jobs in progress. An account can have up to 25 transcriptions in progress at once (created, downloading, pending or processing). A POST /v1/transcribe beyond that returns 429 RATE_LIMIT_EXCEEDED with in_flight and limit in the error and no Retry-After: submit more as earlier jobs finish. Need more? Contact support and we can raise it for your account.
Rate limit headers
Rate limits are advertised in two vocabularies on the same response: the RateLimit-Policy / RateLimit structured fields from draft-ietf-httpapi-ratelimit-headers, and the older X-RateLimit-* spelling that most existing clients read. They always agree; use whichever your HTTP client makes easier.
On every response, including 401 and 429:
| Header | Description |
|---|---|
RateLimit-Policy | The quotas that apply, as an RFC 9651 structured field list. q is the quota, w the window in seconds. Two policies are always listed: "endpoint" (per key, per endpoint) and "ip" (per source IP, across everything). |
X-RateLimit-Limit | The "endpoint" quota, as a bare integer. |
You do not need a working API key to read these. A 401 carries them too, which means an agent can learn what it is allowed to do before it is allowed to do anything.
Once the API key has been validated:
| Header | Description |
|---|---|
RateLimit | Live remaining quota. r is the remaining request count, t the seconds until the window resets. |
X-RateLimit-Remaining | Requests remaining in the current rolling window. |
X-RateLimit-Reset | Unix timestamp when the window fully resets. |
Retry-After | Seconds to wait before retrying. Only on 429. |
RateLimit-Policy: "endpoint";q=60;w=60, "ip";q=300;w=60RateLimit: "endpoint";r=57;t=41X-RateLimit-Limit: 60X-RateLimit-Remaining: 57X-RateLimit-Reset: 1787643480
Which 429 you got
A 429 from the per-key limiter carries the live RateLimit field. A 429 from the per-IP cap or from an abuse block is raised before your key is read, so it carries RateLimit-Policy and Retry-After but no r value, because there is no per-key window to report. Both are safe to retry after Retry-After seconds.
Supported Formats
26 file extensions are accepted (11 audio + 15 video). Maximum file size is 5 GB; maximum duration is 10 hours. Unrecognized extensions return 400 INVALID_MEDIA_FORMAT.
Audio (11)
| Extension | Format |
|---|---|
| .mp3 | MPEG Audio |
| .wav | Waveform Audio |
| .m4a | MPEG-4 Audio |
| .aac | Advanced Audio Coding |
| .ogg | Ogg Vorbis |
| .oga | Ogg Audio |
| .flac | Free Lossless Audio |
| .wma | Windows Media Audio |
| .aiff | Audio Interchange |
| .opus | Opus |
| .caf | Core Audio Format |
Video (15)
| Extension | Format |
|---|---|
| .mp4 | MPEG-4 Video |
| .mov | QuickTime |
| .avi | Audio Video Interleave |
| .mkv | Matroska Video |
| .webm | WebM |
| .wmv | Windows Media Video |
| .flv | Flash Video |
| .m4v | MPEG-4 Video (iTunes) |
| .3gp | 3GPP |
| .mpeg | MPEG Video |
| .mts | AVCHD |
| .ogv | Ogg Video |
| .ts | MPEG Transport Stream |
| .vob | DVD Video Object |
| .f4v | Flash MP4 Video |
Supported Languages
119 languages are supported. Pass the ISO 639-1 (or BCP-47 fallback, e.g. yue, kea) language code below in the language parameter.
We recommend always passing a language explicitly. Omitting the parameter (or passing null) triggers auto-detection, which works for most inputs but has a small chance of picking the wrong language, especially on short clips, code-switched audio, or files that start with music or background noise. See Language parameter behavior for details.
Invalid codes return 400 INVALID_REQUEST.
| Language | Code |
|---|---|
| Afrikaans | af |
| Albanian | sq |
| Amharic | am |
| Arabic | ar |
| Armenian | hy |
| Assamese | as |
| Asturian | ast |
| Azerbaijani | az |
| Bashkir | ba |
| Basque | eu |
| Belarusian | be |
| Bengali | bn |
| Bosnian | bs |
| Breton | br |
| Bulgarian | bg |
| Cantonese | yue |
| Cape Verdean Creole | kea |
| Catalan | ca |
| Cebuano | ceb |
| Chichewa | ny |
| Chinese | zh |
| Croatian | hr |
| Czech | cs |
| Danish | da |
| Dutch | nl |
| English | en |
| Estonian | et |
| Faroese | fo |
| Finnish | fi |
| French | fr |
| Fula | ff |
| Galician | gl |
| Georgian | ka |
| German | de |
| Greek | el |
| Gujarati | gu |
| Haitian Creole | ht |
| Hausa | ha |
| Hawaiian | haw |
| Hebrew | he |
| Hindi | hi |
| Hungarian | hu |
| Icelandic | is |
| Igbo | ig |
| Indonesian | id |
| Irish | ga |
| Italian | it |
| Japanese | ja |
| Javanese | jw |
| Kamba | kam |
| Kannada | kn |
| Kazakh | kk |
| Khmer | km |
| Korean | ko |
| Kyrgyz | ky |
| Lao | lo |
| Latin | la |
| Latvian | lv |
| Lingala | ln |
| Lithuanian | lt |
| Luganda | lg |
| Luo | luo |
| Luxembourgish | lb |
| Macedonian | mk |
| Malagasy | mg |
| Malay | ms |
| Malayalam | ml |
| Maltese | mt |
| Maori | mi |
| Marathi | mr |
| Mongolian | mn |
| Myanmar | my |
| Nepali | ne |
| Northern Sotho | nso |
| Norwegian | no |
| Nynorsk | nn |
| Occitan | oc |
| Odia | or |
| Oromo | om |
| Pashto | ps |
| Persian | fa |
| Polish | pl |
| Portuguese | pt |
| Punjabi | pa |
| Romanian | ro |
| Russian | ru |
| Sanskrit | sa |
| Serbian | sr |
| Shona | sn |
| Sindhi | sd |
| Sinhala | si |
| Slovak | sk |
| Slovenian | sl |
| Somali | so |
| Sorani Kurdish | ckb |
| Spanish | es |
| Sundanese | su |
| Swahili | sw |
| Swedish | sv |
| Tagalog | tl |
| Tajik | tg |
| Tamil | ta |
| Tatar | tt |
| Telugu | te |
| Thai | th |
| Tibetan | bo |
| Turkish | tr |
| Turkmen | tk |
| Ukrainian | uk |
| Umbundu | umb |
| Urdu | ur |
| Uzbek | uz |
| Vietnamese | vi |
| Welsh | cy |
| Wolof | wo |
| Xhosa | xh |
| Yiddish | yi |
| Yoruba | yo |
| Zulu | zu |