مساعدة GenderAPI.io V2
الأسئلة الشائعة
إجابات عن طلبات V2 ودرجة الثقة والنتائج غير المعروفة والأرصدة والخصوصية والحساب. إذا كنت تشغّل تكاملًا قديمًا، فراجع وثائق V1.
النتائج ودرجة الثقة
افهم التقدير وحدوده
سياق الدولة ودرجات الثقة والنتائج غير المعروفة في API V2.
هل تحدد نتيجة GenderAPI جنس الشخص؟
لا. تستنتج GenderAPI الجنس من إشارات مرتبطة بالاسم، أو من إشارات الاسم المستعار عند تفعيل هذا الخيار. التقدير ليس معلومة شخصية مؤكدة. احتفظ بعدم اليقين، واحترم الهوية التي يصرّح بها الشخص عن نفسه، ولا تعتمد على هذا الاستنتاج وحده في القرارات ذات الأثر الكبير.
كيف يؤثر سياق الدولة في النتيجة؟
يوفّر رمز الدولة الاختياري وفق ISO بأحرف لاتينية كبيرة سياقًا إقليميًا للطلب. أرسله فقط عندما تكون الدولة معروفة وذات صلة. قد يختلف استخدام الاسم نفسه بين المناطق؛ والدولة المُعادة تعبّر عن ارتباط بالاسم، وليست دليلًا على الجنسية أو مكان الإقامة.
ماذا تعني درجة الثقة في V2؟
الحقل confidence قيمة بين 0 و1، أو null عندما لا تتوفر. اقرأه مع confidence_kind: تعني observed_frequency عدد الجنس الغالب في مجموعة البيانات مقسومًا على العدد الإجمالي، أما model_reported فهي درجة صادرة عن الذكاء الاصطناعي. هذه الدرجات ليست احتمالات معايَرة عن الشخص ولا دقة مقيسة للمنتج. حدّد عتبات المراجعة اعتمادًا على بيانات ممثِّلة.
ماذا تعني القيمة gender: null، وهل تُحتسب رسومها؟
تعني نتيجة V2 الناجحة التي تتضمن gender: null أن الإشارات المتاحة لم تحدّد الجنس. وتُستخدم فيها قيمة null الأصلية في JSON، لا السلسلة النصية "null". تُحتسب رسوم النتيجة الناجحة غير المعروفة وفق تكلفة الوضع المختار. احتفظ بها على أنها غير معروفة؛ أما فشل مزوّد الخدمة أو فشل الطلب فهو خطأ مستقل.
هل يمكنني إرسال أسماء مكتوبة بأنظمة كتابة مختلفة؟
نعم. أرسل الأسماء بترميز Unicode بحروفها الأصلية وعلاماتها المميِّزة ذات الدلالة. تختلف التغطية ودرجة الثقة حسب الاسم والمنطقة والإشارات المتاحة، لذا اختبر عينة ممثِّلة من أنظمة الكتابة والدول التي يخدمها تطبيقك.
API والذكاء الاصطناعي
اختر نوع الطلب وخيار الذكاء الاصطناعي
أنواع طلبات V2 والطلبات المجمّعة وسلوك الذكاء الاصطناعي وحدود الاستخدام.
هل يمكنني تحليل الأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين في طلب مجمّع واحد؟
نعم. يقبل POST /api/v2/gender/batch حتى 50 عنصرًا باستخدام مفتاح API، وحتى 10 عناصر في التجربة حسب عنوان IP. لكل عنصر type وvalue خاصان به، إضافة إلى country اختياري وإعدادات الذكاء الاصطناعي. يكون الذكاء الاصطناعي معطّلًا افتراضيًا في عناصر الطلب المجمّع. افحص كل نتيجة: قد يعيد الطلب المجمّع HTTP 200 مع فشل بعض العناصر، وتُحتسب الأرصدة لكل عنصر ناجح، بما في ذلك النتائج غير المعروفة.
كيف يعمل طلب البريد الإلكتروني؟
استخدم type: email مع عنوان صالح. تبحث API عن إشارة اسم قابلة للاستخدام في الجزء المحلي قبل العلامة @؛ ولا يحدّد النطاق هوية الشخص أو دولته. قد تعيد صناديق البريد المشتركة والعناوين التي لا تتضمن إشارة اسم نتيجة غير معروفة. يستخدم الطلب الفردي افتراضيًا الرجوع إلى الذكاء الاصطناعي إذا لم تحدّد مجموعة البيانات الجنس.
كيف يعمل طلب اسم المستخدم؟
استخدم type: username. يبحث الطلب العادي عن اسم أول يمكن التعرف عليه في المعرّف أو اسم العرض. قد تعيد الأسماء المستعارة المجرّدة نتيجة غير معروفة. فعّل forceToGenderize إذا أردت استخدام ذكاء اصطناعي يفهم الأسماء المستعارة بعد تعذّر التحديد من مجموعة البيانات؛ وقد يُنتج ذلك جنسًا من دون استخراج اسم أول حقيقي.
متى يستخدم V2 الذكاء الاصطناعي؟
الوضع الافتراضي للطلبات الفردية هو options.ai_mode: fallback: تُفحص مجموعة البيانات أولًا، ثم يُستخدم الذكاء الاصطناعي إذا لم يُحدَّد الجنس، بتكلفة إجمالية قدرها رصيد واحد. يستخدم off مجموعة البيانات فقط بتكلفة رصيد واحد؛ ويتخطّى always مجموعة البيانات ويستخدم الذكاء الاصطناعي بتكلفة رصيدين. تكون عناصر الطلب المجمّع على off افتراضيًا، ويمكن تفعيل الذكاء الاصطناعي لكل عنصر على حدة. لا يضمن أيٌّ من هذه الأوضاع نتيجة غير null.
ماذا يفعل forceToGenderize؟
يعمل هذا الخيار الاختياري مع مدخلات الاسم والبريد الإلكتروني واسم المستخدم، بما في ذلك عناصر الطلب المجمّع كلٌّ على حدة. تكلفة النتيجة المحدَّدة من مجموعة البيانات رصيد واحد. وإلا يُستخدم ذكاء اصطناعي يفهم الأسماء المستعارة بتكلفة إجمالية قدرها رصيدان، بما في ذلك النتيجة الناجحة غير المعروفة. لا يلزم وجود اسم أول حقيقي. لا ترسل ai_mode أو استخدم fallback؛ فالجمع بين هذا الخيار وoff أو always يعيد 422.
كيف تُخصم الأرصدة في V2؟
راجع meta.usage.charged_credits لمعرفة صافي تكلفة العملية، وbilling_status لمعرفة تأكيدها. تكلفة تقديرات مجموعة البيانات وfallback العادية رصيد واحد لكل عنصر ناجح؛ أما always والذكاء الاصطناعي الذي يفهم الأسماء المستعارة فتكلفتهما رصيدان. تكلفة كل تحقق مكتمل من رقم هاتف رصيد واحد، حتى عندما تكون النتيجة غير صالحة. يكفي أن يكون الرصيد موجبًا عند البدء، لذلك قد يصبح سالبًا بعد الخصم النهائي. تُسترد أرصدة التقديرات الفاشلة؛ وتحتاج الفوترة غير المؤكدة إلى مراجعة من فريق الدعم.
هل توجد حدود للطلبات في V2؟
نعم. تشمل الحدود الافتراضية الحالية 120 طلبًا في الدقيقة لكل حساب، و600 طلب في الدقيقة لكل عنوان IP، وعمليتين متزامنتين لكل حساب. كما تنطبق حدود السعة المشتركة للخدمة. الحد الأقصى لحجم جسم طلب POST هو 64 KiB؛ ويقبل الطلب المجمّع 50 عنصرًا باستخدام مفتاح أو 10 عناصر في التجربة حسب عنوان IP. التزم بـ HTTP 429 وRetry-After، ولا تفترض أن الطلبات ستُقبل دائمًا عند هذه الحدود القصوى.
هل يمكنني إعادة إرسال طلب فشل أو انتهت مهلته؟
كل طلب تقدير عملية جديدة تُحتسب رسومها بالطريقة المعتادة. انتهاء المهلة أو فقدان الاستجابة لا يثبت عدم خصم الرسوم. تحقّق من billing_status قبل إعادة المحاولة؛ وإذا لم تكن الفوترة مؤكدة، فتواصل مع فريق الدعم وأرسل request_id. في الطلب المجمّع الناجح جزئيًا، أعد إرسال العناصر الفاشلة فقط بعد تأكيد الفوترة. والتزم بـ Retry-After عند تلقي 429.
أين أجد أمثلة الشيفرة والأدوات الخاصة بـ V2؟
تتضمن أدلة V2 أمثلة بلغات cURL وJavaScript وPython وPHP وJava وC# وGo. ويستخدم Swagger وPostman مواصفة V2 نفسها. اختر نوع الإدخال، واحفظ مفتاح API في إعدادات الخادم.
هل يمكنني الاستمرار في استخدام V1؟
نعم. تحتفظ تكاملات V1 الحالية بنقاط النهاية وتنسيقات الاستجابة الأصلية. يتشارك V1 وV2 مفتاح API ورصيد الحساب نفسيهما، لكن حقول الطلب والاستجابات والأخطاء تختلف بينهما. استخدم مرجع V1 المستقل لصيانة عميل قائم، ودليل الترحيل عندما تكون مستعدًا لتحديثه.
الخصوصية والملفات
افهم طريقة التعامل مع البيانات
أين تجد المعلومات الحالية عن المعالجة والاحتفاظ والحذف.
هل تُخزَّن طلبات GenderAPI الناجحة؟
توضح سياسة الخصوصية سجلات الطلبات والسجلات التشغيلية وسجلات الأمان التي قد يُحتفظ بها، وسبب معالجتها، وطريقة حذفها. راجع هذه التفاصيل فيما يخص تكاملك، وتجنّب إرسال بيانات شخصية غير ضرورية.
هل تُخزَّن عناوين البريد الإلكتروني المرسلة في الطلبات؟
راجع سياسة الخصوصية لمعرفة طريقة التعامل الحالية مع مدخلات البريد الإلكتروني والسجلات التقنية المرتبطة بها. قد يكون عنوان البريد الإلكتروني بيانات شخصية؛ أرسل فقط ما يتطلبه الطلب، وتجنّب تسجيل العناوين الكاملة في سجلات التشخيص لديك.
ما مدة الاحتفاظ بملفات Excel أو CSV المرفوعة؟
تحدد سياسة الخصوصية مدة الاحتفاظ بالملفات المرفوعة وطريقة حذفها والتعامل مع نسخها الاحتياطية. صدّر النتائج التي تحتاج إليها، واستخدم أدوات الحذف في مساحة العمل عندما لا تعود بحاجة إلى الملف المرفوع. وتواصل مع فريق الدعم إذا كانت لديك أسئلة عن متطلبات الاحتفاظ الخاصة بمؤسستك.
هل يمكن لمزوّدي الخدمات معالجة بيانات الطلبات أو الملفات المرفوعة؟
توضح سياسة الخصوصية ومعلومات المعالجين الفرعيين المعالجة التي يجريها مزوّدو الخدمات والضمانات المطبّقة. راجع هذه الموارد وأي اتفاقية تنطبق على حسابك عند تقييم مكان معالجة بياناتك.
الحساب والدعم
اربط مفتاحك وأدِر حسابك
الاستخدام المجاني والمصادقة والاستعلام عن الرصيد والدعم.
هل يمكنني تجربة GenderAPI مجانًا؟
نعم. يمنح الحساب المجاني المسجّل 200 رصيد يوميًا. وبشكل منفصل، تمنح تجربة V2 من دون مفتاح 10 أرصدة لكل عنوان IP عام خلال فترة 24 ساعة، يتشاركها V1 والمستخدمون الآخرون على عنوان IP نفسه. تنطبق على الاثنين تكاليف الأرصدة المعتادة؛ ولا يساوي عدد الأرصدة دائمًا عدد طلبات HTTP.
كيف أُجري المصادقة وأحمي مفتاح API؟
استخدم Authorization: Bearer YOUR_API_KEY من شيفرة موثوقة تعمل على الخادم؛ وتحتاج طلبات POST أيضًا إلى Content-Type: application/json. أبقِ المفتاح الحقيقي خارج شيفرة المتصفح والمستودعات العامة والسجلات. قد تستخدم المفاتيح المفقودة أو غير الصالحة التنسيق أو غير المعروفة التجربة حسب عنوان IP، لذا تأكد من أن قيمة meta.access.mode هي api_key. أما المفاتيح المعروفة المعطّلة أو المنتهية الصلاحية أو المقيّدة فلا تنتقل إلى التجربة.
كيف أتحقق من الأرصدة المتبقية؟
استدعِ GET /api/v2/usage باستخدام مفتاح Bearer الخاص بك. هذا الاستعلام عن الرصيد مجاني ويعيد data.remaining_credits. ومن دون مفتاح، يقرأ رصيد التجربة المشتركة حسب عنوان IP. يستخدم V1 وV2 رصيد الحساب نفسه؛ وتمثّل قيمة remaining_credits في استجابة التقدير الرصيد لحظة اكتمال العملية.
أين يمكنني إدارة الاشتراك أو إلغاؤه؟
سجّل الدخول إلى تطبيق GenderAPI لإدارة الاشتراك المرتبط بمفتاح API. استخدم إعدادات الحساب الحالية لمراجعة الخطة وخيارات الإلغاء.
أين يمكنني تحديث بيانات الفوترة؟
أدِر إعدادات الفوترة والدفع الخاصة بمفتاح API أو الاشتراك المعني داخل تطبيق GenderAPI بعد تسجيل الدخول.
كيف أبلغ عن نتيجة غير صحيحة أو أطلب مساعدة في التكامل؟
أرسل إلى فريق الدعم إصدار API ونقطة النهاية وrequest_id ومثالًا صغيرًا قابلًا لإعادة الإنتاج. أرفق رمز الخطأ إن توفر، لكن احذف مفتاح API والبيانات الشخصية الحساسة.
المعلومات التقنية
أدلة التكامل والاستخدام المسؤول
إجابات عن نتائج V2 والخصوصية والتشغيل مع روابط إلى الأدلة المعنية؛ ولكل إجابة نسخة بتنسيق Markdown.
النتائج ودرجة الثقة والاستخدام المسؤول
يستخدم تقدير V2 الذي لم يُحدَّد فيه الجنس قيمة null الأصلية في JSON للحقل gender، لا السلسلة النصية "null". قد يكون الاسم ملتبسًا أو قد لا تكفي الإشارات المتاحة؛ راجع result_status وreason عند وجودهما. احتفظ بالنتيجة على أنها غير معروفة بدلًا من فرض فئة عليها. تُحتسب رسوم التقدير الناجح غير المعروف وفق تكلفة الوضع المختار. أما أخطاء الطلب أو مزوّد الخدمة فهي حالات فشل مستقلة، وتظهر معلومات فوترتها في meta.usage.
اقرأ الإجابة كاملة ←كيف تُقيَّم دقة GenderAPI؟يوضّح التقييم المفيد للدقة مجموعة الاختبار وتاريخه وطريقة أخذ العينات ونسبة النتائج غير المعروفة والنتائج حسب المنطقة ونظام الكتابة. تصف صفحة المنهجية الحالية بروتوكول تقييم، لا نسبة دقة مقيسة. ويشرح الحقلان confidence وconfidence_kind في V2 الأدلة التي تستند إليها كل نتيجة؛ لكنهما لا يغنيان عن قياس الأداء على بيانات ممثِّلة.
اقرأ الإجابة كاملة ←مصادر البيانات والخصوصية والامتثال
تصف صفحة مصادر البيانات الإطار المتّبع لتوثيق فئات المصادر ومعايير الاختيار والترخيص والقيود الجغرافية أو المتعلقة بأنظمة الكتابة. ولا تنشر هذه الصفحة حاليًا قائمة مراجَعة بالمصادر. راجع تلك الصفحة وتواصل مع فريق الدعم بشأن متطلبات المصادر الخاصة بتكاملك؛ ولا تفترض مصدرًا أو حجمًا لمجموعة البيانات أو رقمًا للتغطية لم يُوثَّق.
اقرأ الإجابة كاملة ←كم مرة تُحدَّث بيانات الأسماء؟لا تذكر GenderAPI في صفحة مصادر البيانات الحالية جدول تحديث واحدًا لكل سجل اسم أو قاعدة معالجة. إذا كانت حداثة البيانات تؤثر في حالة استخدامك، فاسأل فريق الدعم عن مجموعة البيانات أو سير العمل المعني، وقيّم نتائج ممثِّلة. وتاريخ مراجعة الصفحة ليس دليلًا على تحديث جميع السجلات الأساسية في ذلك التاريخ.
اقرأ الإجابة كاملة ←أين أجد معلومات GDPR واتفاقية معالجة البيانات؟تصف سياسة الخصوصية ومعلومات GDPR واتفاقية معالجة البيانات وسجل المعالجين الفرعيين شروط المعالجة المنشورة والضمانات المطبّقة. راجع الوثائق الحالية وأي اتفاقية تنطبق على حسابك. وتواصل مع GenderAPI بشأن الأسئلة الخاصة بمؤسستك عن أدوار المعالجة أو نقل البيانات أو طلبات أصحاب البيانات؛ فالأسئلة الشائعة العامة لا تحل محل الاتفاقية المعمول بها.
اقرأ الإجابة كاملة ←تشغيل API والأخطاء والفوترة
استخدم Authorization: Bearer YOUR_API_KEY من شيفرة موثوقة تعمل على الخادم. وتتطلب طلبات POST في V2 أيضًا Content-Type: application/json. يقبل GET /api/v2/gender كذلك المفتاح في معامل الاستعلام، لكن الترويسات تُبقي بيانات الاعتماد خارج عناوين URL في المتصفح. قد تستخدم المفاتيح المفقودة أو غير الصالحة التنسيق أو غير المعروفة التجربة المشتركة حسب عنوان IP؛ لذا تحقّق في تكامل الحساب من أن قيمة meta.access.mode هي api_key. أما المفاتيح المعروفة المعطّلة أو المنتهية الصلاحية أو المقيّدة فلا تنتقل إلى التجربة.
اقرأ الإجابة كاملة ←كيف أتعامل مع حدود الطلبات وإعادة المحاولة؟يطبّق V2 حدودًا لمعدل الطلبات وللعمليات المتزامنة؛ فالتزم بـ HTTP 429 وRetry-After. كل تقدير يُعاد إرساله عملية جديدة تُحتسب رسومها بالطريقة المعتادة. لا تُعِد المحاولة تلقائيًا عند انتهاء المهلة أو فقدان الاستجابة أو عدم تأكيد الفوترة. افحص أولًا code وaction وmeta.usage.billing_status؛ وعند ظهور billing_reconciliation_required تواصل مع فريق الدعم وأرسل request_id. استخدم التراجع المحدود فقط عندما تكون الفوترة مؤكدة ويسمح action الموثّق بمحاولة جديدة.
اقرأ الإجابة كاملة ←كيف أفهم أخطاء V2؟تستخدم أخطاء API في V2 رموز حالة HTTP للأخطاء وتنسيق RFC 9457 Problem Details مع حقلين ثابتين هما code وaction. اعتمد على هذين الحقلين بدلًا من مطابقة نص detail، واحتفظ بـ request_id لفريق الدعم. النتيجة الناجحة غير المعروفة ليست خطأً. وقد تتضمن استجابات الطلبات المجمّعة أخطاءً في عناصر منفردة حتى مع HTTP 200. وقد يعيد الخادم الوكيل خطأً بغير تنسيق JSON، ولا يثبت فقدان الاستجابة أو تعذّر قراءتها عدم خصم الرسوم.
اقرأ الإجابة كاملة ←كيف أتحقق من الأرصدة المتبقية؟استدعِ GET /api/v2/usage باستخدام مفتاح Bearer API الخاص بك من شيفرة موثوقة تعمل على الخادم. هذا الطلب مجاني ويعيد data.remaining_credits؛ ومن دون مفتاح يُقرأ رصيد التجربة المشتركة حسب عنوان IP. يستخدم V1 وV2 رصيد الحساب نفسه. وفي استجابة التقدير، يبيّن meta.usage تكلفة تلك العملية والرصيد لحظة اكتمالها، وقد يتغير ذلك مع الطلبات المتزامنة. أبقِ بيانات الاعتماد خارج السجلات، ولا تعدّ قراءة الرصيد دليلًا على عدم احتساب رسوم طلب معيّن فُقدت استجابته.
اقرأ الإجابة كاملة ←كيف أنتقل بأمان من V1 إلى V2؟استخدم V2 للتكاملات الجديدة، وأبقِ عملاء V1 الحاليين على المسارات الموثّقة لهم حتى تقرر ترحيلهم. يتشارك الإصداران مفاتيح API والأرصدة، لكنهما يستخدمان حقول طلب وبنى استجابة وتنسيقات أخطاء مختلفة. اتبع دليل الترحيل، واختبر النتائج الناجحة وغير المعروفة والأخطاء، وحدّث الشيفرة التي تقرأ الاستجابة قبل تبديل نقاط النهاية. ويظل مرجع V1 متاحًا للتكاملات الحالية.
اقرأ الإجابة كاملة ←كيف أفحص الأخطاء وأراقب توفر الخدمة؟إذا فشلت الطلبات، فافحص رمز الخطأ المُعاد لتمييز أعطال الخدمة من المدخلات غير الصالحة أو مشكلات الوصول إلى الحساب أو نفاد الأرصدة أو حدود معدل الطلبات. راقب نجاح الطلبات وزمن الاستجابة في تكاملك. وتواصل مع فريق الدعم وأرسل request_id عند حدوث فشل غير مفسَّر أو عدم يقين بشأن الفوترة. استند إلى أدلة مراقبة مقيسة في أي ادعاء عن التوفر؛ فهذه الأسئلة الشائعة لا تذكر نسبة تشغيل مضمونة.
اقرأ الإجابة كاملة ←هل ما زلت تحتاج إلى مساعدة؟
أرسل مثالًا قابلًا لإعادة الإنتاج
أرسل نقطة النهاية ومعاملات الطلب والخطأ المُعاد، من دون مفتاح API للإنتاج أو بيانات شخصية حساسة.