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	تكون true عندما تبلغ similarity قيمة threshold أو تتجاوزها، أي عند الحكم بأن المقطعين للمتحدث نفسه.
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 مفقود

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

مفتاح API غير صالح

{ "error": "Invalid API key" }

الملف مفقود

{ "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.
• تتم معالجة الصوت المرجعي والمرشح كلٌّ على حدة، لذا قد تختلف المدة ومعدل أخذ العينات والتنسيق.
• لا يُخصم الطلب إلا بعد اكتمال التحقق بنجاح.