Speech to text

Hopper transcribes English audio with Nemotron ASR (nemotron-asr), as a file upload or as a live WebSocket stream.

Transcribe a file

POST /v1/audio/transcriptions takes a multipart/form-data upload and returns the transcript with word timestamps.

file (file, required) — PCM16 mono or WAV, up to 25 MB. Compressed audio is rejected; decode it first.
model (string, required) — nemotron-asr.
sample_rate (integer, optional, default 16000) — One of 8000, 16000, 22050, 24000, 44100, 48000.

import os

import requests

response = requests.post(
    "https://api.withhopper.com/v1/audio/transcriptions",
    headers={"Authorization": f"Bearer {os.environ['HOPPER_API_KEY']}"},
    files={"file": open("call.wav", "rb")},
    data={"model": "nemotron-asr", "sample_rate": 16000},
)
print(response.json()["text"])

import { readFile } from "node:fs/promises";

const form = new FormData();
form.append("file", new Blob([await readFile("call.wav")]), "call.wav");
form.append("model", "nemotron-asr");
form.append("sample_rate", "16000");

const response = await fetch(
  "https://api.withhopper.com/v1/audio/transcriptions",
  {
    method: "POST",
    headers: { Authorization: `Bearer ${process.env.HOPPER_API_KEY}` },
    body: form,
  },
);
const { text, words, duration_seconds } = await response.json();

curl https://api.withhopper.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $HOPPER_API_KEY" \
  -F file=@call.wav \
  -F model=nemotron-asr \
  -F sample_rate=16000

The response carries the transcript, one entry per word with its start and end offset in seconds, and the duration of the audio.

{
  "text": "thanks for calling, how can I help",
  "words": [{ "word": "thanks", "start": 0.12, "end": 0.34 }],
  "duration_seconds": 12.345
}

Stream live audio

wss://api.withhopper.com/stt/websocket transcribes audio as it arrives. Authenticate with the Authorization header, or with the api_key query parameter from clients that cannot set headers.

api_key (string, optional) — Your key, when no Authorization header is sent.
model (string, optional, default nemotron-asr) — STT model id.
sample_rate (integer, optional, default 16000) — One of 8000, 16000, 22050, 24000, 44100, 48000.
turn_detection (string, optional, default balanced) — balanced, patient to wait longer before ending a turn, or responsive to end it sooner.

The server sends {"type": "Ready"} once, then you send binary PCM16 mono frames and receive {"text", "is_final", "words"} events — is_final marks the end of a turn. Send the text frame END to flush; the server replies with END when every final has been delivered.

import asyncio
import json
import os

import websockets

URL = (
    "wss://api.withhopper.com/stt/websocket"
    f"?api_key={os.environ['HOPPER_API_KEY']}"
    "&model=nemotron-asr&sample_rate=16000&turn_detection=balanced"
)


async def main():
    pcm = open("call.pcm", "rb").read()  # raw PCM16 mono at 16 kHz
    frame = 3200  # 100 ms: 16000 samples/s x 2 bytes x 0.1 s

    async with websockets.connect(URL) as ws:
        json.loads(await ws.recv())  # {"type": "Ready"}

        async def send():
            for i in range(0, len(pcm), frame):
                await ws.send(pcm[i : i + frame])
                await asyncio.sleep(0.1)  # real-time pacing
            await ws.send("END")

        async def receive():
            async for message in ws:
                if message == "END":
                    return
                event = json.loads(message)
                print("final" if event["is_final"] else "partial", event["text"])

        await asyncio.gather(send(), receive())


asyncio.run(main())

A session is billed on the audio bytes it receives, settled every 60 seconds and at close. If the balance reaches zero mid-session the server closes the socket with code 1008. Error codes are listed in Errors.

​Transcribe a file

​Stream live audio

Transcribe a file

Stream live audio