# Postman Testing Guide - Voice Authentication API

## Base URL
```
https://YOUR_USERNAME-voice-auth-api.hf.space
```

## 1. Test Authentication Failure (No API Key)

### Request
- **Method**: POST
- **URL**: `{{base_url}}/api/voice-detection`
- **Headers**:
  ```
  Content-Type: application/json
  ```
- **Body** (raw - JSON):
  ```json
  {
    "language": "English",
    "audioFormat": "mp3",
    "audioBase64": "dGVzdA=="
  }
  ```

### Expected Response
```json
{
  "status": "error",
  "message": "Missing API key"
}
```
**Status**: 401 Unauthorized

---

## 2. Test Authentication Failure (Invalid API Key)

### Request
- **Method**: POST
- **URL**: `{{base_url}}/api/voice-detection`
- **Headers**:
  ```
  Content-Type: application/json
  x-api-key: wrong-key-here
  ```
- **Body** (raw - JSON):
  ```json
  {
    "language": "English",
    "audioFormat": "mp3",
    "audioBase64": "dGVzdA=="
  }
  ```

### Expected Response
```json
{
  "status": "error",
  "message": "Invalid API key"
}
```
**Status**: 401 Unauthorized

---

## 3. Test Invalid Language

### Request
- **Method**: POST
- **URL**: `{{base_url}}/api/voice-detection`
- **Headers**:
  ```
  Content-Type: application/json
  x-api-key: hackathon-2026-voice-auth-api-key
  ```
- **Body** (raw - JSON):
  ```json
  {
    "language": "French",
    "audioFormat": "mp3",
    "audioBase64": "dGVzdA=="
  }
  ```

### Expected Response
```json
{
  "status": "error",
  "message": "Malformed request"
}
```
**Status**: 422 Unprocessable Entity

---

## 4. Test Invalid Audio Format

### Request
- **Method**: POST
- **URL**: `{{base_url}}/api/voice-detection`
- **Headers**:
  ```
  Content-Type: application/json
  x-api-key: hackathon-2026-voice-auth-api-key
  ```
- **Body** (raw - JSON):
  ```json
  {
    "language": "English",
    "audioFormat": "wav",
    "audioBase64": "dGVzdA=="
  }
  ```

### Expected Response
```json
{
  "status": "error",
  "message": "Malformed request"
}
```
**Status**: 422 Unprocessable Entity

---

## 5. Test Missing Required Fields

### Request
- **Method**: POST
- **URL**: `{{base_url}}/api/voice-detection`
- **Headers**:
  ```
  Content-Type: application/json
  x-api-key: hackathon-2026-voice-auth-api-key
  ```
- **Body** (raw - JSON):
  ```json
  {
    "language": "English"
  }
  ```

### Expected Response
```json
{
  "status": "error",
  "message": "Malformed request"
}
```
**Status**: 422 Unprocessable Entity

---

## 6. Test Valid Request (All 5 Languages)

### Test Each Supported Language:

#### English
```json
{
  "language": "English",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}
```

#### Tamil
```json
{
  "language": "Tamil",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}
```

#### Hindi
```json
{
  "language": "Hindi",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}
```

#### Malayalam
```json
{
  "language": "Malayalam",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}
```

#### Telugu
```json
{
  "language": "Telugu",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}
```

### Headers for All:
```
Content-Type: application/json
x-api-key: hackathon-2026-voice-auth-api-key
```

### Expected Success Response
```json
{
  "status": "success",
  "language": "English",
  "classification": "AI_GENERATED",
  "confidenceScore": 0.89,
  "explanation": "Detected unnatural pitch consistency and spectral artifacts in the 4-8kHz range characteristic of neural vocoder synthesis"
}
```
**Status**: 200 OK

---

## 7. Test Health Check

### Request
- **Method**: GET
- **URL**: `{{base_url}}/health`
- **Headers**: None required

### Expected Response
```json
{
  "status": "healthy",
  "model_loaded": true
}
```
**Status**: 200 OK

---

## 8. Test Root Endpoint

### Request
- **Method**: GET
- **URL**: `{{base_url}}/`
- **Headers**: None required

### Expected Response
```json
{
  "name": "Voice Authentication API",
  "version": "1.0.0",
  "status": "operational",
  "endpoints": {
    "classify": "/api/voice-detection (POST)",
    "docs": "/docs",
    "health": "/health"
  },
  "supported_languages": ["tamil", "english", "hindi", "malayalam", "telugu"],
  "authentication": "Required via 'x-api-key' header"
}
```
**Status**: 200 OK

---

## How to Convert Audio to Base64 for Testing

### Windows (PowerShell)
```powershell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\path\to\audio.mp3")) | Set-Clipboard
```

### macOS/Linux
```bash
base64 audio.mp3 | pbcopy  # macOS
base64 audio.mp3 | xclip -selection clipboard  # Linux
```

### Python Script
```python
import base64

with open("audio.mp3", "rb") as f:
    encoded = base64.b64encode(f.read()).decode("utf-8")
    print(encoded)
```

---

## Postman Environment Variables

Create an environment with these variables:

| Variable | Initial Value | Current Value |
|----------|--------------|---------------|
| base_url | `https://YOUR_USERNAME-voice-auth-api.hf.space` | `https://YOUR_USERNAME-voice-auth-api.hf.space` |
| api_key | `hackathon-2026-voice-auth-api-key` | `hackathon-2026-voice-auth-api-key` |

---

## Postman Collection Structure

```
Voice Auth API Tests
├── Authentication
│   ├── 01 - No API Key (Should Fail)
│   ├── 02 - Invalid API Key (Should Fail)
│   └── 03 - Valid API Key (Should Pass)
├── Validation
│   ├── 04 - Invalid Language (Should Fail)
│   ├── 05 - Invalid Audio Format (Should Fail)
│   └── 06 - Missing Fields (Should Fail)
├── Classification
│   ├── 07 - English Audio
│   ├── 08 - Tamil Audio
│   ├── 09 - Hindi Audio
│   ├── 10 - Malayalam Audio
│   └── 11 - Telugu Audio
└── Health
    ├── 12 - Health Check
    └── 13 - Root Endpoint
```

---

## Common Mistakes to Avoid

### ❌ DON'T
1. Don't forget the `x-api-key` header
2. Don't use `audioFormat: "wav"` - only `mp3` is accepted
3. Don't use unsupported languages like "french" or "spanish"
4. Don't send audio larger than 10MB
5. Don't send audio longer than 60 seconds
6. Don't wrap the Base64 string in quotes in the body - it's already a string

### ✅ DO
1. Always include `Content-Type: application/json` header
2. Use exactly `audioFormat: "mp3"` (lowercase)
3. Use one of the 5 supported languages
4. Ensure Base64 audio is valid and complete
5. Use the correct API key: `hackathon-2026-voice-auth-api-key`

---

## Response Status Codes Reference

| Code | Meaning | When It Happens |
|------|---------|-----------------|
| 200 | Success | Classification successful |
| 400 | Bad Request | Invalid audio format/content |
| 401 | Unauthorized | Missing or invalid API key |
| 422 | Validation Error | Invalid schema/language/format |
| 500 | Internal Error | Server/processing error |

---

## Testing Checklist

- [ ] Test without API key (expect 401)
- [ ] Test with wrong API key (expect 401)
- [ ] Test with invalid language (expect 422)
- [ ] Test with wrong audioFormat (expect 422)
- [ ] Test with missing fields (expect 422)
- [ ] Test with valid English audio (expect 200)
- [ ] Test with valid Tamil audio (expect 200)
- [ ] Test with valid Hindi audio (expect 200)
- [ ] Test with valid Malayalam audio (expect 200)
- [ ] Test with valid Telugu audio (expect 200)
- [ ] Check response has all required fields
- [ ] Check classification is "AI_GENERATED" or "HUMAN"
- [ ] Check confidenceScore is between 0.0 and 1.0
- [ ] Check explanation is meaningful