Pre-recorded Speech-to-Text

Pre-recorded Speech-to-Text turns audio and video files into accurate, timestamped transcripts. You point the API at a file, it processes the audio in the background, and you fetch the finished transcript with word-level timing, confidence scores, and optional speaker labels.

Transcription is asynchronous. POST /v2/transcripts returns immediately with status: "processing", and you collect the result in one of two ways: poll GET /v2/transcripts/{id} until the status becomes completed (the simple pattern used in this quickstart), or register a webhook_url and let the API notify your server when the transcript finishes (the recommended pattern for production). Short files usually finish in seconds; long recordings take longer.

• An API key. Create one in your workspace under Settings, then API keys. Keys look like rtvk_...
• An audio or video file, either reachable at a public URL or available locally for upload.
• Any HTTP client. The examples below use curl, Python (requests), and JavaScript (fetch).

All requests go to https://api.realtimevoicekit.com and authenticate with a bearer header: Authorization: Bearer rtvk_your_api_key.

The create endpoint accepts exactly one audio source per request:

Requests that include neither field (or both) are rejected with a 400.

The full flow is two calls: create the transcript, then poll it until the status is completed or error.

# 1. Create the transcript
curl -s -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/interview.mp3",
    "model": "whisper-voicekit-best",
    "speaker_labels": true
  }'
# => { "id": "tr_9f2c31b8...", "status": "processing", ... }

# 2. Poll until status is completed (repeat every few seconds)
curl -s https://api.realtimevoicekit.com/v2/transcripts/tr_9f2c31b8 \
  -H "Authorization: Bearer rtvk_your_api_key"

For local files, upload the bytes first through a signed URL, then create the transcript with the resulting upload_id:

The sign request takes filename, content_type, and an optional size_bytes. Only audio and video content types are accepted, uploads can be up to 5 GiB, and the signed URL stays valid for one hour. Send the PUT with the exact headers returned by the sign response.

# 1. Request a signed upload URL
curl -s -X POST https://api.realtimevoicekit.com/v2/uploads/sign \
  -H "Authorization: Bearer rtvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"filename": "meeting.mp3", "content_type": "audio/mpeg"}'
# => { "upload_id": "upload_51c0...", "url": "https://...", "headers": { "Content-Type": "audio/mpeg" }, ... }

# 2. PUT the file bytes to the returned url
curl -s -X PUT "SIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: audio/mpeg" \
  --data-binary @meeting.mp3

# 3. Confirm the upload
curl -s -X POST https://api.realtimevoicekit.com/v2/uploads/upload_51c0/complete \
  -H "Authorization: Bearer rtvk_your_api_key"

# 4. Create the transcript from the upload, then poll as usual
curl -s -X POST https://api.realtimevoicekit.com/v2/transcripts \
  -H "Authorization: Bearer rtvk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"upload_id": "upload_51c0", "model": "whisper-voicekit-best"}'

A transcript moves through these statuses:

Poll every 3 to 5 seconds for typical files. For short clips where latency matters, use a tighter loop as shown in Sync STT. Stop polling on completed or error. In production, prefer registering a webhook (next section) so your server is told when the transcript is done instead of asking repeatedly.

Instead of polling, pass a webhook_url when you create the transcript. When the transcript reaches a terminal state (completed or error), the API sends an HTTP POST with a small JSON notification to that URL. This is the recommended pattern for production: no wasted polling requests, and your pipeline reacts the moment the transcript is ready.

{
  "audio_url": "https://example.com/interview.mp3",
  "model": "whisper-voicekit-best",
  "webhook_url": "https://yourapp.com/hooks/transcripts"
}

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

The event is transcript.completed on success and transcript.error on failure. The notification is deliberately small: on receipt, call GET /v2/transcripts/{id} with your API key to fetch the full transcript (the payload itself carries no transcript text, so a leaked notification exposes nothing).

Delivery rules

• The URL must be a public http or https address. Localhost, private ranges, and internal hosts are rejected at create time with 400 and code invalid_webhook_url.
• Your endpoint has 10 seconds to respond. Return a 2xx quickly and do any heavy work afterward.
• A 5xx response or a network failure is retried, so treat deliveries as at-least-once and handle duplicates idempotently (the transcript_id plus event pair is a stable deduplication key).
• A 4xx response is treated as a permanent rejection and is not retried.
• Webhook delivery never affects the transcript itself: if your endpoint is down, the transcript still completes and polling GET /v2/transcripts/{id} still works as a fallback.

A completed transcript contains the full text plus structured timing data. All timestamps are in milliseconds from the start of the audio.

{
  "id": "tr_9f2c31b8",
  "status": "completed",
  "model": "whisper-voicekit-best",
  "title": "interview.mp3",
  "language_code": "en",
  "speaker_labels": true,
  "text": "Thanks for joining me today. Happy to be here.",
  "words": [
    { "text": "Thanks", "start": 240, "end": 480, "confidence": 0.99, "speaker": "A" }
  ],
  "utterances": [
    {
      "speaker": "A",
      "text": "Thanks for joining me today.",
      "start": 240,
      "end": 1860,
      "confidence": 0.98
    }
  ],
  "confidence": 0.97,
  "audio_duration_sec": 1912,
  "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": "2026-07-22T14:04:02Z"
}

The analysis fields are covered in depth on their own tabs: Speech Understanding for summaries, chapters, entities, and sentiment, and Guardrails for content safety and redaction.

Beyond the raw transcript, you can fetch sentences, paragraphs, and word search or export SRT and VTT subtitles.

Two pre-recorded models are available. Pick per request with the model field; the default is whisper-voicekit-best.

Usage is billed per second of audio at the hourly rate. GET /v2/models returns the live catalog with rates and descriptions, and GET /v2/credits shows your remaining credit.

All options for POST /v2/transcripts: