ใช้ GenderAPI.io V2 ด้วย JavaScript และ Node.js

เก็บการเชื่อมต่อไว้บนเซิร์ฟเวอร์ Node.js

คู่มือนี้เรียก endpoint ของ GenderAPI.io V2 ที่ https://api.genderapi.io/api/v2/gender ด้วยคีย์ API แบบ Bearer ใช้ Node.js 22 ขึ้นไป และดาวน์โหลด genderapi-v2.mjs ไว้ในโปรเจกต์ โมดูล ES นี้ใช้ fetch และ AbortSignal.timeout ที่มีในตัว จึงไม่ต้องใช้แพ็กเกจ npm นามสกุล .mjs ทำให้นำเข้าจากโมดูล ES อื่นได้โดยไม่ต้องแก้ package.json

ตั้งค่า GENDERAPI_API_KEY ในสภาพแวดล้อมของเซิร์ฟเวอร์ อย่ารวมคีย์ไว้ใน React, Vue หรือ JavaScript สำหรับเบราว์เซอร์ ให้ผู้ใช้แอปพลิเคชันยืนยันตัวตนกับเซิร์ฟเวอร์ของคุณเอง แล้วให้เซิร์ฟเวอร์นั้นเรียก GenderAPI.io YOUR_API_KEY ในตัวอย่างด้านล่างไม่ใช่คีย์ที่ใช้ได้ การนำเข้าโมดูลหรือรันโดยไม่มีตัวเลือกการรันที่ระบุชัดเจนจะไม่ส่งคำขอ

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

ส่ง JSON POST หนึ่งครั้งพร้อมนโยบาย AI ที่ระบุชัดเจน

บันทึกโค้ดเป็น 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;
}

ฟิลด์ทั้งหมดของคำขอเดี่ยว

เก็บผลลัพธ์ไว้คู่กับหลักฐาน

ความเชื่อมโยงที่ได้จากการคาดการณ์ไม่ใช่เพศที่บุคคลระบุด้วยตนเอง เก็บข้อมูลนำเข้าต้นฉบับ หลักฐานที่ส่งคืน และข้อมูลที่บุคคลนั้นให้ไว้แยกจากกัน ผลลัพธ์ที่ไม่ทราบเป็นผลลัพธ์ที่ถูกต้อง จึงไม่ควรเปลี่ยนเป็นหมวดหมู่ที่เดาขึ้นในแอปพลิเคชันของคุณ

ฟิลด์	วิธีใช้
`data.gender / data.result_status`	ใช้ male หรือ female เฉพาะเมื่อเป็น identified เมื่อผลลัพธ์เป็น unknown ให้คงค่า 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 ผลลัพธ์ที่ไม่ทราบซึ่งดำเนินการสำเร็จจะถูกหักเครดิต การไม่ได้รับการตอบกลับไม่ได้แปลว่าคำขอนั้นไม่มีค่าใช้จ่าย

ประมวลผลคำขอแบบกลุ่มที่ผสมประเภทและคง ID ของแถวไว้

GenderAPI.io V2 ใช้ POST https://api.genderapi.io/api/v2/gender/batch สำหรับคำขอแบบกลุ่มที่ผสมประเภท คีย์ของบัญชีส่งได้สูงสุด 50 รายการ ส่วนการทดลองใช้ตาม IP ส่งได้สูงสุด 10 รายการ ตัวอย่างนี้ต้องใช้คีย์ของบัญชี กำหนด id ที่คงที่และไม่ซ้ำกัน และโหมด AI ที่ชัดเจนให้ทุกรายการ คำขอแบบกลุ่มหนึ่งครั้งผสมชื่อ ที่อยู่อีเมล และชื่อผู้ใช้ได้ และแต่ละรายการระบุบริบทประเทศได้ตามต้องการ

อ่านทุกรายการใน 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 สำรองแบบปกติและการคาดการณ์จากชื่อเล่นไม่รับประกันคำตอบที่ถูกต้องหรือไม่เป็น null

โมดูลตัวช่วย JavaScript นี้กำหนดให้ต้องระบุ options.ai_mode เสมอ หากต้องการใช้การคาดการณ์จากชื่อเล่น ให้ส่ง forceToGenderize: true พร้อม options: { ai_mode: 'fallback' }

ตัวเลือกของคำขอ	การทำงาน	เครดิตสำหรับการค้นหาที่สำเร็จ
options.ai_mode: off	ใช้เฉพาะชุดข้อมูล	1 รวมถึงผลลัพธ์ที่ไม่ทราบ
options.ai_mode: fallback	ค้นหาในชุดข้อมูลก่อน แล้วใช้ AI แบบปกติเมื่อไม่ได้ผลเป็นเพศ เป็นค่าเริ่มต้นของคำขอเดี่ยว	รวม 1 รวมถึง AI สำรอง
options.ai_mode: always	ใช้ AI โดยตรง	2
forceToGenderize: true	ค้นหาในชุดข้อมูลก่อน แล้วให้ AI ตีความชื่อเล่นหรือนามแฝงของบุคคลได้แม้ไม่มีชื่อจริง	1 เมื่อชุดข้อมูลระบุเพศได้ หรือรวม 2 หากใช้ AI

ตัดสินใจว่าจะทำอะไรหลังความล้มเหลว

ตัวอย่างส่งแต่ละงานเพียงครั้งเดียวและไม่ส่งคำขอซ้ำโดยอัตโนมัติ การส่งอีกครั้งจะเป็นงานใหม่ที่ถูกหักเครดิต การหมดเวลาหรือการเชื่อมต่อล้มเหลวหมายความเพียงว่าไคลเอนต์ไม่ได้รับการตอบกลับที่สมบูรณ์ ไม่ใช่หลักฐานว่าเซิร์ฟเวอร์หยุดประมวลผลหรือไม่ได้หักเครดิต

เก็บ ID คำขอและสถานะการหักเครดิตที่ส่งคืนไว้คู่กับบันทึกงาน ออบเจ็กต์ข้อผิดพลาดเก็บการตอบกลับไว้เพื่อให้ตรวจสอบได้อย่างมีการควบคุม แต่ก็อาจมีข้อมูลนำเข้าดั้งเดิมอยู่ด้วย อย่าบันทึกออบเจ็กต์ทั้งหมด การตอบกลับ หรือคีย์ API ลงในล็อกทั่วไป

ผลลัพธ์	การตัดสินใจของแอปพลิเคชัน
ผลลัพธ์ที่ไม่ทราบซึ่งดำเนินการสำเร็จ	คง null, reason และ usage ไว้ตามเดิม นี่คือผลลัพธ์ที่เสร็จสมบูรณ์และถูกหักเครดิตแล้ว ไม่ใช่แถวที่ล้มเหลวซึ่งควรส่งซ้ำโดยอัตโนมัติ
ข้อผิดพลาดการตรวจสอบ 422	แก้ไขข้อมูลนำเข้าที่ฟิลด์ Problem Details ระบุก่อนส่งคำขอใหม่
401 / 403	ตรวจสอบสิทธิ์การเข้าถึงบัญชีหรือเครดิตที่ใช้ได้ การส่งคำขอเดิมซ้ำไม่ได้แก้ปัญหาที่ต้นเหตุ
429	ปฏิบัติตาม Retry-After หากมี ตรวจสอบข้อผิดพลาดและสถานะการหักเครดิต แล้วจึงกำหนดเวลาส่งซ้ำภายหลังอย่างระมัดระวัง
ข้อผิดพลาดของเครือข่าย การหมดเวลา หรือการตอบกลับที่อ่านไม่ได้	บันทึกว่ายังไม่ได้ยืนยันผลลัพธ์และการหักเครดิต กระทบยอดก่อนส่งอีกครั้ง ไคลเอนต์ยกเลิกงานที่เซิร์ฟเวอร์ทำเสร็จแล้วไม่ได้
billing_status: unconfirmed	charged_credits และ remaining_credits อาจเป็น null ติดต่อทีมช่วยเหลือพร้อม request_id ก่อนส่งซ้ำ อย่าเปลี่ยน null เป็น 0
บางรายการในคำขอแบบกลุ่มล้มเหลว	บันทึกรายการที่เสร็จสมบูรณ์ก่อน ตรวจสอบรายการที่ล้มเหลวและการหักเครดิตของรายการเหล่านั้น แล้วส่งอีกครั้งเฉพาะความล้มเหลวที่ส่งซ้ำได้ ไม่ใช่คำขอแบบกลุ่มทั้งชุด

ทำความเข้าใจการจำกัดเวลาของ 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

คำถามที่พบบ่อย

วางโค้ดนี้ใน JavaScript สำหรับเบราว์เซอร์ได้หรือไม่?

เก็บโค้ดไว้บนเซิร์ฟเวอร์ บันเดิลของเบราว์เซอร์จะเปิดเผยคีย์ API ให้ผู้ใช้เห็น ให้เบราว์เซอร์เรียกแบ็กเอนด์ของคุณเองที่ยืนยันตัวตนแล้ว และให้แบ็กเอนด์นั้นส่งคำขอไปยัง GenderAPI.io

ผลลัพธ์ที่ไม่ทราบใช้เครดิตหรือไม่?

ใช้ การค้นหาแบบปกติที่สำเร็จใช้ 1 เครดิตแม้ gender จะเป็น null โดยรวม AI สำรองแบบปกติไว้ในเครดิตนี้แล้ว โหมด always ใช้ 2 เครดิต ส่วน forceToGenderize ใช้ 1 เครดิตเมื่อได้ผลจากชุดข้อมูล หรือ 2 เครดิตเมื่อใช้ AI

ตัวอย่างนี้ส่งคำขอที่ล้มเหลวซ้ำหรือไม่?

ไม่ คำขอใหม่แต่ละครั้งเป็นงานแยกกัน ตรวจสอบข้อผิดพลาด ผลลัพธ์ของแต่ละรายการ และสถานะการหักเครดิตก่อนตัดสินใจส่งอีกครั้ง การไม่ได้รับการตอบกลับไม่ได้แปลว่าความพยายามครั้งก่อนไม่มีค่าใช้จ่าย

ต้องติดตั้งแพ็กเกจหรือไม่?

ไม่ ดาวน์โหลดตัวอย่างได้โดยตรงจากคู่มือ GenderAPI.io นี้ ตัวอย่างไม่ได้พึ่งพาแพ็กเกจของบุคคลที่สามขณะทำงาน และไม่ใช่ SDK ที่เผยแพร่แยกต่างหาก หากต้องการแพ็กเกจที่มีการดูแลอย่างต่อเนื่อง SDK อย่างเป็นทางการของ GenderAPI.io เรียกใช้ API V2 เดียวกัน โดยใช้ pip install genderapi สำหรับ Python หรือ npm install genderapi สำหรับ JavaScript ตรวจทานและปรับตัวอย่างให้เข้ากับแอปพลิเคชันของคุณ ข้อกำหนดของ API ยังคงกำหนดโดยเอกสาร GenderAPI.io V2

แหล่งอ้างอิง

เอกสาร API กำหนดคำขอและการตอบกลับ ส่วนเอกสารของสภาพแวดล้อมการทำงานอธิบายเครื่องมือ HTTP ที่ใช้