API تحديد الجنس من الصوت
حدّد الجنس المحتمل للمتحدث من الصوت المرفوع أو من عنوان URL صوتي.
عنوان URL الأساسي
https://api.genderrecognition.com
اختيار نقطة النهاية
| الخيار | الطريقة والمسار | مناسب لـ |
|---|---|---|
| تحليل الملف القياسي | POST /v1/voice-gender-recognition/api | رفع ملف باستخدام سلوك التحليل القياسي. |
| التحليل القياسي عبر URL | POST /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
محتوى الطلب
| الحقل | النوع | مطلوب | الوصف |
|---|---|---|---|
file | file | نعم | ملف صوتي لتحليله. |
مثال
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.