API Reference

Speech To Text Translate · HTTP Stream

POSThttps://api.shabd.tech/v1/speech-to-text-translate/stream

Transcribes speech and translates the transcript — streamed as NDJSON (stt lines, then ttt lines) over one chunked connection.

Headers

x-api-keystringrequired
API Key for authentication
Example:
<your-api-key>
Content-Typestringrequired
Content type of the request body
Example:
multipart/form-data
x-request-idstringrequired
Unique request ID in UUID format
Example:
550e8400-e29b-41d4-a716-446655440000

Request bodymultipart/form-data

filefileoptional
Audio file in WAV or PCM format. Optional when audioUrl is supplied.
audioUrlstringoptional
Public http(s) URL to fetch the audio from, as an alternative to uploading file. Exactly one of file or audioUrl is required; if both are sent the uploaded file wins. The URL must be publicly reachable and the downloaded audio is subject to the same size limit as an upload.
Example:
https://example.com/audio/sample.wav
sourceLanguagestringrequired
Language of the speech
Example:
english
targetLanguagestringrequired
Language to translate into
Example:
tamil
sampleRatenumberoptional
Sample rate of the audio in Hz (default 16000)
Example:
16000
projectIdstringoptional
Optional project identifier
Example:
<your-project-id-here>
stylestringoptional
Translation style ("conversational" or "formal")
Allowed:
conversational
formal
Default:
conversational

Responses

200NDJSON stream — one JSON object per line, newline-separated. Each transcript (stt) is followed by its translation (ttt), interleaved per segment.

mode	Example line
stt	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "mode": "stt", "status": true, "completed": false, "chunk": 1, "transcript": "hello world", "start": 0.0, "end": 2.0 }`
ttt	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "mode": "ttt", "status": true, "completed": false, "chunk": 1, "translation": "வணக்கம் உலகம்" }`

The stt stream ends with a completed: true line (empty transcript; start/end are null), and a final ttt completed: true line (empty translation) ends the stream. On failure a single error line is sent: { "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "status": false, "completed": false, "message": "An unexpected error occurred. Please try again later." }

Bodyapplication/x-ndjson

requestIdstringoptional
Example:
550e8400-e29b-41d4-a716-446655440000
modestringoptional
Example:
stt
statusbooleanoptional
Example:
true
completedbooleanoptional
Example:
false
chunkintegeroptional
Example:
1
transcriptstringoptional
Example:
hello world
translationstringoptional
Example:
வணக்கம் உலகம்
startnumber or nulloptional
Example:
0
endnumber or nulloptional
Example:
2

Example response

{  "requestId": "550e8400-e29b-41d4-a716-446655440000",  "mode": "stt",  "status": true,  "completed": false,  "chunk": 1,  "transcript": "hello world",  "translation": "வணக்கம் உலகம்",  "start": 0,  "end": 2}

400Bad Request
Bodyapplication/json
statusbooleanoptional
Example:
false
messagestringoptional
Example:
Invalid input parameters.
Example response
```
{  "status": false,  "message": "Invalid input parameters."}
```
401Unauthorized Access
Bodyapplication/json
statusbooleanoptional
Example:
false
messagestringoptional
Example:
Unauthorized access.
Example response
```
{  "status": false,  "message": "Unauthorized access."}
```
403Usage Limit Exceeded
Bodyapplication/json
statusbooleanoptional
Example:
false
messagestringoptional
Example:
Limit Exceeded
Example response
```
{  "status": false,  "message": "Limit Exceeded"}
```
500Internal server error
Bodyapplication/json
statusbooleanoptional
Example:
false
messagestringoptional
Example:
An unexpected error occurred. Please try again later.
Example response
```
{  "status": false,  "message": "An unexpected error occurred. Please try again later."}
```

Request

1curl -X POST "https://api.shabd.tech/v1/speech-to-text-translate/stream" \2 -H "x-api-key: <your-api-key>" \3 -H "x-request-id: <your-uuid-here>" \4 -F "sourceLanguage=english" \5 -F "targetLanguage=tamil" \6 -F "sampleRate=16000" \7 -F "file=@path_to_audio_file.wav" \8 -N

1import requests2import json3 4url = "https://api.shabd.tech/v1/speech-to-text-translate/stream"5headers = {6    "x-api-key": "<your-api-key>",7    "x-request-id": "<your-uuid-here>"8}9files = {"file": open("path_to_audio_file.wav", "rb")}10data = {"sourceLanguage": "english", "targetLanguage": "tamil", "sampleRate": 16000}11 12with requests.post(url, headers=headers, files=files, data=data, stream=True) as r:13    r.raise_for_status()14    for line in r.iter_lines():15        if not line:16            continue17        msg = json.loads(line.decode("utf-8"))18        status = msg.get("status")19        transcript = msg.get("transcript")20        translation = msg.get("translation")21        chunk = msg.get("chunk")22        completed = msg.get("completed")23        mode = msg.get("mode")24 25        if not status:26            print("Error:", msg.get("message"))27            break28        if transcript:29            print(f"Transcript {chunk}: {transcript}")30        if completed and mode == "stt":31            print("Transcription completed")32        if translation:33            print(f"Translation {chunk}: {translation}")34        if completed and mode == "ttt":35            print("Translation completed")36            break

1// npm install form-data node-fetch2const fs = require("fs");3const FormData = require("form-data");4const fetch = require("node-fetch");5 6const url = "https://api.shabd.tech/v1/speech-to-text-translate/stream";7const form = new FormData();8form.append("sourceLanguage", "english");9form.append("targetLanguage", "tamil");10form.append("sampleRate", "16000");11form.append("file", fs.createReadStream("path_to_audio_file.wav"));12 13const response = await fetch(url, {14    method: "POST",15    headers: {16        "x-api-key": "<your-api-key>",17        "x-request-id": "<your-uuid-here>",18        ...form.getHeaders()19    },20    body: form21});22 23const reader = response.body.getReader();24const decoder = new TextDecoder();25let buffer = "";26while (true) {27    const { value, done } = await reader.read();28    if (done) break;29    buffer += decoder.decode(value, { stream: true });30    const lines = buffer.split("\n");31    buffer = lines.pop();32    for (const line of lines) {33        if (!line.trim()) continue;34        const msg = JSON.parse(line);35        const { status, transcript, translation, chunk, completed, mode } = msg;36 37        if (!status) { console.error("Error:", msg.message); break; }38        if (transcript) console.log(`Transcript ${chunk}: ${transcript}`);39        if (completed && mode === "stt") console.log("Transcription completed");40        if (translation) console.log(`Translation ${chunk}: ${translation}`);41        if (completed && mode === "ttt") { console.log("Translation completed"); break; }42    }43}

Speech To Text Translate · HTTP Stream

Headers

Request bodymultipart/form-data

Responses

Bodyapplication/x-ndjson

Bodyapplication/json

Bodyapplication/json

Bodyapplication/json

Bodyapplication/json