Transcribe (Pre-recorded)

Transcribe an audio file. The model is chosen via ?model=:

• ?model=pulse-pro: English-only, leaderboard-ranked accuracy. Raw bytes only; pass webhook_url to receive transcription asynchronously on long files.
• ?model=pulse: multilingual transcription (21 streaming + 26 pre-recorded languages), supports both raw bytes and audio-by-URL.

When to use this

Use this endpoint when you have a complete audio file (call recording, voicemail, podcast episode) and want the transcript back in one response. For live transcription as audio arrives, use the realtime WebSocket endpoint (WS /waves/v1/stt/live) instead.

Pulse Pro has no streaming worker today; calls to WS /waves/v1/stt/live?model=pulse-pro return 400 before the WebSocket upgrades.

Input methods

• Raw bytes: Content-Type: application/octet-stream with the audio in the body. All knobs are query parameters.
• URL (?model=pulse only): Content-Type: application/json with {"url": "..."} in the body.

Examples

cURL: Pulse Pro, sync

curl -X POST "https://api.smallest.ai/waves/v1/stt/?model=pulse-pro&language=en&word_timestamps=true" \
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
  -H "Content-Type: application/octet-stream" \
  --data-binary "@./call.wav"

cURL: Pulse Pro, async via webhook

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

Returns 200 { "status": "processing", "request_id": "..." } immediately. The webhook receives the full transcription when ready.

cURL: Pulse, audio-by-URL

curl -X POST "https://api.smallest.ai/waves/v1/stt/?model=pulse&language=en" \
  -H "Authorization: Bearer $SMALLEST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-bucket.s3.amazonaws.com/call.wav"}'

Python

import requests

with open("./call.wav", "rb") as f:
    audio = f.read()

r = requests.post(
    "https://api.smallest.ai/waves/v1/stt/",
    params={"model": "pulse-pro", "language": "en", "word_timestamps": "true"},
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/octet-stream"},
    data=audio,
)
r.raise_for_status()
print(r.json()["transcription"])

JavaScript / TypeScript

import { readFileSync } from "node:fs";

const audio = readFileSync("./call.wav");
const params = new URLSearchParams({ model: "pulse-pro", language: "en", word_timestamps: "true" });

const res = await fetch(`https://api.smallest.ai/waves/v1/stt/?${params}`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.SMALLEST_API_KEY}`, "Content-Type": "application/octet-stream" },
  body: audio,
});
console.log((await res.json()).transcription);

Common gotchas

• model is required. Missing or invalid values return 400 with an enum-validation error.
• Pulse Pro is English only. Pass language=en. Other language codes are accepted at the wire level but produce unpredictable output.
• Pulse Pro does not support audio-by-URL. Send raw bytes or use ?model=pulse for the URL flow.
• Async (webhook) mode is Pulse Pro only. Pulse runs sync only on this endpoint.
• Max payload 250 MB. Larger requests return 413. Compress to mono 16 kHz PCM if you are close to the limit; quality is unaffected.

{
  "url": "https://example.com/audio.wav"
}

{
  "status": "success",
  "transcription": "Hi, how are you doing?",
  "words": [
    {
      "word": "hello",
      "start": 0.32,
      "end": 0.4,
      "confidence": 0.96,
      "speaker": "speaker_0"
    }
  ],
  "utterances": [
    {
      "text": "Hello world.",
      "end": 0.9,
      "speaker": "speaker_0"
    }
  ],
  "language": "en",
  "metadata": {
    "duration": 5.6,
    "processing_time_ms": 240.51,
    "rtfx": 23.3,
    "num_chunks": 1,
    "filename": "audio.wav",
    "fileSize": 268844
  },
  "request_id": "87dd36c1-4267-472d-96ee-4113e0a770a6",
  "gender": "female",
  "emotions": {
    "neutral": 0.72,
    "happy": 0.18,
    "calm": 0.1
  }
}