API فحص جودة الصوت

قيّم الجودة الإدراكية للصوت المرفوع، وأعد الدرجة الإجمالية واكتشاف الكلام ومستوى الضوضاء الخلفية ومستوى الصوت ومؤشرات القصّ أو التشويه.

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

https://api.genderrecognition.com

نقطة النهاية

POST /v1/audio/quality/api

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

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

محتوى الطلب

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

مثال

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

الاستجابة

{
  "success": true,
  "quality_score": 82,
  "quality_label": "good",
  "mos_score": 4.1,
  "speech": {
    "detected": true,
    "duration": 4.8,
    "ratio": 92
  },
  "noise": {
    "level": "low",
    "snr_db": 28.4
  },
  "volume": {
    "too_quiet": false,
    "rms_dbfs": -18.2
  },
  "clipping": {
    "detected": false,
    "ratio": 0
  },
  "audio": {
    "duration": 5.2,
    "sample_rate": 44100,
    "channels": 1
  },
  "remainingRequests": 119
}

حقول الاستجابة

الحقل	النوع	الوصف
success	boolean	تكون true عند معالجة الصوت بنجاح.
quality_score	integer or null	الجودة الإدراكية الإجمالية من 0 إلى 100. تكون null عند عدم اكتشاف الكلام.
quality_label	string or null	تصنيف الجودة المقابل لـ quality_score: excellent أو good أو fair أو poor. وتكون القيمة null إذا كان quality_score يساوي null.
mos_score	number or null	درجة متوسط الرأي المتوقعة الخام من 1 إلى 5 (الأعلى أفضل). تكون null عند عدم اكتشاف الكلام.
speech.detected	boolean	ما إذا تم اكتشاف كلام في الملف.
speech.duration	number	مدة الصوت المصنف على أنه كلام، بالثواني.
speech.ratio	integer	نسبة الكلام من الملف، من 0 إلى 100.
noise.level	string or null	مستوى الضوضاء الخلفية: low أو medium أو high. تكون null عند تعذر القياس، مثل عدم توفر صوت غير كلامي للمقارنة.
noise.snr_db	number or null	نسبة الإشارة إلى الضوضاء للكلام مقارنة بالضوضاء الخلفية، بوحدة dB. وتكون null في الحالات نفسها التي يتعذر فيها قياس noise.level.
volume.too_quiet	boolean	تكون true عندما يكون الصوت منخفضًا جدًا بحيث يتعذر استخدامه بشكل موثوق.
volume.rms_dbfs	number	مستوى الصوت بوحدة dBFS. تمثل 0 أعلى مستوى ممكن، وتشير القيم الأكثر سلبية إلى صوت أخفض.
clipping.detected	boolean	تكون true عند اكتشاف قصّ أو تشويه.
clipping.ratio	integer	نسبة عينات الصوت المتأثرة بالقصّ، من 0 إلى 100.
audio.duration	number	مدة الملف المرفوع بالثواني.
audio.sample_rate	number	معدل أخذ عينات الصوت المرفوع، بوحدة Hz.
audio.channels	number	عدد قنوات الصوت (1 = أحادي، 2 = ستيريو).
remainingRequests	integer	عدد طلبات API المتبقية بعد خصم هذا الطلب الناجح.

القيم quality_score وspeech.ratio وclipping.ratio نسب مئوية صحيحة. أما noise.snr_db وvolume.rms_dbfs فقيم بالديسيبل وليست نسبًا مئوية.

حالات الخطأ

مفتاح API مفقود

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

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

{ "error": "Invalid API key" }

الملف مفقود

{ "error": "No file uploaded" }

الملف كبير جدًا

{ "error": "File too large" }

حقل نموذج غير متوقع

يُعاد هذا الخطأ عند رفع الملف باستخدام اسم حقل غير 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": "Audio quality assessment failed" }

ملاحظات

• يقبل الخادم تنسيقات صوتية شائعة عديدة مثل WAV وMP3 وM4A وFLAC وOGG وWebM وAAC وOpus وWMA وAMR و3GP وAIFF وAU، ويحوّل الملفات غير WAV قبل التحليل.
• استخدم الحقل file لرفع الصوت، ويجب ألا يتجاوز حجم الملف 10 MB.
• لا يُخصم الطلب إلا بعد اكتمال تقييم الجودة بنجاح.