ก่อนส่งคำขอ
ส่ง JSON ไปยัง POST https://api.genderapi.io/api/v2/gender ใช้คีย์ API ที่มีอยู่ใน Authorization: Bearer YOUR_API_KEY และ Content-Type: application/json คำขอแต่ละรายการได้รับการประมวลผลแยกกัน
เลือกภาษาในตัวอย่างโค้ด และตั้งค่า GENDERAPI_API_KEY ในสภาพแวดล้อมของโปรเซสก่อนรัน หากไม่มีคีย์หรือระบบไม่รู้จักคีย์ อาจใช้การทดลองใช้ตาม IP ที่ใช้ร่วมกันแทน ดังนั้นเมื่อเชื่อมต่อบัญชีให้ตรวจสอบว่า meta.access.mode เป็น api_key
คาดการณ์เพศจากชื่อผู้ใช้หรือชื่อเล่น
| พารามิเตอร์ | ชนิดข้อมูล | จำเป็น | ค่าเริ่มต้น | คำอธิบาย |
|---|---|---|---|---|
type | string | ใช่ | — | ประเภทข้อมูลนำเข้า: name, email หรือ username |
value | string | ใช่ | — | จำเป็น ความยาว 1–254 อักขระ ต้องไม่ว่างและไม่มีอักขระควบคุม ค่าอีเมลต้องมีรูปแบบอีเมลที่ถูกต้อง |
country | string | ไม่ | — | รหัส ISO 3166-1 alpha-2 ตัวพิมพ์ใหญ่ ไม่บังคับ เช่น TR หรือ US การค้นหาตามประเทศอาจใช้ชุดข้อมูลส่วนกลางแทนได้ |
forceToGenderize | boolean | ไม่ | false | ค้นหาในชุดข้อมูลก่อน แล้วใช้ AI ที่ตีความชื่อเล่นหากยังระบุเพศไม่ได้ รองรับ name, email และ username |
options | object | ไม่ | — | ออบเจ็กต์ที่เก็บตัวเลือก AI ของข้อมูลนำเข้าแต่ละรายการ |
options.ai_mode | string | ไม่ | fallback | ค่าที่อนุญาต: off, fallback, always หากใช้ forceToGenderize: true ให้ละฟิลด์นี้หรือใช้ fallback |
id | string | ไม่ | — | ตัวระบุใน JSON ของ POST ความยาว 1–64 อักขระ ไม่บังคับ ส่งคืนคู่กับผลลัพธ์แต่ละรายการของคำขอแบบกลุ่ม และต้องไม่ซ้ำกันภายในคำขอแบบกลุ่มเดียวกัน คำขอเดี่ยวรับค่านี้ได้แต่ไม่ส่งคืน ไม่รองรับในคิวรีของ GET |
ใช้ type: username สำหรับชื่อบัญชีและชื่อเล่น ตั้งค่า forceToGenderize เป็น true เมื่อต้องการให้คาดการณ์จากความหมายของชื่อเล่น เช่น prenses แม้จะดึงชื่อจริงออกมาไม่ได้ ระบบยังค้นหาในชุดข้อมูลก่อน การคาดการณ์จากชื่อเล่นอาจส่งคืนเพศที่ไม่ใช่ null พร้อม name: null
เลือกภาษาโปรแกรม ตั้งค่าคีย์ API จากนั้นรันตัวอย่างบนเซิร์ฟเวอร์ของคุณ
คำขอคาดการณ์ทุกครั้งเป็นงานใหม่ที่มีการหักเครดิต รวมถึงคำขอที่ส่งซ้ำ ตัวอย่างเหล่านี้ไม่ส่งคำขอซ้ำโดยอัตโนมัติ ตรวจสอบสถานะการหักเครดิตก่อนส่งคำขออีกครั้ง
ก่อนรัน: การเข้าถึงและการจัดการข้อผิดพลาด
รันตัวอย่างเหล่านี้บนเซิร์ฟเวอร์ของคุณ ตั้งค่า GENDERAPI_API_KEY ในสภาพแวดล้อมของโปรเซสเป็นคีย์ API ที่มีอยู่ ตรวจสอบว่า meta.access.mode เป็น api_key เพราะคีย์ที่ระบบไม่รู้จักอาจทำให้ใช้การทดลองใช้ตาม IP แทน
การตอบกลับ JSON ที่มี HTTP 4xx และ 5xx จะคงเนื้อหาข้อผิดพลาดไว้และจบด้วยสถานะการออกที่ไม่ใช่ศูนย์ ตรวจสอบ code, action และ meta.usage.billing_status ก่อนส่งคำขอซ้ำ
คู่มือข้อผิดพลาดและการส่งคำขอซ้ำ →cURL 7.76+ ในเชลล์ POSIX รันในเทอร์มินัล เอกสารของรันไทม์
Node.js 22+ พร้อม fetch ในตัว บันทึกเป็น example.mjs แล้วรัน node example.mjs เอกสารของรันไทม์
Python 3.10+ พร้อมไลบรารีมาตรฐาน บันทึกเป็น example.py แล้วรัน python3 example.py เอกสารของรันไทม์
PHP 8+ พร้อมส่วนขยาย cURL บันทึกเป็น example.php แล้วรัน php example.php เอกสารของรันไทม์
Java 17+ พร้อมไคลเอนต์ HTTP มาตรฐาน บันทึกเป็น GenderApiExample.java แล้วรัน java GenderApiExample.java เอกสารของรันไทม์
แอปพลิเคชันคอนโซล .NET 8+ ใช้เป็น Program.cs ในโปรเจกต์คอนโซล แล้วรัน dotnet run เอกสารของรันไทม์
Go 1.22+ พร้อมไลบรารีมาตรฐาน บันทึกเป็น main.go แล้วรัน go run main.go เอกสารของรันไทม์
ตัวอย่างการตอบกลับ
นี่คือการตอบกลับจริงที่บันทึกเมื่อวันที่ 1 ตุลาคม 2026 ด้วยคีย์ API โดยแทนที่เฉพาะยอดคงเหลือของบัญชีเท่านั้น การตอบกลับนี้ไม่ใช่ตัววัดความแม่นยำ และคำขอจริงอาจได้ผลลัพธ์ที่ต่างออกไป คำขอที่ใช้คีย์ API จะรายงาน meta.access.mode: api_key และฟิลด์โควตาที่ใช้เฉพาะการทดลองใช้จะเป็น null ส่วนคำขอแบบทดลองใช้ตาม IP จะรายงาน ip_trial อ่าน data เพื่อดูผลการคาดการณ์ และอ่าน meta.usage เพื่อดูผลการหักเครดิตของงาน
{
"data": {
"input": {
"type": "username",
"value": "prenses",
"country": "TR",
"forceToGenderize": true
},
"name": "prenses",
"gender": "female",
"country": "TR",
"confidence": 0.9456521739130435,
"confidence_kind": "observed_frequency",
"sample_count": 184,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "prenses",
"method": "normalized",
"scope": "country",
"country": "TR"
}
},
"meta": {
"request_id": "a799faa4-bc1a-4537-90b3-2c1b60205499",
"duration_ms": 15,
"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 ได้ | ตัวอย่าง | คำอธิบาย |
|---|---|---|---|---|
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 |
อ่านผลการคาดการณ์จากชื่อเล่น
ตัวอย่างนี้ใช้ forceToGenderize: true หากชุดข้อมูลระบุเพศได้จะใช้ 1 เครดิต หากระบุไม่ได้ API จะให้ AI ตีความนามแฝงและหักรวม 2 เครดิตสำหรับงานที่สำเร็จ รวมถึงผลลัพธ์ที่ไม่ทราบ ให้ละ ai_mode หรือตั้งเป็น fallback เพราะ off และ always ขัดแย้งกับ forceToGenderize และจะส่งคืน 422
ในโหมดชื่อเล่น เพศที่คาดการณ์ได้พร้อม name: null ถือว่าถูกต้อง หมายความว่าไม่ได้ดึงชื่อจริงออกมา ไม่ใช่ข้อผิดพลาดของตัวแยกวิเคราะห์ เมื่อ AI ส่งคืนเพศ ผลลัพธ์จะมี sample_count: null และ confidence_kind: model_reported คะแนนนี้ไม่ใช่ความน่าจะเป็นที่ปรับเทียบแล้วหรือการยืนยันตัวตน
หากไม่ใช้ forceToGenderize การค้นหาชื่อผู้ใช้แบบเดี่ยวยังใช้ AI สำรองแบบปกติเป็นค่าเริ่มต้น รวมทั้งหมด 1 เครดิต แต่ต้องมีชื่อจริงที่ใช้ได้ ใช้ options.ai_mode: off หากต้องการประมวลผลเฉพาะชุดข้อมูล