بولنے والے کی تصدیق کی API

ایک حوالہ جاتی اور ایک امیدوار آڈیو کلپ کا موازنہ کریں، معلوم کریں کہ آیا دونوں ایک ہی بولنے والے کے ہیں، اور دونوں فائلوں کے لیے مماثلت کا اسکور اور آڈیو میٹا ڈیٹا حاصل کریں۔

بنیادی URL

https://api.genderrecognition.com

اینڈپوائنٹ

POST /v1/speaker-verification/api

ہیڈرز

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

درخواست کا مواد

فیلڈ	قسم	لازمی	وضاحت
reference	file	ہاں	معلوم بولنے والے کی آواز جس سے تصدیق کرنی ہے۔
candidate	file	ہاں	وہ آواز جس کا حوالہ جاتی آواز سے موازنہ کرنا ہے۔

مثال

curl -X POST "https://api.genderrecognition.com/v1/speaker-verification/api" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@audio.wav"

جواب

{
  "success": true,
  "same_speaker": true,
  "similarity": 87,
  "threshold": 70,
  "reference_audio": {
    "duration": 4.8,
    "sample_rate": 16000
  },
  "candidate_audio": {
    "duration": 5.1,
    "sample_rate": 16000
  },
  "remainingRequests": 119
}

جوابی فیلڈز

فیلڈ	قسم	وضاحت
success	boolean	دونوں کلپس کامیابی سے پراسیس ہونے پر true۔
same_speaker	boolean	جب similarity، threshold کے برابر یا اس سے زیادہ ہو تو true؛ یعنی دونوں کلپس ایک ہی بولنے والے کے سمجھے گئے۔
similarity	integer	دونوں آوازوں کی مماثلت، 0 سے 100 تک۔ زیادہ قدر زیادہ مماثلت ظاہر کرتی ہے۔
threshold	integer	same_speaker کے فیصلے کے لیے مماثلت کی حد، 0 سے 100 تک۔ اس حد کے برابر یا زیادہ similarity کو مماثلت سمجھا جاتا ہے۔
reference_audio.duration	number	موازنے کے لیے ڈی کوڈ کیے گئے حوالہ جاتی کلپ کا دورانیہ، سیکنڈ میں۔
reference_audio.sample_rate	number	موازنے سے پہلے حوالہ جاتی کلپ جس نمونہ شرح (Hz) پر ڈی کوڈ ہوا۔
candidate_audio.duration	number	موازنے کے لیے ڈی کوڈ کیے گئے امیدوار کلپ کا دورانیہ، سیکنڈ میں۔
candidate_audio.sample_rate	number	موازنے سے پہلے امیدوار کلپ جس نمونہ شرح (Hz) پر ڈی کوڈ ہوا۔
remainingRequests	integer	اس کامیاب درخواست کی کٹوتی کے بعد باقی API درخواستیں۔

similarity اور threshold مکمل عددی فیصد ہیں، خام اسکور نہیں۔

خرابی کی صورتیں

API key موجود نہیں

{ "error": "API key is required" }

غلط API key

{ "error": "Invalid API key" }

فائل موجود نہیں(s)

{ "error": "Both reference and candidate files are required" }

فائل بہت بڑی ہے

{ "error": "File too large" }

غیر متوقع فیلڈ

یہ جواب تب آتا ہے جب فائل reference یا candidate کے بجائے کسی اور فیلڈ نام سے اپ لوڈ ہو (مثلاً file استعمال کرنے یا اضافی فائل بھیجنے پر):

{ "error": "Unexpected field" }

فائل کی قسم غلط ہے

{
  "error": "Invalid file type. Allowed formats: WAV, MP3, FLAC, MP4, OGG, AIFF"
}

آڈیو کی تبدیلی ناکام ہوئی

یہ جواب تب آتا ہے جب فائل کی توسیع قابل قبول ہو لیکن ffmpeg اسے تبدیل نہ کر سکے (مثلاً فائل خراب ہو یا پڑھی نہ جا سکے):

{ "error": "Audio conversion failed: <details>" }

کوٹہ ختم ہو گیا

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

پراسیسنگ ناکام ہوئی

{ "error": "Speaker verification failed" }

نوٹس

• بیک اینڈ کئی عام آڈیو فارمیٹس قبول کرتا ہے، جیسے WAV، MP3، M4A، FLAC، OGG، WebM، AAC، Opus، WMA، AMR، 3GP، AIFF اور AU، اور تجزیے سے پہلے غیر WAV فائلوں کو تبدیل کرتا ہے۔
• دونوں اپ لوڈز کے لیے reference اور candidate فیلڈز استعمال کریں؛ ہر فائل 10 MB یا اس سے کم ہونی چاہیے۔
• حوالہ جاتی اور امیدوار کلپس الگ الگ پراسیس ہوتے ہیں، اس لیے ان کا دورانیہ، نمونہ شرح اور فارمیٹ مختلف ہو سکتا ہے۔
• درخواست صرف تصدیق کامیابی سے مکمل ہونے کے بعد منہا ہوتی ہے۔