Build Voice AI in Python: Complete Speech-to-Text Developer Guide (2026)

curl -H "Authorization: Bearer $SMALLEST_API_KEY" \

  https://waves-api.smallest.ai/api/v1/lightning-v3.1/get_voices

Authorization: Bearer <YOUR_API_KEY>

POST https://waves-api.smallest.ai/api/v1/pulse/get_text

curl --request POST \

  --url "https://waves-api.smallest.ai/api/v1/pulse/get_text?model=pulse&language=en&diarize=true&word_timestamps=true&emotion_detection=true" \

  --header "Authorization: Bearer $SMALLEST_API_KEY" \

  --header "Content-Type: audio/wav" \

  --data-binary "@/path/to/audio.wav"

import os

import requests



API_KEY = os.getenv("SMALLEST_API_KEY")

audio_file = "meeting_recording.wav"



url = "https://waves-api.smallest.ai/api/v1/pulse/get_text"

params = {

    "model": "pulse",

    "language": "en",

    "word_timestamps": "true",

    "diarize": "true",

    "emotion_detection": "true"

}

headers = {

    "Authorization": f"Bearer {API_KEY}",

    "Content-Type": "audio/wav"

}



with open(audio_file, "rb") as f:

    audio_data = f.read()



response = requests.post(url, params=params, headers=headers, data=audio_data)

result = response.json()



# Print transcription

print("Transcription:", result.get("transcription"))



# Print word-level details with speaker info

for word in result.get("words", []):

    speaker = word.get("speaker", "N/A")

    print(f"  [Speaker {speaker}] [{word['start']:.2f}s - {word['end']:.2f}s] {word['word']}")



# Check emotions

if "emotions" in result:

    print("\nEmotions detected:")

    for emotion, score in result["emotions"].items():

        if score > 0.1:

            print(f"  {emotion}: {score:.1%}")

const fs = require('fs');

const axios = require('axios');



const API_KEY = process.env.SMALLEST_API_KEY;

const audioFile = 'meeting_recording.wav';



const url = 'https://waves-api.smallest.ai/api/v1/pulse/get_text';

const params = new URLSearchParams({

  model: 'pulse',

  language: 'en',

  word_timestamps: 'true',

  diarize: 'true',

  emotion_detection: 'true'

});



const audioData = fs.readFileSync(audioFile);



axios.post(`${url}?${params}`, audioData, {

  headers: {

    'Authorization': `Bearer ${API_KEY}`,

    'Content-Type': 'audio/wav'

  }

})

.then(res => {

  console.log('Transcription:', res.data.transcription);



  // Print words with speaker info

  res.data.words?.forEach(word => {

    console.log(`  [Speaker ${word.speaker}] [${word.start}s - ${word.end}s] ${word.word}`);

  });

})

.catch(err => {

  console.error('Error:', err.response?.data || err.message);

});

{

  "status": "success",

  "transcription": "Hello, this is a test transcription.",

  "words": [

    {"start": 0.0, "end": 0.88, "word": "Hello,", "confidence": 0.82, "speaker": 0, "speaker_confidence": 0.61},

    {"start": 0.88, "end": 1.04, "word": "this", "confidence": 1.0, "speaker": 0, "speaker_confidence": 0.76},

    {"start": 1.04, "end": 1.20, "word": "is", "confidence": 1.0, "speaker": 0, "speaker_confidence": 0.99},

    {"start": 1.20, "end": 1.36, "word": "a", "confidence": 1.0, "speaker": 0, "speaker_confidence": 0.99},

    {"start": 1.36, "end": 1.68, "word": "test", "confidence": 0.99, "speaker": 0, "speaker_confidence": 0.99},

    {"start": 1.68, "end": 2.16, "word": "transcription.", "confidence": 0.99, "speaker": 0, "speaker_confidence": 0.99}

  ],

  "utterances": [

    {"start": 0.0, "end": 2.16, "text": "Hello, this is a test transcription.", "speaker": 0}

  ],

  "age": "adult",

  "gender": "female",

  "emotions": {

    "happiness": 0.28,

    "sadness": 0.0,

    "anger": 0.0,

    "fear": 0.0,

    "disgust": 0.0

  },

  "metadata": {

    "duration": 1.97,

    "fileSize": 63236

  }

}

wss://waves-api.smallest.ai/api/v1/pulse/get_text

import asyncio

import json

import os

import numpy as np

import websockets

import librosa

from urllib.parse import urlencode



WS_URL = "wss://waves-api.smallest.ai/api/v1/pulse/get_text"



# Configurable features

LANGUAGE = "en"

ENCODING = "linear16"

SAMPLE_RATE = 16000

WORD_TIMESTAMPS = False

FULL_TRANSCRIPT = True

SENTENCE_TIMESTAMPS = False

DIARIZE = False

REDACT_PII = False

REDACT_PCI = False



async def transcribe(audio_file: str, api_key: str):

    params = {

        "language": LANGUAGE,

        "encoding": ENCODING,

        "sample_rate": SAMPLE_RATE,

        "word_timestamps": str(WORD_TIMESTAMPS).lower(),

        "full_transcript": str(FULL_TRANSCRIPT).lower(),

        "sentence_timestamps": str(SENTENCE_TIMESTAMPS).lower(),

        "diarize": str(DIARIZE).lower(),

        "redact_pii": str(REDACT_PII).lower(),

        "redact_pci": str(REDACT_PCI).lower(),

    }



    url = f"{WS_URL}?{urlencode(params)}"

    headers = {"Authorization": f"Bearer {api_key}"}



    # Load audio with librosa (handles any format)

    audio, _ = librosa.load(audio_file, sr=SAMPLE_RATE, mono=True)

    chunk_duration = 0.1  # 100ms chunks

    chunk_size = int(chunk_duration * SAMPLE_RATE)



    async with websockets.connect(url, additional_headers=headers) as ws:

        print("✅ Connected to Pulse STT WebSocket")



        async def send_audio():

            for i in range(0, len(audio), chunk_size):

                chunk = audio[i:i + chunk_size]

                pcm16 = (chunk * 32768.0).astype(np.int16).tobytes()

                await ws.send(pcm16)

                await asyncio.sleep(chunk_duration)

            await ws.send(json.dumps({"type": "end"}))

            print("📤 Sent end signal")



        async def receive_responses():

            async for message in ws:

                result = json.loads(message)



                if result.get("is_final"):

                    print(f"✓ {result.get('transcript')}")



                    if result.get("is_last"):

                        if result.get("full_transcript"):

                            print(f"\n{'='*60}")

                            print("FULL TRANSCRIPT")

                            print(f"{'='*60}")

                            print(result.get("full_transcript"))

                        break



        await asyncio.gather(send_audio(), receive_responses())



# Usage

if __name__ == "__main__":

    api_key = os.environ.get("SMALLEST_API_KEY")

    asyncio.run(transcribe("recording.wav", api_key))

pip install websockets librosa numpy

export SMALLEST_API_KEY="your-api-key"

python transcribe.py recording.wav

const fs = require("fs");

const WebSocket = require("ws");

const wav = require("wav");



const WS_URL = "wss://waves-api.smallest.ai/api/v1/pulse/get_text";



// Configurable features

const LANGUAGE = "en";

const ENCODING = "linear16";

const SAMPLE_RATE = 16000;

const WORD_TIMESTAMPS = false;

const FULL_TRANSCRIPT = true;

const DIARIZE = false;

const REDACT_PII = false;

const REDACT_PCI = false;



async function loadAudio(audioFile) {

  return new Promise((resolve, reject) => {

    const reader = new wav.Reader();

    const chunks = [];



    reader.on("format", (format) => {

      reader.on("data", (chunk) => chunks.push(chunk));

      reader.on("end", () => {

        const buffer = Buffer.concat(chunks);

        const samples = new Int16Array(buffer.buffer, buffer.byteOffset, buffer.length / 2);

        resolve(samples);

      });

    });



    reader.on("error", reject);

    fs.createReadStream(audioFile).pipe(reader);

  });

}



async function transcribe(audioFile, apiKey) {

  const params = new URLSearchParams({

    language: LANGUAGE,

    encoding: ENCODING,

    sample_rate: SAMPLE_RATE,

    word_timestamps: WORD_TIMESTAMPS,

    full_transcript: FULL_TRANSCRIPT,

    diarize: DIARIZE,

    redact_pii: REDACT_PII,

    redact_pci: REDACT_PCI,

  });



  const url = `${WS_URL}?${params}`;

  const audio = await loadAudio(audioFile);

  const chunkDuration = 0.1; // 100ms

  const chunkSize = Math.floor(chunkDuration * SAMPLE_RATE);



  return new Promise((resolve, reject) => {

    const ws = new WebSocket(url, {

      headers: { Authorization: `Bearer ${apiKey}` },

    });



    ws.on("open", async () => {

      console.log("✅ Connected to Pulse STT WebSocket");



      for (let i = 0; i < audio.length; i += chunkSize) {

        const chunk = audio.slice(i, i + chunkSize);

        ws.send(Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength));

        await new Promise((r) => setTimeout(r, chunkDuration * 1000));

      }

      ws.send(JSON.stringify({ type: "end" }));

      console.log("📤 Sent end signal");

    });



    ws.on("message", (data) => {

      const result = JSON.parse(data.toString());



      if (result.is_final) {

        console.log(`✓ ${result.transcript}`);



        if (result.is_last) {

          if (result.full_transcript) {

            console.log("\n" + "=".repeat(60));

            console.log("FULL TRANSCRIPT");

            console.log("=".repeat(60));

            console.log(result.full_transcript);

          }

          ws.close();

        }

      }

    });



    ws.on("close", resolve);

    ws.on("error", reject);

  });

}



// Usage

const apiKey = process.env.SMALLEST_API_KEY;

transcribe("recording.wav", apiKey).then(() => console.log("Done!"));

npm install ws wav

export SMALLEST_API_KEY="your-api-key"

node transcribe.js recording.wav

{

  "session_id": "sess_12345abcde",

  "transcript": "Hello, how are you?",

  "full_transcript": "Hello, how are you?",

  "is_final": true,

  "is_last": false,

  "language": "en",

  "words": [

    {"word": "Hello,", "start": 0.0, "end": 0.5, "confidence": 0.98, "speaker": 0},

    {"word": "how", "start": 0.5, "end": 0.7, "confidence": 0.99, "speaker": 0},

    {"word": "are", "start": 0.7, "end": 0.9, "confidence": 0.97, "speaker": 0},

    {"word": "you?", "start": 0.9, "end": 1.2, "confidence": 0.99, "speaker": 0}

  ]

}

params = {"model": "pulse", "language": "en", "diarize": "true"}

{

  "words": [

    {"word": "Hello", "speaker": 0, "speaker_confidence": 0.95},

    {"word": "Hi", "speaker": 1, "speaker_confidence": 0.92}

  ],

  "utterances": [

    {"text": "Hello, how can I help?", "speaker": 0},

    {"text": "I have a question.", "speaker": 1}

  ]

}

{

  "emotions": {

    "happiness": 0.28,

    "sadness": 0.0,

    "anger": 0.0,

    "fear": 0.0,

    "disgust": 0.0

  }

}

{

  "transcript": "My credit card is [CREDITCARD_1] and SSN is [SSN_1]",

  "redacted_entities": ["[CREDITCARD_1]", "[SSN_1]"]

}

{

  "age": "adult",

  "gender": "female"

}

try:

    response = requests.post(url, params=params, headers=headers, data=audio_data, timeout=120)

    response.raise_for_status()

except requests.exceptions.HTTPError as e:

    if e.response.status_code == 429:

        # Rate limited - implement exponential backoff

        time.sleep(2 ** retry_count)

    elif e.response.status_code == 401:

        # Invalid API key

        raise ValueError("Invalid API key")

cd demo-app

npm install

echo 'SMALLEST_API_KEY=your-api-key' > .env.local

npm run dev:all

Browser → WebSocket Proxy (3001) → Pulse STT (wss://waves-api.smallest.ai)

Browser → Next.js API (3000) → Pulse STT (REST API)

demo-app/

├── src/

│   └── app/

│       ├── api/

│       │   └── transcribe/

│       │       └── route.ts    # REST API for file upload

│       ├── page.tsx            # Main UI

│       └── layout.tsx

├── ws-server.js                # WebSocket proxy server

├── .env.local                  # Your API key (create this)

└── package.json