Spaces:

harshad-dhokane
/

voice-auth-api

Sleeping

App Files Files Community

voice-auth-api / POSTMAN_TESTING_GUIDE.md

harshad-dhokane

update

e9fb375 5 months ago

preview code

Raw

History Blame Contribute Delete

7.5 kB

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):

{
  "language": "English",
  "audioFormat": "mp3",
  "audioBase64": "dGVzdA=="
}

Expected Response

{
  "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):

{
  "language": "English",
  "audioFormat": "mp3",
  "audioBase64": "dGVzdA=="
}

Expected Response

{
  "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):

{
  "language": "French",
  "audioFormat": "mp3",
  "audioBase64": "dGVzdA=="
}

Expected Response

{
  "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):

{
  "language": "English",
  "audioFormat": "wav",
  "audioBase64": "dGVzdA=="
}

Expected Response

{
  "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):
```
{
  "language": "English"
}
```

Expected Response

{
  "status": "error",
  "message": "Malformed request"
}

Status: 422 Unprocessable Entity

6. Test Valid Request (All 5 Languages)

Test Each Supported Language:

English

{
  "language": "English",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}

Tamil

{
  "language": "Tamil",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}

Hindi

{
  "language": "Hindi",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}

Malayalam

{
  "language": "Malayalam",
  "audioFormat": "mp3",
  "audioBase64": "YOUR_BASE64_AUDIO_HERE"
}

Telugu

{
  "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

{
  "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

{
  "status": "healthy",
  "model_loaded": true
}

Status: 200 OK

8. Test Root Endpoint

Request

Method: GET
URL: {{base_url}}/
Headers: None required

Expected Response

{
  "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)

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

macOS/Linux

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

Python Script

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

Don't forget the x-api-key header
Don't use audioFormat: "wav" - only mp3 is accepted
Don't use unsupported languages like "french" or "spanish"
Don't send audio larger than 10MB
Don't send audio longer than 60 seconds
Don't wrap the Base64 string in quotes in the body - it's already a string

✅ DO

Always include Content-Type: application/json header
Use exactly audioFormat: "mp3" (lowercase)
Use one of the 5 supported languages
Ensure Base64 audio is valid and complete
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