Scriptivox

    API Reference

    Complete reference for the Scriptivox transcription API. All endpoints require an API key, passed in one of:

    • Authorization: sk_live_… (the Bearer prefix 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.

    POST/v1/transcribe

    Start 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    urlstringRequired

    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.

    languagestringOptional

    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.

    diarizebooleanOptional

    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_countintegerOptional

    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.

    alignbooleanOptional

    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_urlstringOptional

    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_thresholdnumberOptional

    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.

    Response

    json
    {
    "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 status
    import time
    while 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"):
    break
    time.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.

    json
    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.reasonMeaning
    link_not_verifiableThe post is private, deleted or not available in your region.
    link_not_foundThe video can't be opened. Check that it plays in a browser.
    link_unsupportedThe link is not a video, for example a Facebook Page or a profile. Open the video itself and send its own link.
    link_no_mediaThe 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.

    POST/v1/upload

    Get 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    filenamestringRequired

    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.

    Response

    json
    {
    "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 requests
    resp = 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)
    POST/v1/transcribe

    Start 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    upload_idstringRequired

    The upload_id returned by POST /v1/upload.

    languagestringOptional

    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.

    diarizebooleanOptional

    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_countintegerOptional

    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.

    alignbooleanOptional

    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_urlstringOptional

    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_thresholdnumberOptional

    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.

    Response

    json
    {
    "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 status
    import time
    while 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"):
    break
    time.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.

    POST/v1/transcribe

    Start 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    source_transcription_idstringRequired

    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.

    languagestringOptional

    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.

    diarizebooleanOptional

    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_countintegerOptional

    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.

    alignbooleanOptional

    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_urlstringOptional

    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_thresholdnumberOptional

    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.

    Response

    json
    {
    "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 language and the language is detected again.
    • After 24 hours the answer is 409 SOURCE_EXPIRED and nothing is created or charged: send the file again with upload_id or url.
    • Only a completed job. A job in another status answers 400 INVALID_REQUEST with error.current_status; an id that is not one of yours answers 404 TRANSCRIPTION_NOT_FOUND.
    • Idempotency-Key works as on any start: the same key and body give the same job.

    Get result

    GET/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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    idstringRequired

    Transcription ID returned by POST /v1/transcribe.

    formatstringOptional

    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_wordsintegerOptional

    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_charsintegerOptional

    Caption segmentation: maximum characters per cue. The subtitle convention is about 80 (roughly 37 characters across two lines). Range: 10–500. Default: 80.

    max_durationintegerOptional

    Caption segmentation: maximum seconds a single cue stays on screen. Range: 1–60. Default: 10.

    sentence_awarebooleanOptional

    Caption segmentation: end a cue at sentence-ending punctuation (. ! ?). Produces more natural breaks at the cost of more variable cue lengths. Default: true.

    include_speakersstringOptional

    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_charsstringOptional

    Characters to remove from cue text before output, e.g. `strip_chars=,.` drops all commas and periods. Maximum 32 characters.

    include_timestampsbooleanOptional

    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.

    Response

    json
    {
    "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.

    StatusDescription
    createdJob accepted. Download (URL flow) or validation (upload flow) is about to start.
    downloadingURL flow only: the file is being fetched from the provided URL.
    processingThe file has been validated and is being transcribed.
    completedTranscription finished successfully. The result object is now populated.
    failedThe 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:

    formatContent-TypeBody
    json (default)application/jsonFull structured response with result.utterances[]
    srttext/plain; charset=utf-8SubRip Text
    vtttext/vtt; charset=utf-8WebVTT, with <v Speaker> voice tags when speaker labels are shown
    texttext/plain; charset=utf-8Plain 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.

    ParamDefaultRangeEffect
    max_words41–50Maximum 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_chars8010–500Maximum characters per cue. The subtitle convention is about 80 (roughly 37 characters across two lines).
    max_duration101–60Maximum seconds a single cue stays on screen.
    sentence_awaretruetrue / falseEnd a cue at sentence-ending punctuation (. ! ?). Produces more natural breaks at the cost of more variable cue lengths.
    include_speakersautotrue / false / autoWhether 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 charsCharacters to remove from cue text before output, e.g. strip_chars=,. drops all commas and periods.
    include_timestampsfalsetrue / falseformat=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:

    bash
    # 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 settings
    curl "https://api.scriptivox.com/v1/transcribe/{id}?format=srt" \
    -H "Authorization: sk_live_YOUR_KEY"
    # WebVTT, always show speaker tags, strip filler punctuation
    curl "https://api.scriptivox.com/v1/transcribe/{id}?format=vtt&include_speakers=true&strip_chars=,." \
    -H "Authorization: sk_live_YOUR_KEY"
    # Plain text without speaker prefixes
    curl "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 paragraph
    curl "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

    GET/v1/transcriptions

    List your transcriptions with optional filters and cursor-based pagination. Newest first by default. Soft-deleted transcriptions are excluded.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    statusstringOptional

    Only return jobs in this status. One of: "created", "downloading", "pending", "processing", "completed", "failed".

    fromstringOptional

    Inclusive lower bound on created_at. An ISO 8601 timestamp.

    tostringOptional

    Exclusive upper bound on created_at. An ISO 8601 timestamp.

    limitintegerOptional

    Page size. Range: 1–200. Default: 50.

    orderstringOptional

    Sort direction on created_at. One of: "desc", "asc". Default: desc.

    cursorstringOptional

    Opaque cursor from the next_cursor field of a previous response.

    Response

    json
    {
    "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 page
    resp = 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

    POST/v1/transcribe/{id}/cancel

    Stop 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    idstringRequired

    Transcription ID returned by POST /v1/transcribe.

    Response

    json
    {
    "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

    POST/v1/transcribe/{id}/webhook/resend

    Send 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    idstringRequired

    Transcription ID returned by POST /v1/transcribe.

    Response

    json
    {
    "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

    POST/v1/webhooks/test

    Send 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    urlstringOptional

    Where to send the test event (https:// only). Without it, your account's default webhook URL is used.

    Response

    json
    {
    "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

    POST/v1/transcribe/{id}/feedback

    Rate 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    idstringRequired

    Transcription ID returned by POST /v1/transcribe.

    ratingintegerOptional

    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.

    topicsarrayOptional

    Optional: what the feedback is about.

    commentstringOptional

    What made it that rating, in words. With a rating: comment or their_words, at least 20 characters. Maximum 1000 characters.

    their_wordsstringOptional

    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.

    problembooleanOptional

    true to report a problem with this job (failed, empty or wrong). Needs what_happened.

    what_happenedstringOptional

    What went wrong, for a problem report: what_happened or their_words, at least 20 characters. Maximum 1000 characters.

    Response

    json
    {
    "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

    DELETE/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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Request Body

    idstringRequired

    Transcription ID returned by POST /v1/transcribe.

    Response

    json
    (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.

    GET/v1/balance

    Returns 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.

    Authentication: Authorization: sk_live_YOUR_KEY

    Response

    json
    {
    "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:

    json
    {
    "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)

    HTTPCodeDescription
    400INVALID_REQUESTMalformed 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.
    400INVALID_FILENAMEFilename is missing, too long, contains invalid characters, or has no extension
    400INVALID_MEDIA_FORMATUnsupported file extension at upload time (e.g. .txt, .pdf). Also returned later if the contents turn out not to be readable audio or video.
    400FILE_NOT_UPLOADEDFile not found at the upload URL
    400FILE_TOO_LARGEFile exceeds 5 GB limit
    400UPLOAD_ALREADY_USEDUpload already used for a transcription
    400UPLOAD_EXPIREDUpload URL expired (1 hour TTL)
    400URL_NOT_ACCESSIBLEA 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}.
    400DURATION_TOO_LONGA social post whose video is longer than 10 hours, refused when you send it (error.platform names the site). Nothing is created or charged.
    401INVALID_API_KEYInvalid or missing API key
    401API_KEY_REVOKEDAPI key has been revoked
    402INSUFFICIENT_BALANCENot enough balance for this transcription
    402ZERO_BALANCEBalance is $0 or below: deposit required
    403FORBIDDENRequest rejected upstream (e.g. by the network layer) before it reached the API.
    404UPLOAD_NOT_FOUNDUpload ID does not exist
    404TRANSCRIPTION_NOT_FOUNDTranscription ID does not exist
    404NOT_FOUNDPath doesn't match any endpoint
    405METHOD_NOT_ALLOWEDThe 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).
    409CONFLICTAction not allowed in the current state (e.g. delete on an in-flight job, cancel on a job that is already transcribing or completed)
    409IDEMPOTENCY_KEY_LOCKEDAnother request with the same Idempotency-Key is mid-flight. Retry after a few seconds (Retry-After header sent).
    409SOURCE_EXPIREDsource_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.
    410ENDPOINT_REMOVEDThis endpoint has been removed. The message says what to use instead (for POST /v1/accounts: create the account at https://www.scriptivox.com/signup).
    413PAYLOAD_TOO_LARGERequest 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.
    415UNSUPPORTED_MEDIA_TYPERequest 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).
    422IDEMPOTENCY_KEY_CONFLICTIdempotency-Key reused with a different request body. Use a fresh key for a different operation.
    422NO_SPEECHA 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.
    429RATE_LIMIT_EXCEEDEDToo 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.
    500INTERNAL_ERRORServer error
    503LINK_CHECK_UNAVAILABLEA 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.
    503TEMPORARILY_UNAVAILABLEYour 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.
    503MAINTENANCEThe API is briefly paused for maintenance. Nothing was created or charged. Retry after the number of seconds in the Retry-After header.
    503ISSUER_UNCONFIGUREDOAuth 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.

    CodeWhen it appears
    URL_NOT_ACCESSIBLEURL 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_FAILEDURL flow only: the download started but was interrupted.
    INVALID_MEDIA_FORMATThe 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_LARGEThe file is larger than 5 GB. For a URL this is only known once the download reaches the limit.
    DURATION_TOO_LONGAudio exceeds the 10-hour limit (only known after probing duration).
    INSUFFICIENT_BALANCEOnce 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_ERRORTranscription failed after all retries.
    SPEECH_BELOW_THRESHOLDYou 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_TIMEOUTJob sat in created for more than 30 minutes: the validation step never started.
    DOWNLOAD_TIMEOUTJob sat in downloading for more than 15 minutes: the file download stalled.
    PROCESSING_TIMEOUTJob sat in processing for more than 45 minutes without a result.
    BILLING_ERRORInternal accounting issue while finalizing the charge. Your balance was not debited and the transcript was not delivered. Safe to retry.
    INTERNAL_ERRORA server-side step (e.g. queueing the job to our processing layer) failed after we accepted the request. Safe to retry.
    CANCELLEDThe 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 HTML 413 page 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_FORMAT and 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 / PATCH that carries a JSON body must send Content-Type: application/json (parameters allowed, e.g. application/json; charset=utf-8). Anything else is rejected at the gateway with 415 UNSUPPORTED_MEDIA_TYPE and an Accept-Post: application/json header.
    • Presigned URL TTL: 1 hour. Uploads must PUT to the URL within expires_in seconds of receiving it; after that the URL returns 400 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.

    bash
    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: true header 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_LOCKED with a Retry-After header. 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:

    Fielddiarize: falsealign: false
    result.speakersnullunchanged
    result.utterances[].speakernullunchanged
    result.utterances[].wordsunchanged[] (empty array)
    result.utterances[].words[].speakerkey absentn/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.

    ScopeLimitNotes
    POST /v1/upload (per key)60/minCreate a presigned upload URL
    POST /v1/transcribe (per key)60/minStart a transcription
    GET /v1/transcribe/{id} (per key)200/minGet a transcription
    DELETE /v1/transcribe/{id} (per key)30/minDelete a transcription
    POST /v1/transcribe/{id}/cancel (per key)30/minCancel a transcription before it starts transcribing
    POST /v1/transcribe/{id}/webhook/resend (per key)30/minSend a finished job's final webhook again
    POST /v1/transcribe/{id}/feedback (per key)10/minRate a job or report a problem with it
    POST /v1/webhooks/test (per key)10/minSend a test webhook to your URL
    GET /v1/transcriptions (per key)60/minList transcriptions
    GET /v1/balance (per key)100/minGet account balance
    GET /v1 (per IP)100/minDescribe the API
    Per source IP (across all endpoints)300/minEdge-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:

    HeaderDescription
    RateLimit-PolicyThe 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-LimitThe "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:

    HeaderDescription
    RateLimitLive remaining quota. r is the remaining request count, t the seconds until the window resets.
    X-RateLimit-RemainingRequests remaining in the current rolling window.
    X-RateLimit-ResetUnix timestamp when the window fully resets.
    Retry-AfterSeconds to wait before retrying. Only on 429.
    http
    RateLimit-Policy: "endpoint";q=60;w=60, "ip";q=300;w=60
    RateLimit: "endpoint";r=57;t=41
    X-RateLimit-Limit: 60
    X-RateLimit-Remaining: 57
    X-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)

    ExtensionFormat
    .mp3MPEG Audio
    .wavWaveform Audio
    .m4aMPEG-4 Audio
    .aacAdvanced Audio Coding
    .oggOgg Vorbis
    .ogaOgg Audio
    .flacFree Lossless Audio
    .wmaWindows Media Audio
    .aiffAudio Interchange
    .opusOpus
    .cafCore Audio Format

    Video (15)

    ExtensionFormat
    .mp4MPEG-4 Video
    .movQuickTime
    .aviAudio Video Interleave
    .mkvMatroska Video
    .webmWebM
    .wmvWindows Media Video
    .flvFlash Video
    .m4vMPEG-4 Video (iTunes)
    .3gp3GPP
    .mpegMPEG Video
    .mtsAVCHD
    .ogvOgg Video
    .tsMPEG Transport Stream
    .vobDVD Video Object
    .f4vFlash 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.

    LanguageCode
    Afrikaansaf
    Albaniansq
    Amharicam
    Arabicar
    Armenianhy
    Assameseas
    Asturianast
    Azerbaijaniaz
    Bashkirba
    Basqueeu
    Belarusianbe
    Bengalibn
    Bosnianbs
    Bretonbr
    Bulgarianbg
    Cantoneseyue
    Cape Verdean Creolekea
    Catalanca
    Cebuanoceb
    Chichewany
    Chinesezh
    Croatianhr
    Czechcs
    Danishda
    Dutchnl
    Englishen
    Estonianet
    Faroesefo
    Finnishfi
    Frenchfr
    Fulaff
    Galiciangl
    Georgianka
    Germande
    Greekel
    Gujaratigu
    Haitian Creoleht
    Hausaha
    Hawaiianhaw
    Hebrewhe
    Hindihi
    Hungarianhu
    Icelandicis
    Igboig
    Indonesianid
    Irishga
    Italianit
    Japaneseja
    Javanesejw
    Kambakam
    Kannadakn
    Kazakhkk
    Khmerkm
    Koreanko
    Kyrgyzky
    Laolo
    Latinla
    Latvianlv
    Lingalaln
    Lithuanianlt
    Lugandalg
    Luoluo
    Luxembourgishlb
    Macedonianmk
    Malagasymg
    Malayms
    Malayalamml
    Maltesemt
    Maorimi
    Marathimr
    Mongolianmn
    Myanmarmy
    Nepaline
    Northern Sothonso
    Norwegianno
    Nynorsknn
    Occitanoc
    Odiaor
    Oromoom
    Pashtops
    Persianfa
    Polishpl
    Portuguesept
    Punjabipa
    Romanianro
    Russianru
    Sanskritsa
    Serbiansr
    Shonasn
    Sindhisd
    Sinhalasi
    Slovaksk
    Sloveniansl
    Somaliso
    Sorani Kurdishckb
    Spanishes
    Sundanesesu
    Swahilisw
    Swedishsv
    Tagalogtl
    Tajiktg
    Tamilta
    Tatartt
    Telugute
    Thaith
    Tibetanbo
    Turkishtr
    Turkmentk
    Ukrainianuk
    Umbunduumb
    Urduur
    Uzbekuz
    Vietnamesevi
    Welshcy
    Wolofwo
    Xhosaxh
    Yiddishyi
    Yorubayo
    Zuluzu