API Documentation

This repository provides frontend integration guides for the FastAPI backend's main endpoints:

1. Text-to-Speech (TTS) API
2. Speech-to-Text (STT) API
3. Chat Sessions API
4. Documents API

1. Text-to-Speech (TTS) API

This API converts text into audio, supporting both non-streaming and streaming modes.

1.1 Endpoint Details

1.2 Request Structure

Request Body (JSON)

Example:

{
  "text": "The quick brown fox jumps over the lazy dog."
}
`

Query Parameters

Example URLs:

Non-streaming: http://[your-api-server]/speech
Streaming WAV: http://[your-api-server]/speech?stream=true
Streaming PCM: http://[your-api-server]/speech?stream=true&as_wav=false

1.3 Frontend Examples (JavaScript)

Example 1: Non-Streaming

async function getSpeechAudio(text) {
  const response = await fetch('http://[your-api-server]/speech', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text })
  });
  const audioBlob = await response.blob();
  const audioUrl = URL.createObjectURL(audioBlob);
  new Audio(audioUrl).play();
}

Example 2: Streaming WAV

async function streamSpeechAudio(text) {
  const response = await fetch('http://[your-api-server]/speech?stream=true', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text })
  });
  const mediaSource = new MediaSource();
  const audio = new Audio(URL.createObjectURL(mediaSource));
  mediaSource.addEventListener('sourceopen', async () => {
    const sourceBuffer = mediaSource.addSourceBuffer('audio/wav');
    const reader = response.body.getReader();
    while (true) {
      const { done, value } = await reader.read();
      if (done) { mediaSource.endOfStream(); break; }
      sourceBuffer.appendBuffer(value);
    }
  });
  audio.play();
}

Example 3: Streaming PCM (Web Audio API)

async function streamPcmAudio(text) {
  const response = await fetch('http://[your-api-server]/speech?stream=true&as_wav=false', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text })
  });
  const audioContext = new AudioContext({ sampleRate: 24000 });
  const reader = response.body.getReader();
  let currentOffset = 0;

  function pcmToFloat32(pcm) {
    const int16 = new Int16Array(pcm.buffer);
    const float32 = new Float32Array(int16.length);
    for (let i = 0; i < int16.length; i++) float32[i] = int16[i] / 32768.0;
    return float32;
  }

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const data = pcmToFloat32(value);
    const buffer = audioContext.createBuffer(1, data.length, audioContext.sampleRate);
    buffer.copyToChannel(data, 0);
    const source = audioContext.createBufferSource();
    source.buffer = buffer;
    source.connect(audioContext.destination);
    source.start(currentOffset);
    currentOffset += buffer.duration;
  }
}

2. Speech-to-Text (STT) API

Converts uploaded audio into text.

2.1 Endpoint Details

2.2 Request Structure

2.3 Example Frontend (HTML + JS)

<input type="file" id="audioFile" accept="audio/*">
<button id="transcribeBtn">Transcribe</button>
<div id="result"></div>

<script>
document.getElementById('transcribeBtn').addEventListener('click', async () => {
  const file = document.getElementById('audioFile').files[0];
  const formData = new FormData();
  formData.append('audio_file', file);

  const res = await fetch('http://[your-api-server]/stt/transcribe', { method: 'POST', body: formData });
  const data = await res.json();
  document.getElementById('result').textContent = data.transcript;
});
</script>

3. Chat Sessions API

Manages conversational sessions with the AI.

3.1 Endpoints

4. Documents API

Add, list, and delete documents.

4.1 Endpoints

4.2 Example Frontend (HTML + JS)

<form id="addDoc">
  <input type="text" id="title" placeholder="Title" required>
  <textarea id="content" placeholder="Content" required></textarea>
  <button type="submit">Add Document</button>
</form>
<div id="docs"></div>

<script>
const API = 'http://[your-api-server]';

async function fetchDocs() {
  const res = await fetch(`${API}/documents/`);
  const data = await res.json();
  document.getElementById('docs').innerHTML = data.documents.map(doc =>
    `<div>${doc.title} <button onclick="delDoc(${doc.id})">Delete</button></div>`
  ).join('');
}

document.getElementById('addDoc').onsubmit = async e => {
  e.preventDefault();
  const title = document.getElementById('title').value;
  const content = document.getElementById('content').value;
  await fetch(`${API}/documents/`, {
    method: 'POST', headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title, content })
  });
  fetchDocs();
};

async function delDoc(id) {
  await fetch(`${API}/documents/${id}`, { method: 'DELETE' });
  fetchDocs();
}

fetchDocs();
</script>