Convert speech to text

Transcribe an audio file to text using the Pulse model. The fastest way to get a transcript when you already have a recording — pass either the raw bytes or a 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 (WSS /waves/v1/pulse/get_text) instead.

Input methods

Send the audio in one of two ways:

1. Raw bytes — Content-Type: application/octet-stream with the audio in the body. All knobs (language, word_timestamps, etc.) are query parameters.
2. URL — Content-Type: application/json with {"url": "..."} in the body. Useful when the audio already lives in object storage. Same query parameters apply.

Pulse autodetects the language across 30+ supported locales. Pass language explicitly when you already know it — detection is fast but skipping it is faster.

Examples

cURL (raw bytes)

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

cURL (URL)

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

Python (pip install smallestai>=5.3.0)

from smallestai import SmallestAI

client = SmallestAI(api_key="YOUR_API_KEY")
with open("./call.wav", "rb") as f:
    result = client.waves.speech_to_text.transcribe(
        model="pulse",
        request=f.read(),
        language="en",
        word_timestamps=True,
        diarize=True,
    )
print(result.status)         # "success"
print(result.transcription)  # the transcript string

<Note> On `smallestai<5.3.0`, this method was `client.waves.transcribe_pulse(request=..., language=...)` and had no `model` parameter. See the [5.3.0 migration notes](/atoms/changelog) for the full rename table. </Note>

JavaScript / TypeScript (using fetch)

import { readFileSync } from "node:fs";

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

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

Common gotchas

• Max file size is 250 MB. Larger files return HTTP 400 with {errors: "Audio data too large", status: "error", message: "Error handling audio data"}. Compress to mono 16 kHz PCM if you're close to the limit; quality is unaffected.
• Formatting flags (format, punctuate, capitalize) are accepted at the wire level and exposed in the Python SDK as of smallestai>=4.4.0. Today they currently return the same transcript regardless of value — pass them in your integration so it works as the behavior changes.
• Webhook-driven flow: pass webhook_url to receive the transcript asynchronously. The endpoint returns immediately; the transcript hits your webhook when ready. Useful for long files where you don't want to hold an HTTP connection open.
• Speaker diarization (diarize=true) adds latency. Skip it if you only need the words.
• JavaScript / TypeScript: the official smallestai npm package predates the Pulse model, so call this endpoint with fetch or axios as shown above.

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

{
  "status": "success",
  "transcription": "Hello world.",
  "audio_length": 1.7,
  "words": [
    {
      "end": 0.5,
      "speaker": "speaker_0",
      "word": "Hello"
    }
  ],
  "utterances": [
    {
      "text": "Hello world.",
      "end": 0.9,
      "speaker": "speaker_0"
    }
  ],
  "gender": "male",
  "emotions": {
    "happiness": 0.8,
    "sadness": 0.15,
    "disgust": 0.02,
    "fear": 0.03,
    "anger": 0.05
  },
  "metadata": {
    "filename": "audio.mp3",
    "duration": 1.7,
    "fileSize": 1000000
  }
}