Streaming API

Real-time AI responses with Server-Sent Events

POST /api/v1/astrology/query/stream Standard $0.01-$0.03; Swift $0.02-$0.05 (Business and above)

Why Use Streaming?

Faster Perceived Response

Users see text immediately instead of waiting for full response

Better Chat Experience

Natural typing effect like human conversation

Handle Long Responses

No timeout issues for detailed readings

Basic Streaming

import { VedikaClient } from '@vedika-io/sdk';

const client = new VedikaClient({ apiKey: process.env.VEDIKA_API_KEY });

// Stream a query response (each chunk is the JSON of one SSE "data:" line)
const stream = client.askQuestionStream({
  question: 'What does my birth chart reveal about career?',
  birthDetails: {
    datetime: '1990-05-15T10:30:00',
    latitude: 28.6139,
    longitude: 77.2090,
    timezone: '+05:30'
  }
});

// Handle streaming events
for await (const chunk of stream) {
  const event = JSON.parse(chunk);

  if (typeof event.response === 'string') {
    // The "completed" event carries the full answer
    console.log(event.response);
    console.log('\n\nStream complete!');
  }
}

Stream Event Types

Event Type Description Data
started Stream opened { ... } status and progress fields
progress Answer is being generated { status: string }
stage_completed A pipeline stage finished (for example the chart) { stage: string, data: object }
completed The full answer { success, response, metadata, followUps, conversationId, ... }
billing_completed Charge settled { charged, currency, usage: { inputTokens, outputTokens } }
data_sources Sources used for the answer { ... }
error Error occurred { error: string, code: string, statusCode: number }

Advanced Event Handling

const stream = client.askQuestionStream({
  question: 'Analyze my career and relationships',
  birthDetails: birthDetails
});

let fullResponse = '';

for await (const chunk of stream) {
  const event = JSON.parse(chunk);

  if (typeof event.response === 'string') {
    // "completed": the full answer, follow-up questions and metadata
    fullResponse = event.response;
    console.log(fullResponse);
    console.log('Follow-ups:', event.followUps);
  } else if (event.charged !== undefined) {
    // "billing_completed": what this query cost
    console.log('Charged:', event.charged, event.currency);
    console.log('Output tokens:', event.usage.outputTokens);
  } else if (event.error) {
    // "error": message, code and HTTP status
    console.error('Stream error:', event.error, event.code);
  } else {
    // "started", "progress", "stage_completed" and "data_sources"
    console.log('Progress:', event);
  }
}

// Full response is now available
console.log('Full response length:', fullResponse.length);

React Integration

import { useState, useCallback } from 'react';

function AstrologyChat() {
  const [messages, setMessages] = useState([]);
  const [isStreaming, setIsStreaming] = useState(false);
  const [currentResponse, setCurrentResponse] = useState('');

  const sendMessage = useCallback(async (question, birthDetails) => {
    setIsStreaming(true);
    setCurrentResponse('');

    // Add user message
    setMessages(prev => [...prev, { role: 'user', content: question }]);

    try {
      // Your backend route runs client.askQuestionStream() with your API key and
      // forwards each payload as an SSE "data:" line (see the Next.js guide)
      const res = await fetch('/api/chat/stream', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ question, birthDetails })
      });

      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 });
        const lines = buffer.split('\n');
        buffer = lines.pop(); // keep a partial line for the next read

        for (const line of lines) {
          if (!line.startsWith('data: ')) continue;
          const event = JSON.parse(line.slice(6));

          if (typeof event.response === 'string') {
            // The "completed" event carries the full answer: finalize the message
            setMessages(prev => [...prev, {
              role: 'assistant',
              content: event.response
            }]);
            setCurrentResponse('');
          } else {
            // started, progress, stage_completed: show a working indicator
            setCurrentResponse('Reading your chart...');
          }
        }
      }
    } catch (error) {
      console.error('Stream error:', error);
      setMessages(prev => [...prev, {
        role: 'error',
        content: 'Failed to get response. Please try again.'
      }]);
    } finally {
      setIsStreaming(false);
    }
  }, []);

  return (
    <div className="chat-container">
      {messages.map((msg, i) => (
        <div key={i} className={`message ${msg.role}`}>
          {msg.content}
        </div>
      ))}

      {isStreaming && currentResponse && (
        <div className="message assistant streaming">
          {currentResponse}
          <span className="cursor">|</span>
        </div>
      )}

      {/* Input form here */}
    </div>
  );
}

Browser EventSource (Low-Level)

// Direct SSE connection (for custom implementations; keep the API key on your server)
async function streamWithFetch(question, birthDetails, apiKey, extra = {}) {
  const response = await fetch('https://api.vedika.io/api/v1/astrology/query/stream', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`
    },
    body: JSON.stringify({ question, birthDetails, ...extra })
  });

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

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    buffer += decoder.decode(value, { stream: true });
    const lines = buffer.split('\n');
    buffer = lines.pop(); // keep a partial line for the next read

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

function handleEvent(name, data) {
  switch (name) {
    case 'completed':
      document.getElementById('response').textContent = data.response;
      break;
    case 'billing_completed':
      console.log('Complete. Charged', data.charged, data.currency);
      break;
    case 'error':
      console.error('Stream error:', data.error, data.code);
      break;
  }
}

Cancel Streaming

// Create an AbortController
const controller = new AbortController();

// Start streaming with the abort signal
const response = await fetch('https://api.vedika.io/api/v1/astrology/query/stream', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.VEDIKA_API_KEY}`
  },
  body: JSON.stringify({
    question: 'Tell me everything about my chart',
    birthDetails
  }),
  signal: controller.signal
});

// Cancel after 5 seconds
setTimeout(() => {
  console.log('Cancelling stream...');
  controller.abort();
}, 5000);

try {
  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    console.log(decoder.decode(value).slice(0, 50));
  }
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Stream was cancelled');
  } else {
    throw error;
  }
}

Multi-Turn Conversation

// Stream with conversation context (streamWithFetch is defined above).
// The server keeps the history: send the conversationId from an earlier
// "completed" event instead of the previous messages.
await streamWithFetch('What about my love life?', birthDetails, process.env.VEDIKA_API_KEY, {
  conversationId: 'conv_abc123'  // Continue an existing conversation
});

Related Topics