Python में GenderAPI.io V2 इस्तेमाल करें

सर्वर पर चलने वाला Python प्रोजेक्ट तैयार करें

यह गाइड Bearer हेडर में API कुंजी के साथ GenderAPI.io V2 एंडपॉइंट https://api.genderapi.io/api/v2/gender को कॉल करती है। Python 3.10 या उससे नया संस्करण इस्तेमाल करें और genderapi_v2.py अपने प्रोजेक्ट में डाउनलोड करें। उदाहरण Python की स्टैंडर्ड लाइब्रेरी के urllib.request और json इस्तेमाल करता है; किसी pip पैकेज की ज़रूरत नहीं है।

सर्वर के एनवायरनमेंट में GENDERAPI_API_KEY सेट करें। नीचे के उदाहरणों में YOUR_API_KEY कोई मान्य कुंजी नहीं है। असली क्रेडेंशियल वर्शन कंट्रोल वाली फ़ाइलों, साझा नोटबुक या क्लाइंट ऐप्लिकेशन में न रखें। मॉड्यूल इंपोर्ट करने या डेमो विकल्पों के बिना उसे चलाने पर कोई अनुरोध नहीं भेजा जाता।

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi_v2.py डाउनलोड करें →
• मुफ़्त उपयोग एंडपॉइंट से कुंजी जाँचें →

साफ़ तौर पर सिर्फ़ डेटासेट वाला अनुरोध भेजें

नीचे दिया गया कोड डाउनलोड की गई फ़ाइल के पास single.py के रूप में सेव करें और python3 single.py चलाएँ। हेल्पर मॉड्यूल JSON के रूप में type: name, value: Alice और options.ai_mode: off भेजता है। अनुमान data में होता है और अनुरोध और बिलिंग की जानकारी meta में।

सफल कॉल पर 1 क्रेडिट लगता है, भले ही परिणाम अज्ञात हो; उदाहरण वाला नाम किसी अनुमान की गारंटी नहीं देता। make_item name, email या username स्वीकार करता है और AI मोड साफ़ तौर पर देना ज़रूरी है। country तभी जोड़ें जब आपके पास उसका प्रासंगिक संदर्भ हो।

कुछ भी भेजने से पहले हेल्पर मॉड्यूल 24 अक्षरों वाली हेक्साडेसिमल API कुंजी माँगता है। यह कुंजी का प्रारूप जाँचता है, यह नहीं कि कुंजी मौजूद है या नहीं। मॉड्यूल IP ट्रायल के सफल रिस्पॉन्स को भी अनपेक्षित एक्सेस मोड मानकर अस्वीकार करता है। यह जाँच रिस्पॉन्स मिलने के बाद होती है, इसलिए पहले से इस्तेमाल हो चुका 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"])

• एकल अनुरोध के सभी फ़ील्ड →

परिणाम और उसके साक्ष्य को साथ रखें

अनुमानित संबंध किसी व्यक्ति का खुद बताया गया लिंग नहीं है। मूल इनपुट, लौटाए गए साक्ष्य और व्यक्ति की दी हुई जानकारी को अलग-अलग रखें। अज्ञात परिणाम एक मान्य परिणाम है; इसे आपके ऐप्लिकेशन में अंदाज़े से चुनी गई श्रेणी नहीं बनना चाहिए।

• रिस्पॉन्स फ़ील्ड और अज्ञात परिणाम →
• सटीकता और कॉन्फिडेंस स्कोर की व्याख्या →
• डेटा स्रोत और तारीख वाली डेटाबेस प्रोफ़ाइल →

मिले-जुले बैच प्रोसेस करें और हर पंक्ति की id सुरक्षित रखें

GenderAPI.io V2 मिले-जुले बैच POST https://api.genderapi.io/api/v2/gender/batch से प्रोसेस करता है: अकाउंट की कुंजी के साथ ज़्यादा से ज़्यादा 50 आइटम और IP ट्रायल में ज़्यादा से ज़्यादा 10। इन उदाहरणों के लिए अकाउंट की कुंजी ज़रूरी है। हर आइटम को एक स्थिर और यूनिक id और साफ़ तौर पर तय AI मोड दें। एक बैच में नाम, ईमेल पते और यूज़रनेम मिलाए जा सकते हैं और हर आइटम में वैकल्पिक 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)

• बैच के इनपुट, परिणाम और बिलिंग →

तय करें कि AI कब इस्तेमाल करना है

नामों, ईमेल पतों और यूज़रनेम के लिए forceToGenderize वैकल्पिक है। इसे चालू करने पर ai_mode छोड़ दें या fallback इस्तेमाल करें; off और always का इससे टकराव होता है और 422 लौटता है। अनुरोध शुरू करने के लिए पॉज़िटिव शुरुआती बैलेंस काफ़ी है, भले ही अंतिम शुल्क के बाद बैलेंस शून्य से नीचे चला जाए।

निकनेम मोड name: null के साथ लिंग लौटा सकता है। यह अज्ञात परिणाम भी लौटा सकता है। न सामान्य AI फ़ॉलबैक और न ही निकनेम का अनुमान सही या non-null जवाब की गारंटी देता है।

Python हेल्पर मॉड्यूल में ai_mode देना हमेशा ज़रूरी है। निकनेम के अनुमान के लिए make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True) इस्तेमाल करें। मॉड्यूल force_to_genderize को JSON फ़ील्ड forceToGenderize में बदल देता है।

• AI विकल्प और निकनेम का अनुमान →
• क्रेडिट और उपयोग →

तय करें कि त्रुटि के बाद क्या करना है

उदाहरणों में हर ऑपरेशन सिर्फ़ एक बार भेजा जाता है। वे कभी अपने-आप दोबारा प्रयास नहीं करते: दोबारा भेजना एक नया ऑपरेशन है और उस पर शुल्क लग सकता है। टाइमआउट या कनेक्शन की त्रुटि का मतलब है कि क्लाइंट को पूरा रिस्पॉन्स नहीं मिला। इससे यह साबित नहीं होता कि सर्वर ने प्रोसेसिंग रोक दी या क्रेडिट नहीं कटे।

लौटाया गया request_id और बिलिंग की स्थिति अपने काम के रिकॉर्ड के साथ सेव करें। त्रुटि ऑब्जेक्ट नियंत्रित विश्लेषण के लिए रिस्पॉन्स सुरक्षित रखता है, लेकिन उसमें मूल इनपुट हो सकता है: पूरे ऑब्जेक्ट, रिस्पॉन्स और 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 →

अक्सर पूछे जाने वाले सवाल