Sync Speech-to-Text

Sync STT is the recommended pattern for short clips, voice notes, and single utterances where you want the text back as quickly as possible: submit the clip with whisper-voicekit-fast and poll on a tight interval. Short clips typically complete within seconds of processing starting, so a one-second polling loop feels close to synchronous from the caller's side.

Polling keeps the examples on this page self-contained and returns the text inline, which is what interactive flows want. For production services that can react asynchronously, the recommended completion pattern is a webhook: pass webhook_url on the create call and the API notifies your server when the transcript finishes, no polling at all.

The tradeoff versus realtime streaming: this pattern needs the whole clip up front and returns the whole text at once. If you need partial results while audio is still being captured, use Realtime STT instead.

The recommended settings for short clips: model: "whisper-voicekit-fast" (the lower-latency, cost-effective model at $0.18 per audio hour), an explicit language_code when you know it (skipping detection saves work), and a 1 second polling interval with an overall deadline.

API="https://api.realtimevoicekit.com"
AUTH="Authorization: Bearer rtvk_your_api_key"

# 1. Create the transcript with the fast model
ID=$(curl -s -X POST "$API/v2/transcripts" \
  -H "$AUTH" -H "Content-Type: application/json" \
  -d '{
    "audio_url": "https://example.com/voice-note.mp3",
    "model": "whisper-voicekit-fast",
    "language_code": "en"
  }' | jq -r '.id')

# 2. Poll every second until it completes
while true; do
  STATUS=$(curl -s "$API/v2/transcripts/$ID" -H "$AUTH" | jq -r '.status')
  if [ "$STATUS" = "completed" ]; then break; fi
  if [ "$STATUS" = "error" ]; then echo "transcription failed" >&2; exit 1; fi
  sleep 1
done

# 3. Print the text
curl -s "$API/v2/transcripts/$ID" -H "$AUTH" | jq -r '.text'

For local clips, run the signed-URL upload flow first and create the transcript with upload_id instead of audio_url; the steps are identical to the pre-recorded quickstart. The completed response carries the same fields as any transcript: text, words with millisecond timestamps, confidence, and audio_duration_sec.

• Polling interval: 1 second is a good default for clips under a couple of minutes. Going below roughly 500 ms adds request volume without a meaningful latency win.
• Deadline: always cap the loop. A generous rule of thumb for short clips is 60 to 120 seconds; treat hitting the deadline as a failure and surface it to the user.
• Language: set language_code explicitly when you know it. Automatic detection works, but skipping it removes a step for latency-sensitive clips.
• Model: whisper-voicekit-fast is the right default here. Switch to whisper-voicekit-best when accuracy matters more than turnaround; the flow is identical.
• estimated_duration_sec: optionally send the clip length so the request is pre-checked against your remaining credit before any processing starts.

When the caller does not need the text inline (queues, batch jobs, server-to-server pipelines), drop the polling loop entirely: pass webhook_url on the same POST /v2/transcripts call and the API POSTs a JSON notification to your server when the transcript reaches completed or error. On receipt, fetch the result with GET /v2/transcripts/{id}. This is the recommended production pattern.

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

The URL must be public http(s) (private hosts are rejected with 400 invalid_webhook_url), deliveries are at-least-once with retries on 5xx, and your endpoint has 10 seconds to answer. Full payload shape and delivery rules are documented in Get notified with a webhook.

If latency is the product (live captions, dictation, voice agents reacting mid-sentence), skip the upload-then-poll cycle entirely and stream audio over a WebSocket with Realtime STT. You get partial transcripts while the speaker is still talking, at realtime session pricing.