استجابات API v2 JSON والثقة

فهم استجابة JSON

تحتوي الاستجابات الفردية الناجحة على data وmeta. إن استجابة مجموعة البيانات أدناه هي مثال توضيحي، وليست قياسًا لدقة المنتج أو وعدًا بنفس النتيجة المباشرة. ويظهر الوصول إلى IP التجريبي. الطلبات التي تمت مصادقتها باستخدام مفتاح الحساب ترجع access.mode: api_key؛ الحقول التي تنطبق على النسخة التجريبية فقط لها القيمة null.

الميدان [[م162]] المعنى	معنى
data.input	نوع الإدخال والقيمة والبلد. يتم تضمين forceToGenderize عند true.
data.name	الاسم المطابق أو المستخرج؛ null عند عدم توفر أي شيء.
data.gender	male أو female أو JSON null. هذا توقع وليس دليلاً على هوية الشخص.
data.result_status / reason	عندما يكون result_status هو identified، فإن reason هو null. عندما تكون الحالة unknown، يكون السبب هو not_found أو no_name_candidate أو ambiguous أو insufficient_evidence.
data.confidence	0–1 النتيجة أو null. الجنس الفارغ لديه ثقة null.
data.confidence_kind	observed_frequency: عدد الجنس السائد مقسومًا على العدد الإجمالي في مجموعة البيانات المحددة. model_reported: درجة الذكاء الاصطناعي، وليست احتمالية معايرة. القيمة هي null عندما لا تكون متاحة.
data.sample_count	حجم عينة مجموعة البيانات أو null. الذكاء الاصطناعي لا يخترع عدد العينات.
data.source	dataset أو ai أو none.
data.country / country_source	ارتباط الدولة من مجموعة البيانات أو ai_association أو null. لا يحدد الجنسية أو الإقامة أو العرق.
data.match	الاسم المطابق في مجموعة البيانات، وطريقة المطابقة (normalized أو token أو substring أو model_inference)، والنطاق (country أو global)، والبلد المطابق. تكون المعلومات غير المتاحة null.
meta.request_id / duration_ms	معرف العملية ومدة المعالجة بالمللي ثانية.
meta.access	كيفية منح حق الوصول وسبب التراجع عن المحاكمة إن وجد.
meta.usage	صافي الرسوم ورصيد وقت الإكمال وحالة الفوترة ومعلومات إعادة تعيين النسخة التجريبية.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

أكمل مخططات الاستجابة وأمثلة الدفعات

نتيجة ناجحة غير معروفة

HTTP 200 يعني أن العملية قد اكتملت؛ لا يضمن الجنس. احتفظ بـ JSON null بدلاً من تحويلها إلى male أو female أو سلسلة فارغة أو ثقة معدومة. تحقق من data.result_status وdata.reason بشكل منفصل عن أخطاء HTTP.

يُرجع هذا المثال لمجموعة البيانات فقط source: none وreason: not_found ولا يزال يتكلف رصيدًا واحدًا. إذا كانت أعداد مجموعة البيانات للجنسين متساوية، فيمكن أن تحتوي النتيجة على reason: ambiguous مع الحفاظ على sample_count. تستخدم نتيجة الذكاء الاصطناعي غير المعروفة 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": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

تفسير الثقة ومطابقة الأدلة

الثقة البالغة 0.9 تقع على مقياس من 0 إلى 1. بالنسبة إلى observed_frequency، فهذا يعني العدد السائد مقسومًا على إجمالي مجموعة البيانات المحددة؛ لا يتم قياس دقة المنتج من البداية إلى النهاية. يتم توفير درجة model_reported بواسطة الذكاء الاصطناعي ولا تتم معايرتها مقابل ترددات مجموعة البيانات.

اختر أي حد للتطبيق باستخدام بيانات التقييم الخاصة بك وconfidence_kind. لا تقم بترتيب مجموعة البيانات ونتائج الذكاء الاصطناعي بشكل مباشر كما لو أنها تقيس نفس الشيء. AI match.name وmatch.scope وmatch.country هي null لأنه لم يتم تحديد صف مجموعة بيانات؛ match.method هو model_inference.

بالنسبة للأسماء الكاملة، قد تأتي نتيجة مجموعة البيانات من مكون بدلاً من السلسلة الكاملة. يحتفظ data.input بالقيمة المقدمة؛ يصف data.name الاسم الذي تم إرجاعه، ويصف data.match المرشح ونطاق البحث.

فهم استجابة JSON

نتيجة ناجحة غير معروفة

تفسير الثقة ومطابقة الأدلة

أدلة ذات صلة