استخدام GenderAPI.io V2 مع Python

جهّز مشروع Python يعمل على الخادم

يستدعي هذا الدليل نقطة النهاية https://api.genderapi.io/api/v2/gender في GenderAPI.io V2 باستخدام مفتاح API في ترويسة Bearer. استخدم Python 3.10 أو إصدارًا أحدث، ونزّل genderapi_v2.py إلى مشروعك. يستخدم المثال urllib.request وjson من المكتبة القياسية في Python؛ ولا يحتاج إلى أي حزمة pip.

اضبط GENDERAPI_API_KEY في بيئة الخادم. العنصر النائب YOUR_API_KEY في الأمثلة أدناه ليس مفتاحًا صالحًا. أبقِ بيانات الاعتماد الحقيقية خارج الملفات المُودَعة في نظام التحكم بالإصدارات، وخارج الدفاتر التي تشاركها، وخارج التطبيقات التي تعمل لدى العميل. لا يرسل استيراد الوحدة أو تشغيلها دون خيار عرض توضيحي أي طلب.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• تنزيل genderapi_v2.py ←
• تحقّق من مفتاحك عبر نقطة نهاية الاستخدام المجانية ←

أرسل طلبًا واحدًا يعتمد صراحةً على مجموعة البيانات فقط

احفظ الكود التالي باسم single.py بجوار الملف الذي نزّلته، ثم شغّل python3 single.py. ترسل الدالة المساعدة type: name وvalue: Alice وoptions.ai_mode: off بتنسيق JSON. اقرأ التقدير من data، وتفاصيل الطلب والخصم من meta. يستهلك الاستدعاء الناجح رصيدًا واحدًا، بما في ذلك النتيجة غير المعروفة؛ ولا يضمن الاسم المستخدم في المثال الحصول على تقدير.

تقبل make_item القيم name أو email أو username، وتتطلب تحديد وضع الذكاء الاصطناعي صراحةً. أضف country فقط عندما يتوفر لديك سياق ذو صلة. تتطلب الدالة المساعدة مفتاح API سداسي عشريًا من 24 حرفًا قبل الإرسال. وهذا يتحقق من الصيغة، لا من وجود المفتاح. كما ترفض الاستجابات الناجحة من التجربة حسب عنوان IP بوصفها عدم تطابق في نمط الوصول؛ ويجري هذا الفحص بعد وصول الاستجابة، لذا لا يمكنه التراجع عن رصيد التجربة المستهلك.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• كل حقول الطلب الفردي ←

احفظ النتيجة مع أدلتها

الارتباط المُستنتج ليس الجنس الذي يصرّح به الشخص. احفظ المُدخل الأصلي والأدلة المُعادة وما صرّح به الشخص كلًّا على حدة. النتيجة غير المعروفة نتيجة صالحة، ولا ينبغي أن تتحول في تطبيقك إلى فئة مُخمَّنة.

• حقول الاستجابة والنتائج غير المعروفة ←
• شرح الدقة ودرجة الثقة ←
• مصادر البيانات وملف قاعدة البيانات المؤرَّخ ←

عالج طلبًا مجمّعًا مختلطًا واحتفظ بمعرّفات الصفوف

يعالج GenderAPI.io V2 الطلبات المجمّعة المختلطة عبر POST https://api.genderapi.io/api/v2/gender/batch: حتى 50 عنصرًا مع مفتاح حساب، أو حتى 10 عناصر في التجربة حسب عنوان IP. تتطلب هذه الأمثلة مفتاح حساب. أعطِ كل عنصر قيمة id ثابتة وفريدة ووضع ذكاء اصطناعي محددًا صراحةً. يمكن أن يجمع الطلب المجمّع بين الأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين، مع سياق country اختياري لكل عنصر.

اقرأ كل عنصر في data والملخص في meta.summary. قد تتضمن استجابة HTTP 200 أخطاء في بعض العناصر؛ وقد يعيد الطلب المجمّع الذي فشلت كل عناصره استجابة Problem على المستوى الأعلى تتضمن النتائج. تُحتسب النتائج غير المعروفة الناجحة ضمن succeeded. ويتيح لك index وid الأصليان ربط كل نتيجة بالصف المصدر الصحيح.

في المهام الأكبر، قسّم المُدخلات إلى مجموعات لا تتجاوز 50 عنصرًا وأرسلها في البداية واحدة تلو الأخرى. احفظ كل استجابة واستخدامها قبل الانتقال إلى المجموعة التالية. توقّف عند أخطاء النقل أو الحساب أو عدم تأكيد الخصم، وسوِّ وضع المجموعة الحالية أولًا. لا تضف الإرسال المتزامن إلا بعد التحقق من حدود حسابك؛ فالحد الأقصى لحجم الطلب المجمّع ليس ضمانًا لسعة معالجة معينة.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• مُدخلات الطلبات المجمّعة ونتائجها وخصمها ←

متى تستخدم الذكاء الاصطناعي

forceToGenderize اختياري للأسماء وعناوين البريد الإلكتروني وأسماء المستخدمين. عند تفعيله، احذف ai_mode أو استخدم fallback؛ فلا يمكن الجمع بينه وبين off أو always، ويعيد ذلك 422. يكفي رصيد ابتدائي موجب لبدء الطلب، حتى لو جعل الخصم النهائي الرصيد سالبًا.

قد يعيد وضع الأسماء المستعارة جنسًا مع name: null، وقد يعطي أيضًا نتيجة غير معروفة. لا يضمن الرجوع العادي إلى الذكاء الاصطناعي ولا تفسير الأسماء المستعارة إجابة صحيحة أو قيمة غير null.

تتطلب وحدة Python المساعدة هذه تحديد ai_mode دائمًا. للسماح بتفسير الأسماء المستعارة، استخدم make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). وتحوّل الوحدة force_to_genderize إلى حقل JSON المسمى forceToGenderize.

• خيارات الذكاء الاصطناعي وتفسير الأسماء المستعارة ←
• الأرصدة والاستخدام ←

قرّر ما تفعله بعد الفشل

ترسل الأمثلة كل عملية مرة واحدة. ولا تعيد المحاولة تلقائيًا: فالإرسال الجديد عملية جديدة قابلة للخصم. تعني مهلة الانتظار أو فشل الاتصال أن العميل لم يتلقَّ استجابة كاملة؛ ولا يثبت ذلك أن الخادم توقف أو أنه لم تُخصم أرصدة.

احفظ معرّف الطلب المُعاد وحالة الخصم مع سجل المهمة. يحتفظ كائن الخطأ بالاستجابة للفحص المضبوط، لكنه قد يتضمن المُدخل الأصلي؛ فلا تكتب الكائن كاملًا أو الاستجابة أو مفتاح API في السجلات الروتينية.

• Problem Details وقرارات إعادة المحاولة ←
• الأرصدة وتأكيد الخصم ←

افهم سلوك النقل في هذا المثال

مهلة urllib البالغة 10 ثوانٍ تنطبق على عمليات المقبس الحاجبة، وليست حدًّا أقصى مضمونًا للمدة الكاملة للطلب. يعطّل المثال عمليات إعادة التوجيه في HTTP، ويحلّل استجابات JSON الناجحة، ويحتفظ باستجابات HTTP Problem. ولا يعيد المحاولة تلقائيًا أبدًا.

تستخدم الاختبارات المحلية استجابات نقل اصطناعية لحالات النجاح والنتائج غير المعروفة والطلبات المجمّعة الناجحة جزئيًا والوصول إلى الحساب والأخطاء. وهي تتحقق من منطق التحكم في المثال، لكنها لا تقيس توفر API الفعلي أو دقة التقدير أو زمن الاستجابة في الإنتاج. وكل أمر عرض توضيحي تشغّله صراحةً أدناه يرسل طلبه الخاص ويُخصم عنه.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• وثائق Python: urllib.request ←
• وثائق Python: HTTPError ←

الأسئلة الشائعة