# NOMAZRA API Endpoints — Voice
Base URL: `https://nomazra.kelthos.com/api/nomazra/`

All endpoints require `Authorization: Bearer <access_token>`

---

## POST /voice/transcribe/
Transcribe an audio file using Whisper API.

**Content-Type:** multipart/form-data

**Request Fields:**
- `audio` (required): Audio file (mp3, wav, ogg, webm, mp4 — max 50MB)
- `conversation_id` (optional): Link to a conversation for context

**What happens:**
1. Audio validated (type + size)
2. If file > 25MB: split into 25MB chunks via ffmpeg
3. Each chunk transcribed via OpenAI Whisper (whisper-1)
4. Transcripts concatenated in order
5. If `conversation_id` provided: sends transcript as user message to AI, gets analysis
6. Stats updated

**Response 200:**
```json
{
  "transcription": "The full transcribed text...",
  "duration_seconds": 45.2,
  "language": "km",
  "ai_response": {
    "content": "Based on what you described...",
    "tokens_used": 312
  }
}
```
*`ai_response` only present if `conversation_id` was provided.*

**Errors:**
- 400: `{"error": "No audio file provided"}` / `{"error": "File too large (max 50MB)"}` / `{"error": "Invalid audio format"}`
- 500: `{"error": "Transcription failed: ..."}` 

---

## POST /voice/sessions/
Start a new voice session.

**Request Body:**
```json
{
  "conversation_id": "uuid (optional)",
  "language": "km (optional, default: km)"
}
```

**Response 201:**
```json
{
  "id": "uuid",
  "user": "user-uuid",
  "conversation": "conv-uuid or null",
  "started_at": "2025-01-20T14:30:00Z",
  "ended_at": null,
  "transcription": null,
  "ai_response": null,
  "status": "active"
}
```

---

## GET /voice/sessions/
List user's voice sessions.

**Response 200:** Array of voice session objects.

---

## PATCH /voice/sessions/{id}/
End a voice session.

**Request Body:**
```json
{
  "status": "completed",
  "transcription": "Final transcription text"
}
```

**Response 200:** Updated voice session object.

---

## POST /voice/tts/
**[TO BE BUILT]** Text-to-speech using OpenAI TTS API.

**Request Body:**
```json
{
  "text": "The legal process for filing a complaint...",
  "voice": "nova",
  "speed": 1.0
}
```

**Response 200:** Binary audio response (audio/mpeg).  
**Headers:** `Content-Type: audio/mpeg`

Available voices: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`  
Speed range: 0.25 to 4.0
