# Voice Onboarding & Audio API Reference

**Implementation Sources**: [`app/api/voice_onboarding.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/api/voice_onboarding.py), [`app/services/voice_service.py`](file:///c:/Users/Lenovo/New%20folder%20%282%29/ai-patient-onboarding/app/services/voice_service.py)

---

## 1. POST `/v1/voice-onboarding/start`

Starts a voice-first onboarding session with Sarvam AI multilingual speech engine.

### Request Body (`StartVoiceOnboardingRequest`):
```json
{
  "patient": {
    "id": "PAT-VOICE-1",
    "name": "Ramesh G",
    "age": 34,
    "gender": "male"
  },
  "category": {
    "type": "general",
    "code": "general_medicine",
    "name": "General Medicine"
  },
  "language": "ta-IN"
}
```

### Supported Language Codes:
- `en-IN` (Indian English)
- `ta-IN` (Tamil)
- `hi-IN` (Hindi)
- `te-IN` (Telugu)
- `kn-IN` (Kannada)
- `ml-IN` (Malayalam)
- `mr-IN` (Marathi)

### Successful Response (`200 OK` - `StartVoiceOnboardingResponse`):
```json
{
  "success": true,
  "session_id": "VOICE-D3CAEA5C",
  "patient_id": "PAT-VOICE-1",
  "category": {
    "type": "general",
    "code": "general_medicine",
    "name": "General Medicine"
  },
  "language": "ta-IN",
  "status": "in_progress",
  "stage": "greeting",
  "greeting_text": "வணக்கம் Ramesh G, CureSelect மருத்துவமனைக்கு வரவேற்கிறோம். இன்று உங்களுக்கு என்ன சுகவீனம் உள்ளது?",
  "audio_url": "/v1/voice-onboarding/audio/aud_a1b2c3d4e5f6",
  "response_time_ms": 78.32,
  "response_time_sec": 0.08
}
```

---

## 2. POST `/v1/voice-onboarding/{session_id}/turn`

Processes a conversational voice turn using audio recording or text fallback.

### Request Headers:
```http
Content-Type: multipart/form-data
Authorization: Bearer test_token_PAT-VOICE-1
```

### Multipart Form Data Parameters:
- `audio`: Binary audio recording file (`WAV`, `WEBM`, `MP3`, `OGG` up to 10MB).
- `text_fallback`: String text transcript (used if WebSpeech STT processed client-side or audio is unprovided).

*Note: At least one of `audio` or `text_fallback` must be provided.*

### Successful Response (`200 OK` - `VoiceTurnResponse`):
```json
{
  "success": true,
  "session_id": "VOICE-D3CAEA5C",
  "patient_transcript": "எனக்கு கடந்த 3 நாளா நெஞ்சு பாரமா இருக்குங்க.",
  "ai_text": "நன்றி. இந்த நெஞ்சு பாரம் உடற்பயிற்சி செய்யும் போது அதிகமாகிறதா?",
  "stage": "symptoms",
  "completed": false,
  "audio_url": "/v1/voice-onboarding/audio/aud_f9e8d7c6b5a4",
  "audio_base64": null,
  "suggested_specialty": {
    "specialty": "Cardiology",
    "reason": "Chest tightness reported"
  },
  "response_time_ms": 1412.37,
  "response_time_sec": 1.41
}
```

---

## 3. GET `/v1/voice-onboarding/audio/{audio_id}`

Streams generated TTS audio for browser or mobile playback.

### Request Headers:
No authentication required for audio file streaming.

### Response Headers:
```http
HTTP/1.1 200 OK
Content-Type: audio/wav (or audio/mpeg)
Accept-Ranges: bytes
Content-Length: 48290
```

### Frontend Audio Playback snippet:
```javascript
const audio = new Audio(`${BASE_URL}/v1/voice-onboarding/audio/${audioId}`);
await audio.play();
```

---

## 4. POST `/v1/voice-onboarding/{session_id}/complete`

Finalizes a voice onboarding session.

### Request Body:
```json
{
  "confirmed": true
}
```

### Successful Response (`200 OK`):
```json
{
  "success": true,
  "session_id": "VOICE-D3CAEA5C",
  "status": "completed",
  "result": {
    "patient_id": "PAT-VOICE-1",
    "chief_complaint": "Chest tightness for 3 days",
    "language": "ta-IN",
    "onboarding_completed": true
  },
  "message": "Voice onboarding successfully saved to patient record.",
  "response_time_ms": 4121.79,
  "response_time_sec": 4.12
}
```