ใช้ GenderAPI.io V2 ด้วย Python

ตั้งค่าโปรเจกต์ Python ฝั่งเซิร์ฟเวอร์

คู่มือนี้เรียก endpoint ของ GenderAPI.io V2 ที่ https://api.genderapi.io/api/v2/gender ด้วยคีย์ API แบบ Bearer ใช้ Python 3.10 ขึ้นไป และดาวน์โหลด genderapi_v2.py ไว้ในโปรเจกต์ ตัวอย่างใช้ urllib.request และ json จากไลบรารีมาตรฐานของ Python จึงไม่ต้องใช้แพ็กเกจ pip

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

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

ส่งคำขอแบบเฉพาะชุดข้อมูลที่ระบุชัดเจนหนึ่งครั้ง

บันทึกโค้ดด้านล่างเป็น single.py ไว้ข้างไฟล์ที่ดาวน์โหลด แล้วรัน python3 single.py โมดูลตัวช่วยส่ง type: name, value: Alice และ options.ai_mode: off เป็น JSON อ่านผลการคาดการณ์จาก data และข้อมูลคำขอและการหักเครดิตจาก meta

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

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

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

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

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

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

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

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

ข้อมูลนำเข้า ผลลัพธ์ และการหักเครดิตของคำขอแบบกลุ่ม

เลือกว่าจะใช้ AI เมื่อใด

forceToGenderize เป็นตัวเลือกที่ไม่บังคับสำหรับชื่อ ที่อยู่อีเมล และชื่อผู้ใช้ เมื่อเปิดใช้ ให้ละ ai_mode หรือใช้ fallback เพราะ off และ always ขัดแย้งกับตัวเลือกนี้และจะส่งคืน 422 ยอดคงเหลือเริ่มต้นที่เป็นบวกก็เพียงพอสำหรับเริ่มคำขอ แม้การหักเครดิตครั้งสุดท้ายจะทำให้ยอดคงเหลือต่ำกว่าศูนย์

โหมดชื่อเล่นอาจส่งคืนเพศพร้อม name: null และอาจส่งคืนผลลัพธ์ที่ไม่ทราบได้เช่นกัน ทั้ง AI สำรองแบบปกติและการคาดการณ์จากชื่อเล่นไม่รับประกันคำตอบที่ถูกต้องหรือไม่เป็น null

โมดูลตัวช่วย Python นี้กำหนดให้ต้องระบุ ai_mode เสมอ หากต้องการอนุญาตการคาดการณ์จากชื่อเล่น ให้ใช้ make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True) โมดูลตัวช่วยจะแปลง force_to_genderize เป็นฟิลด์ JSON forceToGenderize

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

ทำความเข้าใจการทำงานด้านการส่งของตัวอย่างนี้

การจำกัดเวลา 10 วินาทีของ urllib มีผลกับการทำงานของซ็อกเก็ตแบบบล็อก และไม่ใช่กำหนดเวลาที่รับประกันสำหรับเวลารวมทั้งหมดของคำขอ ตัวอย่างปิดการเปลี่ยนเส้นทาง HTTP แยกวิเคราะห์การตอบกลับ JSON ที่สำเร็จ และเก็บการตอบกลับ HTTP Problem ไว้ โดยไม่ส่งคำขอซ้ำอัตโนมัติ

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

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

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

เหตุใด Python จึงแสดง None แทน null?

ตัวถอดรหัส JSON ของ Python แปลง JSON null เป็น None คงค่าที่ไม่ทราบนี้ไว้ตามเดิม และอย่าเปลี่ยนเป็นเพศเริ่มต้นหรือค่าความเชื่อมั่น 0 เมื่อบันทึกหรือส่งออกผลลัพธ์

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

ใช้ การค้นหาแบบปกติที่สำเร็จใช้ 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 ที่ใช้