# 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

| Method | Path      | Purpose                            |
| ------ | --------- | ---------------------------------- |
| POST   | `/speech` | Convert a given text string to audio |

---

### 1.2 Request Structure

#### Request Body (JSON)

| Field  | Type   | Description                  | Example                                        |
| ------ | ------ | ---------------------------- | ---------------------------------------------- |
| text   | string | Text to convert to speech     | `"Hello, this is a test message."`             |

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

#### Query Parameters

| Parameter | Type    | Default | Description                                                                 |
| --------- | ------- | ------- | --------------------------------------------------------------------------- |
| stream    | boolean | false   | If true, returns continuous audio stream.                                   |
| as\_wav   | boolean | true    | **Streaming only**: If true, returns WAV chunks; if false, returns raw PCM. |

**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

```javascript
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

```javascript
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)

```javascript
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

| Method | Path              | Purpose          | Content-Type        |
| ------ | ----------------- | ---------------- | ------------------- |
| POST   | `/stt/transcribe` | Transcribe audio | multipart/form-data |

---

### 2.2 Request Structure

| Field       | Type | Description              |
| ----------- | ---- | ------------------------ |
| audio\_file | File | Audio file to transcribe |

---

### 2.3 Example Frontend (HTML + JS)

```html
<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

| Method | Path                              | Purpose                     |
| ------ | --------------------------------- | --------------------------- |
| POST   | `/sessions/`                      | Create a new chat session   |
| POST   | `/sessions/{session_id}/chat`     | Send a message in a session |
| GET    | `/sessions/{session_id}/messages` | Retrieve chat history       |

---

## 4. Documents API

Add, list, and delete documents.

### 4.1 Endpoints

| Method | Path                       | Purpose            |
| ------ | -------------------------- | ------------------ |
| POST   | `/documents/`              | Add a document     |
| GET    | `/documents/`              | List all documents |
| DELETE | `/documents/{document_id}` | Delete a document  |

---

### 4.2 Example Frontend (HTML + JS)

```html
<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>
```
