การตอบกลับ JSON และค่าความเชื่อมั่นใน API V2

ทำความเข้าใจการตอบกลับ JSON

การตอบกลับเดี่ยวที่สำเร็จประกอบด้วย data และ meta ตัวอย่างชุดข้อมูลต่อไปนี้เป็นการตอบกลับจริงที่บันทึกเมื่อวันที่ 1 ตุลาคม 2026 ด้วยคีย์ API โดยแทนที่เฉพาะยอดคงเหลือของบัญชีเท่านั้น ตัวอย่างนี้ไม่ได้แสดงความแม่นยำที่วัดได้ของผลิตภัณฑ์ และคำขอจริงอาจได้ผลลัพธ์ที่ต่างออกไป คำขอที่ใช้คีย์ API จะรายงาน access.mode: api_key และฟิลด์โควตาที่ใช้เฉพาะการทดลองใช้จะเป็น null ส่วนคำขอแบบทดลองใช้ตาม IP จะรายงาน ip_trial พร้อมขีดจำกัดการทดลองใช้และเวลารีเซ็ต

{
  "data": {
    "input": {
      "type": "name",
      "value": "สมชาย",
      "country": "TH"
    },
    "name": "สมชาย",
    "gender": "male",
    "country": "TH",
    "confidence": 0.9920948616600791,
    "confidence_kind": "observed_frequency",
    "sample_count": 253,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "สมชาย",
      "method": "normalized",
      "scope": "country",
      "country": "TH"
    }
  },
  "meta": {
    "request_id": "1ab0329f-45c4-4d23-9ff1-101193a422a3",
    "duration_ms": 13,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

สคีมาการตอบกลับฉบับเต็มและตัวอย่างคำขอแบบกลุ่ม

ฟิลด์การตอบกลับของการคาดการณ์

ฟิลด์	ชนิดข้อมูล	เป็น null ได้	ตัวอย่าง	คำอธิบาย
`data.input`	`object`	ไม่	`{"type":"name","value":"สมชาย","country":"TH"}`	ประเภท ค่า และประเทศของข้อมูลนำเข้า จะมี forceToGenderize ด้วยเมื่อเป็น true
`data.name`	`string`	ใช่	`"สมชาย"`	ชื่อจริงที่ตรงกันหรือที่ดึงออกมา เป็น null เมื่อไม่มี
`data.gender`	`string`	ใช่	`"male"`	male, female หรือ JSON null เป็นผลการคาดการณ์ ไม่ใช่ตัวตนของบุคคลที่ได้รับการยืนยัน
`data.result_status`	`string`	ไม่	`"identified"`	เป็น identified เมื่อส่งคืนเพศ มิฉะนั้นเป็น unknown
`data.reason`	`string`	ใช่	`null`	เป็น null สำหรับผลลัพธ์ identified เหตุผลของผลลัพธ์ที่ไม่ทราบ: not_found, no_name_candidate, ambiguous หรือ insufficient_evidence
`data.confidence`	`number`	ใช่	`0.95`	คะแนน 0–1 หรือ null เมื่อเพศเป็น null ค่าความเชื่อมั่นก็เป็น 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`	ใช่	`"TH"`	ความเชื่อมโยงกับประเทศจาก dataset หรือ ai_association หรือเป็น null ไม่ได้บ่งบอกสัญชาติ ถิ่นที่อยู่ หรือชาติพันธุ์
`data.country_source`	`string`	ใช่	`"dataset"`	แหล่งที่มาของความเชื่อมโยงกับประเทศ: dataset, ai_association หรือ null
`data.match`	`object`	ไม่	`{"name":"สมชาย","method":"normalized","scope":"country","country":"TH"}`	ชื่อที่ตรงกันในชุดข้อมูล วิธีจับคู่ (normalized, token, substring หรือ model_inference) ขอบเขต country/global และประเทศที่ตรงกัน หลักฐานที่ไม่มีจะเป็น null

ฟิลด์ข้อมูลนำเข้าที่ส่งคืน

ฟิลด์	ชนิดข้อมูล	เป็น null ได้	ตัวอย่าง	คำอธิบาย
`data.input.type`	`string`	ไม่	`"name"`	ประเภทข้อมูลนำเข้า: name, email หรือ username
`data.input.value`	`string`	ไม่	`"สมชาย"`	ค่าที่ส่งมาเพื่อคาดการณ์
`data.input.country`	`string`	ใช่	`"TH"`	บริบทประเทศที่ส่งมา เป็น null เมื่อไม่ได้ระบุ
`data.input.forceToGenderize`	`boolean`	ไม่	`true`	มีเฉพาะเมื่อเปิดโหมดชื่อเล่น มิฉะนั้นจะไม่มีฟิลด์นี้

ฟิลด์การจับคู่ชุดข้อมูล

ฟิลด์	ชนิดข้อมูล	เป็น null ได้	ตัวอย่าง	คำอธิบาย
`data.match.name`	`string`	ใช่	`"สมชาย"`	ชื่อตัวเลือกที่ถูกเลือกจากชุดข้อมูล เป็น null เมื่อไม่ได้เลือกแถวใดในชุดข้อมูล
`data.match.method`	`string`	ใช่	`"normalized"`	normalized, token, substring หรือ model_inference เป็น null เมื่อไม่มีข้อมูล
`data.match.scope`	`string`	ใช่	`"country"`	country หรือ global สำหรับการค้นหาในชุดข้อมูล เป็น null สำหรับ AI หรือเมื่อไม่มีหลักฐาน
`data.match.country`	`string`	ใช่	`"TH"`	ประเทศของแถวที่เลือกในชุดข้อมูล เป็น null สำหรับแถวส่วนกลางหรือ AI

เมทาดาทาของการเข้าถึง การหักเครดิต และคำขอ

ฟิลด์	ชนิดข้อมูล	เป็น null ได้	ตัวอย่าง	คำอธิบาย
`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`	เหตุผลที่ใช้การทดลองใช้แทน: 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"`	เวลารีเซ็ตการทดลองใช้ตาม IP ใน UTC (ISO 8601) เป็น null สำหรับบัญชีที่ใช้คีย์ API หรือเมื่อไม่ทราบ
`meta.usage.limit`	`integer`	ใช่	`10`	จำนวนเครดิตของการทดลองใช้ตาม IP เป็น null สำหรับบัญชีที่ใช้คีย์ API
`meta.usage.period_seconds`	`integer`	ใช่	`86400`	รอบเวลาของการทดลองใช้ตาม IP เป็นวินาที เป็น null สำหรับบัญชีที่ใช้คีย์ API

ผลลัพธ์ที่ไม่ทราบซึ่งดำเนินการสำเร็จ

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	เก็บรหัสข้อผิดพลาดและ รหัสคำขอ ตรวจสอบการหักเครดิต แล้วทำตามคู่มือการส่งคำขอซ้ำ

กำหนดเกณฑ์จากการประเมินของคุณเอง

ไม่มีเกณฑ์ค่าความเชื่อมั่นสากลที่ทำให้การคาดการณ์ถูกต้องเสมอ ประเมิน observed_frequency และ model_reported แยกกันด้วยตัวอย่างที่เป็นตัวแทนของกรณีใช้งานและติดป้ายกำกับอย่างเป็นอิสระ ความถี่จากชุดข้อมูลกับคะแนนที่ AI รายงานเองเป็นสัญญาณที่ต่างกัน แม้ทั้งสองค่าจะเป็น 0.9 เท่ากันก็ตาม วัดว่าเกณฑ์ของคุณให้คำตอบบ่อยเพียงใด และคำตอบที่ได้ถูกต้องบ่อยเพียงใด ส่วนกรณีอื่นให้คงเป็นผลลัพธ์ที่ไม่ทราบหรือส่งเข้าขั้นตอนตรวจทาน

ตัวอย่างเช่น หาก result_status เป็น identified แต่ confidence_kind เป็น model_reported ให้ใช้เกณฑ์สำหรับ AI ที่ประเมินแล้ว ไม่ใช่เกณฑ์ของชุดข้อมูล หากใช้ forceToGenderize ผลลัพธ์ที่มี name: null พร้อมเพศที่ไม่ใช่ null ถือว่าถูกต้อง เพราะนามแฝงคาดการณ์ได้โดยไม่ต้องดึงชื่อจริงออกมา ให้ดูจาก gender และ result_status ไม่ใช่ name อย่างเดียว เพื่อตัดสินว่าการคาดการณ์ได้คำตอบหรือไม่ ผลนี้ยังเป็นเพียงการประมาณ ไม่ใช่การยืนยันตัวตนของบุคคล