إنتقل إلى المحتوى الرئيسي

API تحديد الجنس من الصوت

حدّد الجنس المحتمل للمتحدث من الصوت المرفوع أو من عنوان URL صوتي.

عنوان URL الأساسي​

https://api.genderrecognition.com

اختيار نقطة النهاية​

الخيارالطريقة والمسارمناسب لـ
تحليل الملف القياسيPOST /v1/voice-gender-recognition/apiرفع ملف باستخدام سلوك التحليل القياسي.
التحليل القياسي عبر URLPOST /v1/voice-gender-recognition/api/urlملف صوتي متاح عبر عنوان URL عام.
V2: تحليل التسجيل كاملًاPOST /v1/voice-gender-recognition/api/v2تحليل مع كشف الكلام لتسجيل يحتوي على متحدث واحد.
V3: تحليل المتحدثPOST /v1/voice-gender-recognition/api/v3المكالمات والمقابلات والتسجيلات متعددة المتحدثين.

تقبل نقطة النهاية القياسية عبر URL عنوانًا صوتيًا بصيغة JSON. تقبل V2 وV3 الملفات المرفوعة فقط ولا تقبل عناوين URL الصوتية.

نقطة نهاية الملف​

POST /v1/voice-gender-recognition/api

ترويسات الطلب​

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

محتوى الطلب​

الحقلالنوعمطلوبالوصف
filefileنعمملف صوتي لتحليله.

مثال​

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

نقاط نهاية الملفات ذات الإصدارات​

تظل نقطة نهاية الملف القياسية أعلاه متاحة للتكاملات الحالية. يوفر V2 وV3 خيارين إضافيين لتحليل الملفات. يقبل كل منهما ملفًا صوتيًا واحدًا في حقل multipart باسم file، ويتحقق من الكلام، ويمكنه إرجاع unknown عند عدم توفر كلام واضح كافٍ بدلًا من التخمين دائمًا بين ذكر وأنثى.

V2: تحليل التسجيل كاملًا​

POST /v1/voice-gender-recognition/api/v2

يتحقق V2 أولًا من وجود كلام بشري، ثم يصنّف التسجيل كاملًا باستخدام نموذج الصوت ECAPA-TDNN. وهو مناسب للتسجيلات التي تحتوي على متحدث واحد. عند وجود عدة متحدثين، تُحلّل أصواتهم معًا؛ استخدم V3 إذا احتجت إلى نتيجة خاصة بمتحدث واحد.

يستهلك كل استدعاء ناجح لـ V2 طلب API واحدًا.

curl -X POST "https://api.genderrecognition.com/v1/voice-gender-recognition/api/v2" \
-H "apiKey: YOUR_API_KEY" \
-F "file=@audio.wav"

مثال على الاستجابة عند تحديد الجنس:

{
"success": true,
"gender": "female",
"confidence": 92,
"remainingRequests": 119
}

عند عدم اكتشاف كلام بشري، يعيد V2 استجابة ناجحة مع ضبط gender على unknown:

{
"success": true,
"gender": "unknown",
"confidence": 0,
"message": "No clear speech was detected in the audio, so the gender could not be determined.",
"remainingRequests": 119
}

V3: تحليل المتحدث​

POST /v1/voice-gender-recognition/api/v3

يكشف V3 الكلام ويستخدم فصل المتحدثين لتصنيف متحدث واحد محدد. وهو مصمم للمكالمات والمقابلات والتسجيلات متعددة المتحدثين. يُختار المتحدث الأول، إلا إذا تحدث أقل من ثانيتين؛ عندها يُختار المتحدث صاحب أطول مدة كلام. إذا كانت مدة كلام المتحدث المحدد أقل من ثانية، تكون النتيجة unknown. يستغرق V3 وقتًا أطول من V2 ويجري اتصالًا مدفوعًا بخدمة Deepgram عند اكتشاف الكلام.

يستهلك كل استدعاء ناجح لـ V3 طلبَي API.

curl -X POST "https://api.genderrecognition.com/v1/voice-gender-recognition/api/v3" \
-H "apiKey: YOUR_API_KEY" \
-F "file=@audio.wav"

مثال على الاستجابة عند تحديد الجنس:

{
"success": true,
"gender": "female",
"confidence": 92,
"remainingRequests": 118
}

عند غياب الكلام أو قِصر كلام المتحدث المحدد، يعيد V3 استجابة ناجحة مع ضبط gender على unknown:

{
"success": true,
"gender": "unknown",
"confidence": 0,
"message": "Not enough clear speech from a single speaker was detected in the audio, so the gender could not be determined.",
"remainingRequests": 118
}

في كلا الإصدارين، تكون confidence نسبة مئوية صحيحة من 0 إلى 100، وتشير remainingRequests إلى الرصيد بعد الخصم. نتيجة unknown ناجحة وليست خطأ API. يستخدم الإصداران مفتاح API نفسه وحقل multipart وحدّ حجم الملف وأخطاء المصادقة والتحقق من الملف نفسها المتاحة في نقطة النهاية القياسية.

نقطة نهاية URL​

POST /v1/voice-gender-recognition/api/url

ترويسات الطلب​

apiKey: YOUR_API_KEY
Content-Type: application/json

محتوى الطلب​

{
"url": "https://example.com/audio.wav"
}

الاستجابة​

تعيد طلبات الملفات التوقع والثقة كنسبة مئوية وبيانات الحصة المحدّثة.

{
"success": true,
"gender": "male",
"confidence": 97,
"remainingRequests": 2999
}

تعيد طلبات URL التوقع وبيانات الحصة. وقد تتضمن الاستجابة رسالة info عند بطء الطلب الأول.

{
"success": true,
"gender": "male",
"remainingRequests": 2999
}

حالات الخطأ​

مفتاح API مفقود​

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

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

{
"error": "Invalid API key"
}

الملف مفقود​

{
"error": "No file uploaded"
}

نوع الملف غير صالح​

{
"error": "Invalid file type. Only audio formats are allowed"
}

طلب URL غير صالح​

{
"error": "A valid http or https URL is required"
}

ترويسة نوع محتوى JSON مفقودة​

{
"error": "Content-Type header is required. Please set Content-Type: application/json"
}

نوع محتوى JSON غير مدعوم​

{
"error": "Content-Type must be application/json"
}

تم تجاوز الحصة​

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

ملاحظات​

  • تستخدم طلبات الملفات بيانات نموذج multipart.
  • تستخدم طلبات URL تنسيق JSON.
  • استخدم الحقل file لرفع الصوت، ويجب ألا يتجاوز حجم الملف 10 MB.