API Reference

Speech To Speech · HTTP Stream

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

Transcribes speech, translates it, then synthesizes the translation to audio — streamed as NDJSON (stt, ttt, then tts 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 and synthesize into
Example:
tamil
genderstringrequired
Voice gender for synthesis ("male" or "female")
Example:
male
sampleRateintegeroptional
Output audio sample rate in Hz
Example:
48000
inputSampleRatenumberoptional
Sample rate of the input audio in Hz (default 16000)
Example:
16000
speedstringoptional
Speed of speech (fast, normal, or slow). Default is normal if not specified.
Example:
normal
formatstringoptional
Output audio format (default "wav")
Example:
wav
stylestringoptional
Translation style ("conversational" or "formal")
Allowed:
conversational
formal
Default:
conversational
wordStreambooleanoptional
When true, each tts line carries the word its audio speaks in the word field. When false or omitted, word is present but empty.
Default:
false
Example:
true
projectIdstringoptional
Optional project identifier
Example:
<your-project-id-here>

Responses

200NDJSON stream — one JSON object per line, newline-separated.

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": "வணக்கம் உலகம்" }`
tts	`{ "requestId": "a216e43a-9d81-444c-a9ae-3c1e400fcb02", "mode": "tts", "status": true, "completed": false, "chunk": 1, "audio": "<base64 PCM-16>", "word": "வணக்கம்", "sampleRate": 48000, "format": "pcm" }`

Transcript, translation and audio interleave per segment. word holds the word that line's audio speaks, populated only when wordStream: true was requested; otherwise it is an empty string. Every audio-bearing tts line is completed: false; a single terminal tts line with empty audio and completed: true marks the end of 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." }

Body: application/x-ndjson

Example response

"string"

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-speech/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 "gender=male" \7 -F "sampleRate=48000" \8 -F "file=@path_to_audio_file.wav" \9 -N

1import requests2import json3import base644import wave5 6url = "https://api.shabd.tech/v1/speech-to-speech/stream"7headers = {8    "x-api-key": "<your-api-key>",9    "x-request-id": "<your-uuid-here>"10}11files = {"file": open("path_to_audio_file.wav", "rb")}12sample_rate = 4800013data = {14    "sourceLanguage": "english",15    "targetLanguage": "tamil",16    "gender": "male",17    "sampleRate": sample_rate18}19 20with requests.post(url, headers=headers, files=files, data=data, stream=True) as r:21    r.raise_for_status()22    for line in r.iter_lines():23        if not line:24            continue25        msg = json.loads(line.decode("utf-8"))26        status = msg.get("status")27        transcript = msg.get("transcript")28        translation = msg.get("translation")29        audio = msg.get("audio")30        chunk = msg.get("chunk")31        completed = msg.get("completed")32        mode = msg.get("mode")33 34        if not status:35            print("Error:", msg.get("message"))36            break37        if transcript:38            print(f"Transcript {chunk}: {transcript}")39        if completed and mode == "stt":40            print("Transcription completed")41        if translation:42            print(f"Translation {chunk}: {translation}")43        if completed and mode == "ttt":44            print("Translation completed")45        if audio:46            pcm = base64.b64decode(audio)47            with wave.open(f"SynthesizedAudio_Chunk{chunk}.wav", "wb") as wf:48                wf.setnchannels(1)49                wf.setsampwidth(2)50                wf.setframerate(sample_rate)51                wf.writeframes(pcm)52            print(f"Saved audio chunk {chunk}: {len(pcm)} bytes")53        if completed and mode == "tts":54            print("Audio synthesis completed")55            break

1// npm install form-data node-fetch2const fs = require("fs");3const FormData = require("form-data");4const fetch = require("node-fetch");5const wav = require("wav");6 7const url = "https://api.shabd.tech/v1/speech-to-speech/stream";8const sampleRate = 48000;9const form = new FormData();10form.append("sourceLanguage", "english");11form.append("targetLanguage", "tamil");12form.append("gender", "male");13form.append("sampleRate", String(sampleRate));14form.append("file", fs.createReadStream("path_to_audio_file.wav"));15 16const response = await fetch(url, {17    method: "POST",18    headers: {19        "x-api-key": "<your-api-key>",20        "x-request-id": "<your-uuid-here>",21        ...form.getHeaders()22    },23    body: form24});25 26let buffer = "";27for await (const value of response.body) {28    buffer += value.toString("utf-8");29    const lines = buffer.split("\n");30    buffer = lines.pop();31    for (const line of lines) {32        if (!line.trim()) continue;33        const msg = JSON.parse(line);34        const { status, transcript, translation, audio, chunk, completed, mode } = msg;35 36        if (!status) { console.error("Error:", msg.message); break; }37        if (transcript) console.log(`Transcript ${chunk}: ${transcript}`);38        if (completed && mode === "stt") console.log("Transcription completed");39        if (translation) console.log(`Translation ${chunk}: ${translation}`);40        if (completed && mode === "ttt") console.log("Translation completed");41        if (audio) {42            const writer = new wav.Writer({ channels: 1, sampleRate, bitDepth: 16 });43            writer.pipe(fs.createWriteStream(`SynthesizedAudio_Chunk${chunk}.wav`));44            writer.write(Buffer.from(audio, "base64"));45            writer.end();46            console.log(`Saved audio chunk ${chunk}`);47        }48        if (completed && mode === "tts") { console.log("Audio synthesis completed"); break; }49    }50}

Speech To Speech · HTTP Stream

Headers

Request bodymultipart/form-data

Responses

Bodyapplication/json

Bodyapplication/json

Bodyapplication/json

Bodyapplication/json