Docs
AI Astrologer
AI Astrologers
AI Voice (Call)

POST + WSS · AI

AI Voice (Call)

Real-time AI voice astrologer over WebSocket. Audio streams in both directions — sub-second turn-taking, barge-in, multilingual, chart-grounded. Live transcripts stream alongside the audio for both the user and the astrologer, so you can render captions or build a chat log in parallel. Integration has two phases: one REST call to create the session, one WebSocket for the live conversation.

How it works

Phase 1 (REST) — POST birth data to /start (or /match-start for two charts). Server computes the Vedic chart, returns a session_id.
Phase 2 (WebSocket) — connect to wss://starsapi.com/voice-relay-v2, authenticate with the session_id, then exchange audio frames in real time.

The relay handles voice activity detection (VAD), turn-taking, barge-in, language detection, and billing events. Your client captures mic audio and plays back the astrologer’s audio — nothing else to manage.

Phase 1: Create session

Endpoint POST /api/v2/partner/ai/voice/start

Creates a voice session and computes the birth chart. Returns session_id to use in the WebSocket auth frame. Same birth-data fields as chat /start.

Available voice astrologers: guruji, love_guru, transit_expert.

Two-chart sessions

Endpoint POST /api/v2/partner/ai/voice/match-start

For compatibility voice calls. Same person1 / person2 body as chat /match-start. Returns a session_id with both charts loaded. Use person1_name and person2_name in the WebSocket greet frame instead of name.

Phase 2: WebSocket conversation

Relay wss://starsapi.com/voice-relay-v2

Connection flow

Connect to the relay URL.
Send an auth frame with session_id, api_key, name, and lang.
Wait for ready — session is bound, astrologer loaded.
Send greet to trigger the astrologer’s opening response.
Stream mic audio as audio.chunk frames. Play back assistant.audio frames.

Audio format

Same format in both directions: 24 kHz, mono, signed 16-bit little-endian PCM, base64-encoded in the JSON data field.

Frame reference

All frames are single-line JSON objects with a type field.

Client → Server

Type	Fields	Description
`auth`	`session_id`, `api_key`, `name`, `lang`	First frame. Binds the session to the WebSocket.
`greet`	`name`, `lang`	Triggers the astrologer’s opening response. For couples: `person1_name`, `person2_name`, `lang`.
`audio.chunk`	`data`	One mic chunk. Base64 PCM (24 kHz mono s16le). Send continuously while user speaks.
`interrupt`	—	Cancel the current assistant response. Send when `user.speech_started` arrives while playback is active.

Server → Client

Type	Fields	Description
`ready`	`astrologer`, `language`	Auth accepted, session bound.
`user.speech_started`	—	Server VAD detected the user is speaking.
`user.speech_stopped`	—	VAD detected end of user turn.
`user.transcript`	`text`	Transcript of what the user said.
`assistant.speech_started`	—	Astrologer is about to speak. Show speaking indicator.
`assistant.audio`	`data`	One chunk of astrologer audio. Base64 PCM. Queue and play in order.
`assistant.transcript`	`delta`	Incremental caption text for the current astrologer turn.
`assistant.done`	—	Astrologer finished speaking. Open mic for next turn.
`assistant.cancelled`	—	Barge-in acknowledged. Previous response stopped.
`billing.warning`	—	Wallet running low. Show a top-up nudge.
`billing.exhausted`	—	Wallet empty. Session ending — show top-up flow.
`error`	`code`, `message`	Recoverable or fatal error.

Barge-in

When user.speech_started arrives while you’re still playing assistant audio, stop playback immediately and send {"type":"interrupt"}. The relay replies with assistant.cancelled and starts processing the new user turn.

Billing

Voice sessions use a per-minute meter. An initial charge is debited when the connection is established, then recurring charges every 60 seconds while the session is active. Disconnecting stops the meter. The relay sends billing.warning when balance is getting low and billing.exhausted when the wallet is empty. No webhook wiring needed — handle them inline as WebSocket frames.

Integration checklist

POST to /start (or /match-start) with birth data → save session_id.
Connect to wss://starsapi.com/voice-relay-v2.
Send auth frame → wait for ready.
Send greet → play assistant.audio chunks, render assistant.transcript deltas.
Wait for assistant.done before opening mic (first turn only).
Capture mic at 24 kHz mono s16le, base64-encode, send as audio.chunk frames.
On user.speech_started during playback → stop audio, send interrupt.
Handle billing.warning / billing.exhausted to manage wallet state.

Errors

REST errors follow the same format as chat errors. WebSocket errors arrive as {"type":"error","code":"...","message":"..."} frames.

HTTP / WS	Code	Cause
400	`VALIDATION_ERROR`	Missing/invalid fields or astrologer not available for voice.
400	`MISSING_FIELD`	A required field is absent.
400	`INVALID_SESSION`	Session ID not found or expired.
401	`AUTH_MISSING_KEY`	No API key in request or auth frame.
402	`INSUFFICIENT_BALANCE`	Wallet balance too low to start.
WS	`billing.exhausted`	Wallet empty during session — connection closing.
WS	`error`	Fatal or recoverable error with `code` and `message`.

# Phase 1 — create the session (REST)
curl -X POST https://starsapi.com/api/v2/partner/ai/voice/start \
  -H "X-Api-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "astrologer": "guruji",
    "year": 1990, "month": 6, "day": 15,
    "hour": 14, "minute": 30,
    "timezone": "Asia/Kolkata",
    "latitude": 28.6139, "longitude": 77.2090,
    "name": "Ravi", "gender": "male",
    "preferred_language": "en"
  }'

# Returns: data.session_id
# Use this session_id in Phase 2 (WebSocket).
#
# Phase 2 requires a WebSocket client — see the
# JavaScript, Python, or Dart samples for the full
# connection flow with audio streaming.

const BASE  = "https://starsapi.com/api/v2/partner/ai/voice";
const RELAY = "wss://starsapi.com/voice-relay-v2";

// Phase 1 — REST: create the session
const r = await fetch(`${BASE}/start`, {
  method:  "POST",
  headers: { "X-Api-Key": API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    astrologer: "guruji",
    year: 1990, month: 6, day: 15, hour: 14, minute: 30,
    timezone: "Asia/Kolkata",
    latitude: 28.6139, longitude: 77.2090,
    name: "Ravi", gender: "male",
    preferred_language: "en",
  }),
}).then(r => r.json());

const sessionId = r.data.session_id;

// Phase 2 — WebSocket: real-time conversation
const ws = new WebSocket(RELAY);

ws.onopen = () => ws.send(JSON.stringify({
  type: "auth", session_id: sessionId, api_key: API_KEY,
  name: "Ravi", lang: "en",
}));

ws.onmessage = (e) => {
  const f = JSON.parse(e.data);
  switch (f.type) {
    case "ready":
      ws.send(JSON.stringify({ type: "greet", name: "Ravi", lang: "en" }));
      break;
    case "user.speech_started":
      if (assistantPlaying) ws.send(JSON.stringify({ type: "interrupt" }));
      break;
    case "user.transcript":      renderUserBubble(f.text); break;
    case "assistant.audio":      playPcmChunk(base64ToBytes(f.data)); break;
    case "assistant.transcript": appendCaption(f.delta); break;
    case "assistant.done":       enableMic(); break;
    case "billing.exhausted":    showTopUp(); break;
  }
};

// Send mic chunks (24kHz mono PCM s16le, base64)
function onMicChunk(int16Pcm) {
  ws.send(JSON.stringify({ type: "audio.chunk", data: bytesToBase64(int16Pcm) }));
}

import requests, json, base64
import websocket  # pip install websocket-client

BASE  = "https://starsapi.com/api/v2/partner/ai/voice"
RELAY = "wss://starsapi.com/voice-relay-v2"

# Phase 1 — REST: create the session
r = requests.post(f"{BASE}/start",
    headers={"X-Api-Key": API_KEY, "Content-Type": "application/json"},
    json={
        "astrologer": "guruji",
        "year": 1990, "month": 6, "day": 15,
        "hour": 14, "minute": 30, "timezone": "Asia/Kolkata",
        "latitude": 28.6139, "longitude": 77.2090,
        "name": "Ravi", "gender": "male",
        "preferred_language": "en",
    }).json()
session_id = r["data"]["session_id"]

# Phase 2 — WebSocket: real-time conversation
def on_open(ws):
    ws.send(json.dumps({
        "type": "auth", "session_id": session_id,
        "api_key": API_KEY, "name": "Ravi", "lang": "en",
    }))

def on_message(ws, raw):
    f = json.loads(raw)
    match f["type"]:
        case "ready":
            ws.send(json.dumps({"type": "greet", "name": "Ravi", "lang": "en"}))
        case "user.speech_started":
            if assistant_playing:
                ws.send(json.dumps({"type": "interrupt"}))
        case "assistant.audio":
            play_pcm_chunk(base64.b64decode(f["data"]))
        case "assistant.transcript":
            append_caption(f["delta"])
        case "assistant.done":
            enable_mic()
        case "billing.exhausted":
            show_top_up()

ws = websocket.WebSocketApp(RELAY, on_open=on_open, on_message=on_message)
ws.run_forever()

# Stream mic: base64-encoded 24kHz mono s16le chunks
def send_mic(pcm: bytes):
    ws.send(json.dumps({
        "type": "audio.chunk",
        "data": base64.b64encode(pcm).decode()
    }))

import 'package:http/http.dart' as http;
import 'package:web_socket_channel/web_socket_channel.dart';
import 'dart:convert';

const BASE  = 'https://starsapi.com/api/v2/partner/ai/voice';
const RELAY = 'wss://starsapi.com/voice-relay-v2';

// Phase 1 — REST: create the session
final r = await http.post(
  Uri.parse('$BASE/start'),
  headers: {'X-Api-Key': apiKey, 'Content-Type': 'application/json'},
  body: jsonEncode({
    'astrologer': 'guruji',
    'year': 1990, 'month': 6, 'day': 15,
    'hour': 14, 'minute': 30, 'timezone': 'Asia/Kolkata',
    'latitude': 28.6139, 'longitude': 77.2090,
    'name': 'Ravi', 'gender': 'male',
    'preferred_language': 'en',
  }),
);
final sessionId = jsonDecode(r.body)['data']['session_id'];

// Phase 2 — WebSocket: real-time conversation
final ws = WebSocketChannel.connect(Uri.parse(RELAY));
ws.sink.add(jsonEncode({
  'type': 'auth', 'session_id': sessionId,
  'api_key': apiKey, 'name': 'Ravi', 'lang': 'en',
}));

ws.stream.listen((raw) {
  final f = jsonDecode(raw);
  switch (f['type']) {
    case 'ready':
      ws.sink.add(jsonEncode({'type': 'greet', 'name': 'Ravi', 'lang': 'en'}));
    case 'user.speech_started':
      if (assistantPlaying) ws.sink.add(jsonEncode({'type': 'interrupt'}));
    case 'assistant.audio':
      playPcmChunk(base64Decode(f['data']));
    case 'assistant.transcript':
      appendCaption(f['delta']);
    case 'assistant.done':
      enableMic();
    case 'billing.exhausted':
      showTopUp();
  }
});

// Stream mic: 24kHz mono s16le PCM, base64-encoded
void onMicChunk(Uint8List pcm) {
  ws.sink.add(jsonEncode({'type': 'audio.chunk', 'data': base64Encode(pcm)}));
}

200 RESPONSE

{
  "success": true,
  "data": {
    "session_id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "turn": 0,
    "astrologer": {
      "key": "guruji",
      "name": "Guruji",
      "tagline": "Your Vedic guide",
      "avatar": "🕉️",
      "astrology_system": "vedic"
    },
    "billing": {
      "cost_minor": 0,
      "currency": "INR",
      "wallet_balance_minor": 50000,
      "wallet_balance_human": "₹500.00"
    }
  }
}