API V2 के JSON रिस्पॉन्स और कॉन्फिडेंस स्कोर

JSON रिस्पॉन्स समझें

सफल एकल रिस्पॉन्स में data और meta होते हैं। नीचे दिया गया डेटासेट उदाहरण 1 अक्टूबर 2026 को API कुंजी से प्राप्त किया गया वास्तविक रिस्पॉन्स है; इसमें सिर्फ़ खाते का बैलेंस बदला गया है। यह प्रोडक्ट की मापी गई सटीकता नहीं दिखाता, और लाइव अनुरोध पर अलग परिणाम मिल सकता है। API कुंजी वाले अनुरोधों में access.mode: api_key होता है और सिर्फ़ ट्रायल वाले कोटा फ़ील्ड null होते हैं; IP ट्रायल वाले अनुरोधों में ट्रायल की सीमा और रीसेट समय के साथ ip_trial होता है।

{
  "data": {
    "input": {
      "type": "name",
      "value": "Rahul",
      "country": "IN"
    },
    "name": "rahul",
    "gender": "male",
    "country": "IN",
    "confidence": 0.9969837120450432,
    "confidence_kind": "observed_frequency",
    "sample_count": 4973,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "rahul",
      "method": "normalized",
      "scope": "country",
      "country": "IN"
    }
  },
  "meta": {
    "request_id": "6fa3245b-0947-4188-a31e-c1b8c4cff477",
    "duration_ms": 9,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

पूरे रिस्पॉन्स स्कीमा और बैच के उदाहरण

अनुमान के रिस्पॉन्स फ़ील्ड

फ़ील्ड	प्रकार	Nullable	उदाहरण	विवरण
`data.input`	`object`	नहीं	`{"type":"name","value":"Rahul","country":"IN"}`	इनपुट का प्रकार, मान और देश। forceToGenderize true होने पर शामिल होता है।
`data.name`	`string`	हाँ	`"rahul"`	मिलान किया गया या निकाला गया पहला नाम; उपलब्ध न होने पर null।
`data.gender`	`string`	हाँ	`"male"`	male, female या JSON null। यह अनुमान है, व्यक्ति की सत्यापित पहचान नहीं।
`data.result_status`	`string`	नहीं	`"identified"`	लिंग लौटाए जाने पर identified; नहीं तो unknown।
`data.reason`	`string`	हाँ	`null`	identified परिणामों में null। अज्ञात परिणाम के कारण: not_found, no_name_candidate, ambiguous या insufficient_evidence।
`data.confidence`	`number`	हाँ	`0.95`	0–1 स्कोर या null। null gender का कॉन्फिडेंस स्कोर भी null होता है।
`data.confidence_kind`	`string`	हाँ	`"observed_frequency"`	observed_frequency: डेटासेट की प्रमुख गिनती / कुल गिनती। model_reported: AI का स्कोर, कैलिब्रेटेड प्रायिकता नहीं। उपलब्ध न होने पर null।
`data.sample_count`	`integer`	हाँ	`1200`	डेटासेट के सैंपल का आकार या null। AI कोई सैंपल गिनती नहीं गढ़ता।
`data.source`	`string`	नहीं	`"dataset"`	dataset, ai या none।
`data.country`	`string`	हाँ	`"IN"`	dataset या ai_association से देश का संबंध, या null। इससे राष्ट्रीयता, निवास या जातीयता तय नहीं होती।
`data.country_source`	`string`	हाँ	`"dataset"`	देश के संबंध का स्रोत: dataset, ai_association या null।
`data.match`	`object`	नहीं	`{"name":"rahul","method":"normalized","scope":"country","country":"IN"}`	डेटासेट में मिला नाम, method (normalized, token, substring या model_inference), देश/वैश्विक दायरा और मिलान वाला देश। उपलब्ध न होने वाले साक्ष्य null होते हैं।

लौटाए गए इनपुट फ़ील्ड

फ़ील्ड	प्रकार	Nullable	उदाहरण	विवरण
`data.input.type`	`string`	नहीं	`"name"`	इनपुट की श्रेणी: name, email या username।
`data.input.value`	`string`	नहीं	`"Rahul"`	अनुमान के लिए भेजा गया मान।
`data.input.country`	`string`	हाँ	`"IN"`	भेजा गया देश का संदर्भ; न भेजे जाने पर null।
`data.input.forceToGenderize`	`boolean`	नहीं	`true`	सिर्फ़ निकनेम मोड चालू होने पर मौजूद। नहीं तो छोड़ दिया जाता है।

डेटासेट मिलान के फ़ील्ड

फ़ील्ड	प्रकार	Nullable	उदाहरण	विवरण
`data.match.name`	`string`	हाँ	`"rahul"`	चुना गया डेटासेट कैंडिडेट; कोई डेटासेट पंक्ति न चुनी गई हो तो null।
`data.match.method`	`string`	हाँ	`"normalized"`	normalized, token, substring या model_inference; उपलब्ध न होने पर null।
`data.match.scope`	`string`	हाँ	`"country"`	डेटासेट खोज के लिए country या global; AI या साक्ष्य न होने पर null।
`data.match.country`	`string`	हाँ	`"IN"`	चुनी गई डेटासेट पंक्ति का देश; वैश्विक पंक्तियों या AI के लिए null।

एक्सेस, बिलिंग और अनुरोध का मेटाडेटा

फ़ील्ड	प्रकार	Nullable	उदाहरण	विवरण
`meta.request_id`	`string`	नहीं	`"550e8400-e29b-41d4-a716-446655440000"`	इस HTTP प्रयास का यूनिक पहचानकर्ता; X-Request-ID में भी भेजा जाता है।
`meta.duration_ms`	`integer`	नहीं	`42`	मिलीसेकंड में अनुरोध प्रोसेस होने का समय।
`meta.access.mode`	`string`	नहीं	`"api_key"`	api_key, ip_trial या unauthenticated। पेड अकाउंट इस्तेमाल करते समय api_key की पुष्टि करें।
`meta.access.reason`	`string`	हाँ	`null`	IP ट्रायल पर जाने का कारण: api_key_missing, api_key_invalid या api_key_not_found; बाकी मामलों में null।
`meta.usage.charged_credits`	`integer`	हाँ	`1`	कुल कटे हुए क्रेडिट। शुल्क लगने से पहले या पूरे रिफ़ंड की पुष्टि के बाद शून्य; बिलिंग की पुष्टि न होने पर null।
`meta.usage.remaining_credits`	`integer`	हाँ	`99`	प्रक्रिया पूरी होने के समय का बैलेंस। नेगेटिव हो सकता है; उपलब्ध न होने या बिलिंग की पुष्टि न होने पर null।
`meta.usage.billing_status`	`string`	नहीं	`"confirmed"`	not_charged, confirmed या unconfirmed। विफल अनुमान का दोबारा प्रयास करने से पहले इसे जाँचें।
`meta.usage.resets_at`	`string`	हाँ	`"2026-09-27T12:00:00.000Z"`	UTC में IP ट्रायल रीसेट होने का समय (ISO 8601); API कुंजी वाले अकाउंट के लिए या पता न होने पर null।
`meta.usage.limit`	`integer`	हाँ	`10`	IP ट्रायल की सीमा; API कुंजी वाले अकाउंट के लिए null।
`meta.usage.period_seconds`	`integer`	हाँ	`86400`	सेकंड में IP ट्रायल की अवधि; API कुंजी वाले अकाउंट के लिए null।

सफल अज्ञात परिणाम

HTTP 200 का मतलब है कि प्रक्रिया पूरी हो गई; इससे लिंग मिलने की गारंटी नहीं होती। JSON null को male, female, खाली स्ट्रिंग या शून्य कॉन्फिडेंस स्कोर में बदलने के बजाय वैसे ही रखें। data.result_status और data.reason को HTTP त्रुटियों से अलग जाँचें।

1 अक्टूबर 2026 को प्राप्त, सिर्फ़ डेटासेट वाला यह वास्तविक उदाहरण source: none और reason: not_found लौटाता है और फिर भी इस पर 1 क्रेडिट लगता है। बराबर गिनती वाली डेटासेट पंक्ति reason: ambiguous लौटा सकती है, जिसमें sample_count बना रहता है। अज्ञात AI परिणाम में source: ai और reason: insufficient_evidence होता है।

{
  "data": {
    "input": {
      "type": "name",
      "value": "zzzxxyy",
      "country": null
    },
    "name": null,
    "gender": null,
    "country": null,
    "confidence": null,
    "confidence_kind": null,
    "sample_count": null,
    "source": "none",
    "result_status": "unknown",
    "reason": "not_found",
    "country_source": null,
    "match": {
      "name": null,
      "method": null,
      "scope": null,
      "country": null
    }
  },
  "meta": {
    "request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

कॉन्फिडेंस स्कोर और मिलान के साक्ष्य समझें

0.9 का कॉन्फिडेंस स्कोर 0–1 के पैमाने पर है। observed_frequency में इसका मतलब है चुने गए डेटासेट में प्रमुख गिनती को कुल गिनती से भाग देना; यह प्रोडक्ट की शुरू से अंत तक मापी गई सटीकता नहीं है। model_reported स्कोर AI देता है और यह डेटासेट की आवृत्तियों के आधार पर कैलिब्रेट नहीं किया गया है।

अपने ऐप्लिकेशन की कोई भी सीमा अपने आकलन डेटा और confidence_kind के आधार पर चुनें। डेटासेट और AI स्कोर की सीधी तुलना ऐसे न करें जैसे वे एक ही चीज़ मापते हों। AI परिणाम में match.name, match.scope और match.country null होते हैं, क्योंकि कोई डेटासेट पंक्ति नहीं चुनी गई; match.method का मान model_inference होता है।

पूरे नामों के लिए डेटासेट परिणाम पूरी स्ट्रिंग के बजाय उसके किसी हिस्से से आ सकता है। data.input भेजा गया मान सुरक्षित रखता है; data.name लौटाए गए नाम के बारे में और data.match कैंडिडेट और खोज के दायरे के बारे में बताता है।

तय करें कि आपका ऐप्लिकेशन आगे क्या करे

पहले अनुरोध और आइटम की त्रुटियाँ संभालें, फिर result_status जाँचें। एकल अनुमान के लिए data पढ़ें; बैच के लिए हर सफल आइटम के data पर यही फ़ैसला लागू करें। male या female लेबल ज़बरदस्ती लगाने के बजाय अज्ञात परिणामों को अपने ऐप्लिकेशन में वैसे ही रखें।

परिणाम	इसका मतलब	सुझाया गया तरीका
identified; gender: male या female	अनुमान से लिंग मिला, डेटासेट या AI के साक्ष्य के साथ।	उस confidence_kind के लिए आकलन की गई नीति लागू करें; source और मिलान के साक्ष्य सुरक्षित रखें।
unknown; reason: not_found	कोई भी संग्रहीत डेटासेट रिकॉर्ड पार्स किए गए कैंडिडेट से मेल नहीं खाया।	gender को null ही रहने दें। अलग AI विकल्पों के साथ जान-बूझकर भेजा गया अनुरोध शुल्क वाली नई प्रक्रिया है।
unknown; reason: no_name_candidate	डेटासेट पार्सिंग से इस्तेमाल करने लायक कोई नाम कैंडिडेट नहीं मिला।	null रहने दें; कोई भी अतिरिक्त अनुमान चुनने से पहले इनपुट का प्रकार और मान जाँचें।
unknown; reason: ambiguous	चुनी गई डेटासेट पंक्ति में पुरुष और महिला की गिनती बराबर है; sample_count फिर भी मौजूद हो सकता है।	बराबरी खुद न तोड़ें और null कॉन्फिडेंस स्कोर को शून्य में न बदलें।
unknown; reason: insufficient_evidence	AI ने प्रक्रिया पूरी की, लेकिन लिंग लौटाने के लिए पर्याप्त साक्ष्य नहीं मिले।	इसे पूरा हुआ अज्ञात परिणाम मानें, सेवा प्रदाता की विफलता या अपने-आप दोबारा प्रयास का मामला नहीं।
Problem Details या किसी आइटम का error	प्रक्रिया विफल हुई, उदाहरण के लिए ai_upstream_error या prediction_timeout की वजह से।	त्रुटि कोड और अनुरोध ID सुरक्षित रखें, बिलिंग जाँचें और दोबारा प्रयास के निर्देश अपनाएँ।

अपने आकलन के आधार पर सीमाएँ चुनें

कॉन्फिडेंस स्कोर की कोई ऐसी सार्वभौमिक सीमा नहीं है जिससे अनुमान सही हो जाए। अपने इस्तेमाल के प्रतिनिधि और स्वतंत्र रूप से लेबल किए गए उदाहरणों पर observed_frequency और model_reported का अलग-अलग आकलन करें। डेटासेट की आवृत्ति और AI का खुद बताया गया स्कोर अलग-अलग संकेत हैं, भले ही दोनों संयोग से 0.9 हों। मापें कि आपकी नीति कितनी बार जवाब देती है और उसके दिए गए अनुमान कितनी बार सही होते हैं; बाकी सभी मामलों के लिए अज्ञात परिणाम या समीक्षा का रास्ता रखें।

उदाहरण के लिए, अगर result_status का मान identified है लेकिन confidence_kind का मान model_reported है, तो डेटासेट की सीमा के बजाय AI के लिए आकलन की गई अपनी नीति लागू करें। अगर forceToGenderize इस्तेमाल हुआ था, तो name: null के साथ non-null gender मान्य है: असली पहला नाम निकाले बिना भी छद्मनाम से अनुमान लगाया जा सकता है। अनुमान से जवाब मिला या नहीं, यह तय करने के लिए सिर्फ़ name नहीं, बल्कि gender और result_status जाँचें। यह फिर भी एक अनुमान है, किसी व्यक्ति की पहचान का सत्यापन नहीं।