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

الحصص والاستخدام

يتتبّع GVR استخدام الطلبات لكل مفتاح API من خلال قيمة remainingRequests في حساب المستخدم.

واجهات API ذات الطلب الواحد​

تستهلك معظم استدعاءات API طلبًا واحدًا بعد معالجتها بنجاح.

أمثلة:

  • طلب ملف لتحديد الجنس من الصوت
  • طلب تقدير العمر من الصوت
  • طلب كشف الصوت المزيّف
  • طلب تحديد الجنس من الصورة
  • طلب تقدير العمر من الصورة
  • طلب تحليل اسم مفرد

واجهات CSV​

تختلف معالجة CSV لأن الملف الواحد قد يحتوي على صفوف كثيرة. تتحقق معالجة CSV من عدد الصفوف، وقد تستهلك طلبًا واحدًا لكل صف تتم معالجته.

إذا كان عدد صفوف الملف أكبر من عدد الطلبات المتبقية للمفتاح، ترفض API الطلب قبل معالجة ملف CSV.

بيانات الاستجابة​

تتضمن كثير من استجابات API الناجحة معلومات الحصة المحدّثة:

{
  "remainingRequests": 2999
}

استخدم هذه القيمة لعرض الاستخدام في تطبيقك، أو لإظهار دعوات الترقية قبل أن تنفد حصة المستخدم.

أخطاء الحصة​

قد تعيد نقاط نهاية الملفات وCSV استجابة منظّمة لتجاوز حدّ الطلبات:

{
  "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": "Insufficient remaining requests"
}

إرشادات عملية​

  • تحقّق من الحقول المطلوبة قبل استدعاء API.
  • تجنّب حلقات إعادة المحاولة عند حدوث أخطاء التحقق.
  • اعتمد remainingRequests بعد كل استجابة API بوصفه المرجع الموثوق للحصة.
  • في مهام CSV، تحقّق من ملف CSV قبل بدء مهمة معالجة كبيرة.