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

> स्टैंडर्ड लाइब्रेरी पर आधारित उदाहरणों से Python में GenderAPI.io V2 कॉल करें। नाम, ईमेल पते और यूज़रनेम भेजें, मिले-जुले बैच प्रोसेस करें और data/meta फ़ील्ड पढ़ें।

Canonical HTML: https://www.genderapi.io/hi/integrations/python

Last reviewed: 2026-10-01

## रनटाइम और डाउनलोड करने लायक उदाहरण

Python 3.10+। डाउनलोड करने लायक HTTP इंटीग्रेशन उदाहरण; अलग से प्रकाशित SDK नहीं। GenderAPI.io के आधिकारिक SDK भी उपलब्ध हैं।

- [उदाहरण डाउनलोड करें](https://www.genderapi.io/examples/v2/genderapi_v2.py)
- [GenderAPI.io के आधिकारिक SDK](https://www.genderapi.io/hi/docs/v2/sdks)

## सर्वर पर चलने वाला 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 कोई मान्य कुंजी नहीं है। असली क्रेडेंशियल वर्शन कंट्रोल वाली फ़ाइलों, साझा नोटबुक या क्लाइंट ऐप्लिकेशन में न रखें। मॉड्यूल इंपोर्ट करने या डेमो विकल्पों के बिना उसे चलाने पर कोई अनुरोध नहीं भेजा जाता।

**Python एनवायरनमेंट कॉन्फ़िगर करें**

```bash
python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [genderapi_v2.py डाउनलोड करें](https://www.genderapi.io/examples/v2/genderapi_v2.py)
- [मुफ़्त उपयोग एंडपॉइंट से कुंजी जाँचें](https://www.genderapi.io/hi/docs/v2/authentication#environment-setup)

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

नीचे दिया गया कोड डाउनलोड की गई फ़ाइल के पास 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 ट्रायल क्रेडिट वापस नहीं मिलता।

**Python में एकल खोज**

```python
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"])
```

- [एकल अनुरोध के सभी फ़ील्ड](https://www.genderapi.io/hi/docs/v2/request-parameters)

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

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

| फ़ील्ड | इसे कैसे इस्तेमाल करें |
| --- | --- |
| `data.gender / data.result_status` | male या female सिर्फ़ identified होने पर इस्तेमाल करें। परिणाम अज्ञात हो, तो JSON का असली null मान वैसे ही रखें। |
| `data.name / data.match` | लौटाया गया नाम और चुना गया कैंडिडेट जाँचें। सबस्ट्रिंग मिलान से यह साबित नहीं होता कि इनपुट उसी पहले नाम वाले व्यक्ति का है। |
| `data.confidence / data.confidence_kind` | कॉन्फिडेंस स्कोर 0–1 के पैमाने पर या null होता है। observed_frequency संग्रहीत गिनतियों से आता है; model_reported AI का स्कोर है। हर प्रकार के लिए सीमा का अलग आकलन करें। |
| `data.source / data.sample_count` | dataset, ai और none में अंतर करें। AI परिणामों में संग्रहीत सैंपल गिनती नहीं होती। सैंपल गिनती मापी गई सटीकता नहीं है। |
| `meta.access.mode` | अकाउंट वाले इंटीग्रेशन में पक्का करें कि मान api_key है। कुंजी न होने या पहचानी न जाने पर साझा IP ट्रायल इस्तेमाल हो सकता है। |
| `meta.usage` | charged_credits और billing_status पढ़ें। सफल अज्ञात परिणाम पर शुल्क लगता है। रिस्पॉन्स खो जाने से यह साबित नहीं होता कि अनुरोध मुफ़्त था। |

- [रिस्पॉन्स फ़ील्ड और अज्ञात परिणाम](https://www.genderapi.io/hi/docs/v2/responses)
- [सटीकता और कॉन्फिडेंस स्कोर की व्याख्या](https://www.genderapi.io/hi/accuracy-methodology)
- [डेटा स्रोत और तारीख वाली डेटाबेस प्रोफ़ाइल](https://www.genderapi.io/hi/data-provenance)

## मिले-जुले बैच प्रोसेस करें और हर पंक्ति की 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 आइटम वाले समूहों में बाँटें और शुरुआत में एक बार में एक ही समूह भेजें। अगला समूह प्रोसेस करने से पहले हर रिस्पॉन्स और उससे जुड़ा उपयोग सेव करें। ट्रांसपोर्ट की त्रुटि, अकाउंट एक्सेस की त्रुटि या बिलिंग की पुष्टि न होने पर रुकें और पहले मौजूदा समूह की स्थिति समझें। अकाउंट की सीमाएँ जाँचने के बाद ही समूह एक साथ भेजें। बैच में आइटम की अधिकतम संख्या किसी खास प्रोसेसिंग क्षमता की गारंटी नहीं है।

**Python में बैच खोज**

```python
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)
```

- [बैच के इनपुट, परिणाम और बिलिंग](https://www.genderapi.io/hi/docs/v2/batch)

## तय करें कि 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 में बदल देता है।

| अनुरोध का विकल्प | व्यवहार | हर सफल अनुरोध पर क्रेडिट |
| --- | --- | --- |
| options.ai_mode: off | सिर्फ़ डेटासेट इस्तेमाल करें। | 1, अज्ञात परिणाम पर भी |
| options.ai_mode: fallback | पहले डेटासेट, फिर लिंग न मिलने पर सामान्य AI। एकल अनुरोध का डिफ़ॉल्ट यही है। | कुल 1, AI फ़ॉलबैक सहित |
| options.ai_mode: always | सीधे AI से पूछें। | 2 |
| forceToGenderize: true | पहले डेटासेट, फिर AI को निजी निकनेम या छद्मनाम समझने की अनुमति, असली पहले नाम के बिना भी। | डेटासेट से परिणाम मिलने पर 1; AI इस्तेमाल होने पर कुल 2 |

- [AI विकल्प और निकनेम का अनुमान](https://www.genderapi.io/hi/docs/v2/ai-options)
- [क्रेडिट और उपयोग](https://www.genderapi.io/hi/docs/v2/credits-and-usage)

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

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

लौटाया गया request_id और बिलिंग की स्थिति अपने काम के रिकॉर्ड के साथ सेव करें। त्रुटि ऑब्जेक्ट नियंत्रित विश्लेषण के लिए रिस्पॉन्स सुरक्षित रखता है, लेकिन उसमें मूल इनपुट हो सकता है: पूरे ऑब्जेक्ट, रिस्पॉन्स और API कुंजी को सामान्य लॉग फ़ाइलों में न लिखें।

| स्थिति | ऐप्लिकेशन में फ़ैसला |
| --- | --- |
| सफल अज्ञात परिणाम | null, reason और usage सुरक्षित रखें। यह पूरा हुआ और शुल्क वाला परिणाम है, अपने-आप दोबारा प्रयास करने लायक विफल पंक्ति नहीं। |
| 422 सत्यापन त्रुटि | Problem Details फ़ील्ड में बताई गई समस्या के अनुसार पहले इनपुट ठीक करें, फिर नया अनुरोध भेजें। |
| 401 / 403 | अकाउंट का एक्सेस या उपलब्ध बैलेंस जाँचें। वही अनुरोध दोबारा भेजने से समस्या हल नहीं होगी। |
| 429 | Retry-After हेडर हो, तो उसका पालन करें। त्रुटि और बिलिंग की स्थिति जाँचें, फिर अगले प्रयास की योजना सोच-समझकर बनाएँ। |
| नेटवर्क त्रुटि, टाइमआउट या न पढ़ा जा सकने वाला रिस्पॉन्स | दर्ज करें कि परिणाम और बिलिंग दोनों की पुष्टि नहीं हुई है। दोबारा भेजने से पहले स्थिति की जाँच करें। सर्वर जो प्रोसेसिंग पूरी कर चुका है, उसे क्लाइंट वापस नहीं ले सकता। |
| billing_status: unconfirmed | charged_credits और remaining_credits null हो सकते हैं। दोबारा प्रयास से पहले request_id के साथ सपोर्ट टीम से संपर्क करें। null को शून्य क्रेडिट से न बदलें। |
| बैच के कुछ आइटम में त्रुटि | पहले पूरे हुए आइटम सेव करें। विफल आइटम और उनकी बिलिंग जाँचें और पूरे बैच के बजाय सिर्फ़ दोबारा प्रयास के लायक त्रुटि वाले आइटम दोबारा भेजें। |

- [Problem Details और दोबारा प्रयास के फ़ैसले](https://www.genderapi.io/hi/docs/v2/errors-and-retries)
- [क्रेडिट और बिलिंग की पुष्टि](https://www.genderapi.io/hi/docs/v2/credits-and-usage)

## उदाहरण का नेटवर्क व्यवहार समझें

urllib का 10 सेकंड का टाइमआउट ब्लॉकिंग सॉकेट ऑपरेशन पर लागू होता है; यह पूरे अनुरोध की अवधि की पक्की ऊपरी सीमा नहीं है। उदाहरण HTTP रीडायरेक्ट बंद करता है, सफल JSON रिस्पॉन्स प्रोसेस करता है और HTTP Problem रिस्पॉन्स सुरक्षित रखता है। यह कभी अपने-आप दोबारा प्रयास नहीं करता।

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

**वैकल्पिक Python डेमो**

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

- [Python दस्तावेज़ीकरण: urllib.request](https://docs.python.org/3/library/urllib.request.html)
- [Python दस्तावेज़ीकरण: HTTPError](https://docs.python.org/3/library/urllib.error.html)

## Python में null की जगह None क्यों दिखता है?

Python का JSON डिकोडर null को None में बदल देता है। परिणाम सेव या एक्सपोर्ट करते समय इस अज्ञात मान को वैसा ही रखें; इसे डिफ़ॉल्ट लिंग या शून्य कॉन्फिडेंस से न बदलें।

## क्या अज्ञात परिणाम पर क्रेडिट लगता है?

हाँ। सफल सामान्य खोज पर 1 क्रेडिट लगता है, भले ही gender null हो। सामान्य स्वचालित AI फ़ॉलबैक इसी क्रेडिट में शामिल है। always मोड में 2 क्रेडिट लगते हैं; forceToGenderize के साथ डेटासेट से परिणाम मिलने पर 1 क्रेडिट और AI इस्तेमाल होने पर 2 क्रेडिट लगते हैं।

## क्या उदाहरण विफल अनुरोधों का दोबारा प्रयास करते हैं?

नहीं। हर नया अनुरोध एक अलग ऑपरेशन है। दोबारा भेजने का फ़ैसला करने से पहले त्रुटि, हर आइटम का परिणाम और बिलिंग की स्थिति जाँचें। रिस्पॉन्स न मिलने से यह साबित नहीं होता कि पिछला प्रयास मुफ़्त था।

## क्या कोई पैकेज इंस्टॉल करना होगा?

नहीं। उदाहरण सीधे इसी GenderAPI.io गाइड से डाउनलोड करें। चलते समय यह किसी बाहरी पैकेज पर निर्भर नहीं है और अलग से प्रकाशित SDK नहीं है। अगर आप मेंटेन किया जाने वाला पैकेज पसंद करते हैं, तो GenderAPI.io के आधिकारिक SDK उसी V2 API को कॉल करते हैं: Python के लिए pip install genderapi या JavaScript के लिए npm install genderapi। उदाहरण के कोड की समीक्षा करें और उसे अपने ऐप्लिकेशन के अनुसार बदलें। API के नियम GenderAPI.io V2 दस्तावेज़ीकरण में तय होते हैं।

## संदर्भ दस्तावेज़ीकरण

- [GenderAPI.io V2 प्रमाणीकरण](https://www.genderapi.io/hi/docs/v2/authentication)
- [V2 रिस्पॉन्स फ़ील्ड](https://www.genderapi.io/hi/docs/v2/responses)
- [बैच के परिणाम और सीमाएँ](https://www.genderapi.io/hi/docs/v2/batch)
- [त्रुटियाँ और दोबारा प्रयास का दस्तावेज़ीकरण](https://www.genderapi.io/hi/docs/v2/errors-and-retries)
- [GenderAPI.io के आधिकारिक SDK](https://www.genderapi.io/hi/docs/v2/sdks)