Transcripts

Transcripts turn pre-recorded audio or video into text with word timings, confidence scores, and optional speaker labels. Create one from a public audio_url or from an upload_id produced by the upload flow, then poll until it completes.

Poll GET /v2/transcripts/{transcript_id} until status is completed or error, or register a webhook_url at creation to receive a callback on the terminal status. Derived reads (sentences, paragraphs, word search, subtitles) return 409 not_ready before completion.

Request body

Response

Returns 201 with a transcript object. The status is normally processing at this point; poll the get endpoint until it completes, or register a webhook_url to be notified on completion.

Errors

curl -X POST https://api.realtimevoicekit.com/v2/transcripts \
  -H "Authorization: Bearer rtvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/podcast-episode.mp3",
    "model": "whisper-voicekit-best",
    "speaker_labels": true,
    "language_code": "en"
  }'

{
  "id": "tr_5c8e2f91d0",
  "status": "processing",
  "model": "whisper-voicekit-best",
  "title": null,
  "language_code": "en",
  "speaker_labels": true,
  "text": null,
  "words": null,
  "utterances": null,
  "confidence": null,
  "audio_duration_sec": null,
  "summary": null,
  "chapters": null,
  "entities": null,
  "sentiment_results": null,
  "content_safety": null,
  "webhook_url": null,
  "error": null,
  "created_at": "2026-07-22T14:03:11Z",
  "completed_at": null
}

When a webhook_url is registered at creation, the API sends an HTTP POST to that URL once the transcript reaches a terminal status. The payload is intentionally minimal; fetch the full transcript with GET /v2/transcripts/{transcript_id} when the notification arrives. Polling remains fully supported, with or without a webhook.

{
  "event": "transcript.completed",
  "transcript_id": "tr_5c8e2f91d0",
  "status": "completed"
}

Delivery behavior

• Requests time out after 10 seconds and redirects are not followed. Respond quickly with a 2xx status and do any heavy work asynchronously.
• A 5xx response or a network failure is retried with backoff. A 4xx response is treated as a permanent failure and is not retried.
• Retries reuse the same notification for the same transcript and status, so make your handler idempotent on transcript_id plus event.
• The URL must be publicly reachable over http or https. Private, loopback, and cloud metadata addresses are rejected at creation with 400 invalid_webhook_url.

Returns { "data": [ …transcript objects… ] }. Only transcripts created through the API are listed; transcripts created in the web workspace are separate.

curl "https://api.realtimevoicekit.com/v2/transcripts?limit=10&offset=0" \
  -H "Authorization: Bearer rtvk_your_api_key"

Returns the full transcript object. 404 not_found when the id does not exist or is not yours.

curl https://api.realtimevoicekit.com/v2/transcripts/tr_5c8e2f91d0 \
  -H "Authorization: Bearer rtvk_your_api_key"

Splits the completed transcript into sentence segments. Requires status to be completed, otherwise 409 not_ready.

curl https://api.realtimevoicekit.com/v2/transcripts/tr_5c8e2f91d0/sentences \
  -H "Authorization: Bearer rtvk_your_api_key"

Groups sentences into paragraphs and returns the same segment shape as the sentences endpoint, wrapped in data. Requires a completed transcript (409 not_ready otherwise).

curl https://api.realtimevoicekit.com/v2/transcripts/tr_5c8e2f91d0/paragraphs \
  -H "Authorization: Bearer rtvk_your_api_key"

Requires a completed transcript. Omitting both parameters returns 400 missing_query.

curl "https://api.realtimevoicekit.com/v2/transcripts/tr_5c8e2f91d0/word-search?q=pricing,roadmap" \
  -H "Authorization: Bearer rtvk_your_api_key"

{
  "query": "pricing, roadmap",
  "total_matches": 3,
  "matches": [
    {
      "text": "pricing",
      "count": 2,
      "timestamps": [
        { "start": 12040, "end": 12480, "confidence": 0.98 },
        { "start": 84200, "end": 84660, "confidence": 0.97 }
      ]
    },
    { "text": "roadmap", "count": 1, "timestamps": [ { "start": 61500, "end": 61980, "confidence": 0.99 } ] }
  ]
}

Returns the subtitle file as plain text: application/x-subrip for SRT, text/vtt for VTT. Requires a completed transcript (409 not_ready).

curl -o captions.srt https://api.realtimevoicekit.com/v2/transcripts/tr_5c8e2f91d0/srt \
  -H "Authorization: Bearer rtvk_your_api_key"

Deletes the transcript and its processed data permanently. Returns 204 No Content on success and 404 not_found when the id does not exist or is not yours. This cannot be undone.

curl -X DELETE https://api.realtimevoicekit.com/v2/transcripts/tr_5c8e2f91d0 \
  -H "Authorization: Bearer rtvk_your_api_key"