JavaScript और Node.js में GenderAPI.io V2 इस्तेमाल करें

इंटीग्रेशन को Node.js सर्वर पर रखें

यह गाइड Bearer हेडर में API कुंजी के साथ GenderAPI.io V2 एंडपॉइंट https://api.genderapi.io/api/v2/gender को कॉल करती है। Node.js 22 या उससे नया संस्करण इस्तेमाल करें और genderapi-v2.mjs अपने प्रोजेक्ट में डाउनलोड करें। यह ES मॉड्यूल नेटिव fetch और AbortSignal.timeout इस्तेमाल करता है; किसी npm पैकेज की ज़रूरत नहीं है। .mjs एक्सटेंशन की वजह से आप package.json बदले बिना इसे दूसरे ES मॉड्यूल से इंपोर्ट कर सकते हैं।

सर्वर के एनवायरनमेंट में GENDERAPI_API_KEY सेट करें। कुंजी को React, Vue या ब्राउज़र में चलने वाले किसी दूसरे JavaScript कोड में न रखें। अपने सर्वर से ऐप्लिकेशन के उपयोगकर्ताओं का प्रमाणीकरण कराएँ और GenderAPI.io को कॉल भी सर्वर से ही करें। नीचे के उदाहरणों में YOUR_API_KEY कोई मान्य कुंजी नहीं है; मॉड्यूल इंपोर्ट करने या साफ़ तौर पर दिए गए चलाने के विकल्पों के बिना उसे चलाने पर कोई अनुरोध नहीं भेजा जाता।

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

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

JSON और साफ़ तौर पर तय AI नीति के साथ POST अनुरोध भेजें

कोड को डाउनलोड किए गए मॉड्यूल के पास single.mjs के रूप में सेव करें और node single.mjs चलाएँ। यह अनुरोध V2 के type और value फ़ील्ड और options.ai_mode: off भेजता है। अनुमान response.data में होता है और अनुरोध और बिलिंग की जानकारी response.meta में।

पूरी हुई खोज पर 1 क्रेडिट लगता है, भले ही gender null हो; उदाहरण वाला नाम किसी खास परिणाम की गारंटी नहीं देता।

हेल्पर मॉड्यूल साफ़ तौर पर तय AI मोड और 24 अक्षरों वाली हेक्साडेसिमल कुंजी माँगता है और फिर जाँचता है कि meta.access.mode का मान api_key है। IP ट्रायल का सफल रिस्पॉन्स चुपचाप आगे बढ़ने के बजाय अनपेक्षित एक्सेस मोड की त्रुटि देता है। मॉड्यूल को यह अंतर पता चलने से पहले सर्वर एक IP ट्रायल क्रेडिट इस्तेमाल कर चुका हो सकता है।

import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}

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

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

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

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

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

import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}

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

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

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

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

JavaScript हेल्पर मॉड्यूल में options.ai_mode देना हमेशा ज़रूरी है। निकनेम के अनुमान के लिए forceToGenderize: true और options: { ai_mode: 'fallback' } दोनों भेजें।

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

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

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

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

• Problem Details और दोबारा प्रयास के फ़ैसले →
• क्रेडिट और बिलिंग की पुष्टि →

fetch का टाइमआउट और रिस्पॉन्स की जाँच समझें

डिफ़ॉल्ट टाइमआउट 10,000 मिलीसेकंड है, जो AbortSignal.timeout से लागू होता है और इसमें रिस्पॉन्स बॉडी पढ़ने का समय भी शामिल है। क्लाइंट का अनुरोध रद्द करना यह साबित नहीं करता कि सर्वर पर प्रोसेसिंग या बिलिंग रुक गई। मॉड्यूल रीडायरेक्ट बंद करता है, HTTP त्रुटियों और न पढ़े जा सकने वाले रिस्पॉन्स में अंतर करता है और कभी अपने-आप दोबारा प्रयास नहीं करता।

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

node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch

• Node.js दस्तावेज़ीकरण: fetch →
• Node.js दस्तावेज़ीकरण: AbortSignal.timeout →

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