150 lines
3.9 KiB
Markdown
150 lines
3.9 KiB
Markdown
# 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
|
|
}
|
|
```
|