Skip to navigation
Speech to TextPre-Recorded

Quickstart

Transcribe pre-recorded audio files using the unified STT endpoint with Pulse or Pulse Pro
View as Markdown

This guide shows you how to convert an audio file into text using the unified Speech-to-Text endpoint. Both Pulse (multilingual, 21 streaming + 12 pre-recorded languages) and Pulse Pro (leaderboard-ranked English) live behind the same path; you pick the model with ?model=.

Pre-Recorded Audio

Transcribe pre-recorded audio files using synchronous HTTPS POST requests. Perfect for batch processing, archived media, and offline transcription workflows.

The Pre-Recorded API takes an audio file and returns a complete transcript in a single request. Send raw bytes or, for the Pulse model, a URL.

Pick a model

If your audio is…UseWhy
English, and you want highest accuracypulse-proTied #2 on the public Open ASR Leaderboard (5.42% ESB avg WER). Pre-recorded HTTP only.
Multilingual, or you need streamingpulse21 streaming + 12 pre-recorded languages, runs on both HTTP and the live WebSocket endpoint.

See the Pulse Pro model card and Pulse model card for full benchmarks and feature matrices.

Endpoint

POST https://api.smallest.ai/waves/v1/stt/?model={pulse|pulse-pro}

The existing path POST /waves/v1/pulse/get_text continues to work alongside the new unified path.

Authentication

Head over to the smallest console to generate an API key, if not done previously. Also look at the Authentication guide for more information about API keys.

Include your API key in the Authorization header:

Authorization: Bearer SMALLEST_API_KEY

Browser and mobile clients should send a short-lived access token minted by your server instead of the API key. Tokens work on this endpoint but not on the older /waves/v1/pulse/get_text path.

Example Request: Pulse Pro (English)

Send raw audio bytes against ?model=pulse-pro. Word timestamps add per-word timing and confidence scores; omit for higher throughput.

# Download sample audio
curl -L -o sample.wav "https://github.com/smallest-inc/cookbook/raw/main/speech-to-text/getting-started/samples/audio.wav"
# Transcribe with Pulse Pro
curl --request POST \
  --url "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en&word_timestamps=true" \
  --header "Authorization: Bearer $SMALLEST_API_KEY" \
  --header "Content-Type: application/octet-stream" \
  --data-binary "@sample.wav"

Async via webhook (Pulse Pro)

For long audio files where you do not want to hold an HTTP connection open, pass webhook_url. The endpoint returns 200 immediately with {"status": "processing", "request_id": "..."}; the transcription hits your webhook when ready.

curl --request POST \
  --url "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en&webhook_url=https://your.app/cb" \
  --header "Authorization: Bearer $SMALLEST_API_KEY" \
  --header "Content-Type: application/octet-stream" \
  --data-binary "@longcall.wav"

Example Request: Pulse (multilingual)

For non-English audio, code-switching, or when you need streaming, use ?model=pulse. Set language explicitly to the known code (en, hi, es, etc.) for best accuracy, or use a regional aggregator for unknown audio: on pre-recorded that’s multi-eu (21 European codes + en) or multi-asian (zh, ja, ko, en). See the Pulse model card for the full per-mode language matrix.

Raw audio bytes

curl --request POST \
  --url "https://api.smallest.ai/waves/v1/stt/?model=pulse&language=hi&word_timestamps=true" \
  --header "Authorization: Bearer $SMALLEST_API_KEY" \
  --header "Content-Type: application/octet-stream" \
  --data-binary "@hindi-sample.wav"

Audio URL (Pulse only)

Pulse also accepts a URL for audio hosted in cloud storage. Pulse Pro does not support audio-by-URL.

curl --request POST \
  --url "https://api.smallest.ai/waves/v1/stt/?model=pulse&language=en&word_timestamps=true" \
  --header "Authorization: Bearer $SMALLEST_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "url": "https://github.com/smallest-inc/cookbook/raw/main/speech-to-text/getting-started/samples/audio.wav"
  }'

For Pulse, set language explicitly to match the audio (en, hi, es, etc.) for the best accuracy. For unknown audio, pick the regional auto-detect scope: pre-recorded supports multi-eu (21 European codes + en) or multi-asian (zh, ja, ko, en). See the Pulse model card for which codes each aggregator covers.

Example Response

Pulse Pro

{
  "status": "success",
  "transcription": "This is a sample audio file for testing speech-to-text transcription with the Pulse API.",
  "words": [
    {"word": "This", "start": 0.32, "end": 0.4, "confidence": 0.9625},
    {"word": "is", "start": 0.48, "end": 0.56, "confidence": 0.9344},
    {"word": "a", "start": 0.64, "end": 0.72, "confidence": 0.9695}
  ],
  "language": "en",
  "metadata": {
    "duration": 5.6,
    "processing_time_ms": 240.51,
    "rtfx": 23.3,
    "num_chunks": 1
  },
  "request_id": "87dd36c1-4267-472d-96ee-4113e0a770a6"
}

Pulse

{
  "status": "success",
  "transcription": "This is a sample audio file for testing speech to text transcription with the Pulse API.",
  "words": [
    {"start": 0.48, "end": 1.12, "word": "This"},
    {"start": 1.12, "end": 1.28, "word": "is"}
  ],
  "utterances": [
    {"start": 0.48, "end": 4.96, "text": "This is a sample audio file for testing speech to text transcription with the Pulse API."}
  ],
  "metadata": {
    "duration": 5.6,
    "fileSize": 268844
  }
}

Full runnable source files: Python | JavaScript | cURL

Next Steps