API Reference

Speech To Text · WebSocket

WSSwss://stream.shabd.tech/v1/speech-to-text

Connection headers

x-api-keystringrequired
API key for authentication.

Message flow

Outgoing Message (↑): The client sends metadata first then sends audio data in bytes.
Incoming Message (↓): The server responds json with requestId, status, transcript, language, chunk, completed, mode.

Send Metadata (↑):

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "language": "tamil",  "sampleRate": 16000,  "projectId": "<your-project-id-here>"}

Send Audio Data (↑):

  Raw PCM 16-bit Audio Data (in Bytes)

Initial messageapplication/json

requestIdstringrequired
Unique identifier for the request
languagestringrequired
Language of the speech, or "auto" to detect it
sampleRatenumber or nulloptional
Sample Rate of the speech
Default:
16000
projectIdstring or nulloptional
An optional ID representing the project.

Server messages

101The server streams transcribed text along with status and progress updates.

Receive Transcription (↓):

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம் இனிய நாள்!",  "chunk": 1,  "completed": false,  "mode": "stt"}

When the transcription is complete:

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "",  "chunk": 2,  "completed": true,  "mode": "stt"}

Messages

Message Type	Example	Description
Send (↑)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "language": "tamil", "sampleRate": 16000, "projectId": "<your-project-id-here>" }`	The client sends parameters for getting transcription from Audio.
Send (↑)	`Raw PCM 16-bit Audio Data (in Bytes)`	The client sends audio data after sending metadata.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "வணக்கம் இனிய நாள்!", "chunk": 1, "completed": false, "mode": "stt" }`	The server sends transcription along with status and progress updates.
Receive (↓)	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": true, "transcript": "", "chunk": 2, "completed": true, "mode": "stt" }`	The server sends completed message.

Example response

{  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "வணக்கம் இனிய நாள்!",  "chunk": 1,  "completed": false,  "mode": "stt"} {  "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02",  "status": true,  "transcript": "",  "chunk": 2,  "completed": true,  "mode": "stt"}

Request

1from websockets.sync.client import connect2from scipy.io import wavfile3import json4 5api_key = "your_api_key"6 7url = f'wss://stream.shabd.tech/v1/speech-to-text'8headers = {"x-api-key": api_key}9 10sampleRate, audio_data = wavfile.read("path_to_your_audio_file.wav")11audio_data_bytes = audio_data.tobytes() # Ensure your audio is Raw PCM 16 bit Format12 13metadata = {14    "requestId": "your_uuid_here",15    "language": "tamil",16    "sampleRate": sampleRate,17    "projectId": "your_project_id_here"18}19 20with connect(url, additional_headers=headers) as ws:21    ws.send(json.dumps(metadata))22    ws.send(audio_data_bytes)23 24    for message in ws:25        response = json.loads(message)26        27        status = response.get("status", False)28        transcript = response.get("transcript", "")29        chunk = response.get("chunk") 30        completed = response.get("completed", False)31        32        if not status:33            print("Request Failed: ",response.get('message', 'Unknown Error'))34            break35        if transcript:36            print(f"Transcript {chunk}: {transcript}") # chunk id and transcript37        if completed:38            print("Transcription completed")39            break

1const WebSocket = require('ws');2const fs = require('fs');3 4const api_key = "your_api_key";5const url = `wss://stream.shabd.tech/v1/speech-to-text`; 6const headers = {7  "x-api-key": api_key8};9 10const audioFilePath = 'path_to_your_audio_file.wav';11const audioData = fs.readFileSync(audioFilePath);12const sampleRate = audioData.readUInt32LE(24);  // Extract sample rate from audio file13const pcmData = audioData.slice(44); // Sending raw PCM Audio14 15const metadata = {16  requestId: "your_uuid_here",17  language: "tamil",18  sampleRate: sampleRate,19  projectId: "your_project_id_here"20};21 22// Initialize WebSocket connection23const ws = new WebSocket(url, {24  headers: headers25});26 27ws.on('open', () => {28  ws.send(JSON.stringify(metadata));  29  ws.send(pcmData);               30});31 32ws.on('message', (data) => {33  if (Buffer.isBuffer(data)) {34    try {35      const stringData = data.toString('utf8');36      if (stringData && stringData.startsWith("{") && stringData.endsWith("}")) {37        const response = JSON.parse(stringData);38        39        status = response.status;40        transcript = response.transcript;41        chunk = response.chunk;42        completed = response.completed;43 44        if (!status) 45          console.log("Request Failed: ", response.message || 'Unknown Error');46  47        if (transcript) 48          console.log(`Transcript ${chunk}: ${transcript}`);49        50        if (completed)  {51            console.log("Transcription completed");52            ws.close();53        }54 55      } 56    } catch (err) {57      console.log("Error processing buffer: ", err);58    }59  } else {60    console.log("Unexpected data type received");61  }62});63 64ws.on('error', (err) => {65  console.error("WebSocket Error: ", err);66});67 68ws.on('close', () => {69  console.log("WebSocket connection closed");70});