Voice API

How It Works

POST /api/v1/voice

Buffered voice query. Accepts multipart audio, returns a complete MP3 file as the response body (audio/mpeg).

Best for: mobile apps, IVR systems, any client that plays audio after full download.

POST /api/v1/voice/stream

Streaming voice query (SSE). Same multipart input, but the response is a text/event-stream that emits audio chunks as they are generated — sub-200ms time-to-first-audio on the Jarvis tier.

Best for: real-time voice assistants, conversational UIs, and any client that can play audio progressively.

Authenticate with your Vedika API key using either method:

Authorization: Bearer vk_live_your_api_key

or

x-api-key: vk_live_your_api_key

Content-Type: multipart/form-data

Each tier balances cost, latency, and audio quality. If tier is omitted, Vedika auto-selects based on the detected language.

All costs shown are customer price (raw provider cost × 4.0 markup). The exact cost per call is returned in the response metadata. LLM inference cost is billed separately on top of voice STT+TTS cost.

Success (audio available)

Content-Type: audio/mpeg
The response body is raw MP3 binary. Save it directly as an .mp3 file or pipe it to an audio player.

Response Headers

X-Vedika-Voice-Meta (decoded)

{
  "transcription": "What does my chart say about career?",
  "language": "en",
  "tier": "vedika-voice-premium",
  "tierSource": "auto",
  "processingMs": 4200,
  "sttDurationSec": 3.2,
  "ttsDurationSec": 12.5,
  "engine": "vedika-voice",
  "billing": {
    "rawCostUsd": 0.003200,
    "markupFactor": 4.0,
    "customerCostUsd": 0.012800
  },
  "totalPriceUsd": 0.012800
}

Fallback (TTS failed)

If speech synthesis fails, the endpoint degrades gracefully to a JSON response with audio: null and the text answer:

{
  "success": true,
  "audio": null,
  "response": "Your chart shows a strong period for career growth...",
  "transcription": "What does my chart say about career?",
  "language": "en",
  "tier": "vedika-voice-premium",
  "billing": { ... }
}

Content-Type: text/event-stream (Server-Sent Events). The stream emits the following event types in order:

data: {"transcription":"What about my marriage?","language":"hi","tier":"vedika-voice-jarvis","sttMs":820}

data: {"delta":"Your Venus is exalted in Pisces...","done":true}

data: {"bytesBase64":"//uQxAAAAAANIAAAAAExBTUUzLjEw...","seq":0}
data: {"bytesBase64":"AAAAIGZ0eXBpc29t...","seq":1}
data: {"bytesBase64":"...","seq":2}

data: {"processingMs":2400,"sttDurationSec":1.2,"ttsDurationSec":8.5,"totalChunks":14,"billing":{"rawCostUsd":0.004100,"markupFactor":4.0,"customerCostUsd":0.016400}}

data: {"code":"STT_FAILED","message":"Could not transcribe the submitted audio."}

On the streaming endpoint, errors are emitted as SSE event: error instead of HTTP status codes (since the stream starts with HTTP 200). Check the code field in the error event data.

cURL

curl -X POST https://api.vedika.io/api/v1/voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "audio=@question.webm" \
  -F 'birthDetails={"datetime":"1992-08-20T14:30:00","latitude":12.97,"longitude":77.59,"timezone":"Asia/Kolkata"}' \
  -F "language=hi" \
  -F "speed=fast" \
  -F "tier=cheap-hi" \
  --output response.mp3

The --output flag saves the MP3 binary to a file. To also read the metadata header, add -D headers.txt.

JavaScript (Browser / Node.js)

const form = new FormData();
form.append('audio', audioBlob, 'question.webm');
form.append('birthDetails', JSON.stringify({
  datetime: '1992-08-20T14:30:00',
  latitude: 12.97,
  longitude: 77.59,
  timezone: 'Asia/Kolkata'
}));
form.append('language', 'hi');
form.append('speed', 'fast');
form.append('tier', 'cheap-hi');

const res = await fetch('https://api.vedika.io/api/v1/voice', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: form
});

// Play the audio
const audioBuffer = await res.arrayBuffer();
const audio = new Audio(URL.createObjectURL(
  new Blob([audioBuffer], { type: 'audio/mpeg' })
));
audio.play();

// Read metadata from header
const meta = JSON.parse(atob(
  res.headers.get('X-Vedika-Voice-Meta')
));
console.log('Transcription:', meta.transcription);
console.log('Cost:', meta.billing.customerCostUsd);

const form = new FormData();
form.append('audio', audioBlob, 'question.webm');
form.append('birthDetails', JSON.stringify({
  datetime: '1992-08-20T14:30:00',
  latitude: 12.97,
  longitude: 77.59,
  timezone: 'Asia/Kolkata'
}));
form.append('tier', 'jarvis');
form.append('speed', 'fast');

const res = await fetch('https://api.vedika.io/api/v1/voice/stream', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
  body: form
});

const reader = res.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // Parse SSE events
  const lines = buffer.split('\n');
  buffer = lines.pop(); // keep incomplete line

  let eventType = '';
  for (const line of lines) {
    if (line.startsWith('event: ')) {
      eventType = line.slice(7);
    } else if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));

      switch (eventType) {
        case 'started':
          console.log('Transcribed:', data.transcription);
          break;
        case 'text':
          console.log('Answer:', data.delta);
          break;
        case 'audio':
          // Decode base64 and queue for playback
          const bytes = Uint8Array.from(
            atob(data.bytesBase64), c => c.charCodeAt(0)
          );
          // Append to MediaSource or Web Audio buffer
          break;
        case 'completed':
          console.log('Done in', data.processingMs, 'ms');
          break;
        case 'error':
          console.error('Voice error:', data.code);
          break;
      }
    }
  }
}

Python

import requests
import base64
import json

url = "https://api.vedika.io/api/v1/voice"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

birth = json.dumps({
    "datetime": "1992-08-20T14:30:00",
    "latitude": 12.97,
    "longitude": 77.59,
    "timezone": "Asia/Kolkata"
})

with open("question.webm", "rb") as f:
    files = {"audio": ("question.webm", f, "audio/webm")}
    data = {
        "birthDetails": birth,
        "language": "hi",
        "speed": "fast",
        "tier": "cheap-hi"
    }
    resp = requests.post(url, headers=headers, files=files, data=data)

if resp.status_code == 200:
    # Save audio
    with open("response.mp3", "wb") as out:
        out.write(resp.content)

    # Read metadata
    meta_b64 = resp.headers.get("X-Vedika-Voice-Meta", "")
    if meta_b64:
        meta = json.loads(base64.b64decode(meta_b64))
        print("Transcription:", meta["transcription"])
        print("Cost: $", meta["billing"]["customerCostUsd"])
else:
    print("Error:", resp.status_code, resp.json())

import requests
import json
import base64

url = "https://api.vedika.io/api/v1/voice/stream"
headers = {"Authorization": "Bearer YOUR_API_KEY"}

with open("question.webm", "rb") as f:
    files = {"audio": ("question.webm", f, "audio/webm")}
    data = {"tier": "jarvis", "speed": "fast"}
    resp = requests.post(url, headers=headers, files=files,
                         data=data, stream=True)

audio_chunks = []

for line in resp.iter_lines(decode_unicode=True):
    if not line:
        continue
    if line.startswith("event: "):
        event_type = line[7:]
    elif line.startswith("data: "):
        payload = json.loads(line[6:])

        if event_type == "started":
            print("Transcribed:", payload["transcription"])
        elif event_type == "text":
            print("Answer:", payload["delta"][:100], "...")
        elif event_type == "audio":
            chunk = base64.b64decode(payload["bytesBase64"])
            audio_chunks.append(chunk)
        elif event_type == "completed":
            print(f"Done: {payload['processingMs']}ms, "
                  f"{payload['totalChunks']} chunks")
        elif event_type == "error":
            print("Error:", payload["code"], payload.get("message"))

# Save assembled audio
with open("response.mp3", "wb") as f:
    f.write(b"".join(audio_chunks))
print(f"Saved {len(audio_chunks)} chunks to response.mp3")

Speech recognition supports 50+ languages. If the language hint is omitted, the system auto-detects from the audio. For best accuracy with short clips, provide the language hint.

Voice calls are billed from your wallet in two parts:

1. Voice cost (STT + TTS) — raw provider cost × 4.0 markup.
2. LLM cost — Vedika Intelligence inference cost (same pricing as the text /query endpoint).

Both costs are deducted from your wallet balance after the response is generated. The exact breakdown is returned in X-Vedika-Voice-Meta (buffered) or the completed SSE event (streaming).

Audio Quality

• Use WebM/Opus at 48kHz for best speech recognition accuracy at small file sizes.
• MP3 and WAV are fully supported but produce larger uploads.
• Keep recordings under 60 seconds for optimal response time.

Multi-turn Conversations

• Save the conversationId from the first response metadata and pass it in subsequent calls.
• The AI will reference prior questions and answers for contextual follow-ups.
• Birth details only need to be sent on the first call — they persist in the conversation.

Choosing a Tier

• High-volume B2C: Use cheap-hi (or signal=b2c) for the lowest cost per query.
• Premium experience: Use premium-hi (Hindi) or premium-en (English) for the most natural voice.
• Multi-language: Use premium-multi for Tamil, Telugu, Bengali, and other Indic languages.
• Real-time assistant: Use jarvis with the /voice/stream endpoint for sub-200ms time-to-first-audio.

Error Handling

• Always check for audio: null in buffered responses — it means TTS failed but the text answer is available.
• On the streaming endpoint, handle the error event gracefully and close the EventSource.
• If LLM_FAILED is returned, the transcription field contains the recognized text — retry via the text /query endpoint as a fallback.