الحصص والاستخدام
يتتبّع GVR استخدام الطلبات لكل مفتاح API من خلال قيمة remainingRequests في حساب المستخدم.
تكلفة الطلب حسب العملية
يُخصم الرصيد بعد نجاح المعالجة. كما تستهلك نتيجة الجنس الناجحة unknown من الرصيد.
| العملية | الرصيد المستهلك |
|---|---|
| تحليل الجنس القياسي من ملف صوتي | طلب واحد |
| تحليل الجنس القياسي من عنوان URL | طلب واحد |
| تحديد الجنس من الصوت V2 (تحليل محسّن مع كشف الكلام) | طلب واحد |
| تحديد الجنس من الصوت V3 (تحليل متقدم للمتحدث) | طلبان |
| العمر الصوتي أو الصوت المزيّف أو مشاعر الكلام أو جودة الصوت أو التحقق من المتحدث أو تحليل صورة أو اسم واحد | طلب واحد لكل استدعاء API ناجح |
| التحقق من CSV | لا يستهلك طلبات؛ يتحقق فقط من كفاية الرصيد لمعالجة الصفوف |
| معالجة CSV | طلب واحد لكل صف تتم معالجته |
واجهات CSV
تختلف معالجة CSV لأن الملف الواحد قد يحتوي على صفوف كثيرة. تتحقق API من عدد الصفوف قبل المعالجة، ثم تستهلك طلبًا واحدًا لكل صف.
إذا كان عدد صفوف الملف أكبر من عدد الطلبات المتبقية للمفتاح، ترفض 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 قبل بدء مهمة معالجة كبيرة.