Dùng GenderAPI.io V2 với Python

Thiết lập dự án Python phía máy chủ

Hướng dẫn này gọi endpoint GenderAPI.io V2 https://api.genderapi.io/api/v2/gender bằng khóa API Bearer. Hãy dùng Python 3.10 trở lên và tải genderapi_v2.py vào dự án. Ví dụ dùng urllib.request và json trong thư viện chuẩn của Python; không cần gói pip nào.

Đặt GENDERAPI_API_KEY trong môi trường máy chủ. YOUR_API_KEY trong ví dụ bên dưới không phải khóa hợp lệ. Đừng đưa thông tin xác thực thật vào tệp được commit, notebook được chia sẻ hoặc ứng dụng phía máy khách. Việc import mô-đun hoặc chạy mô-đun mà không có tùy chọn demo sẽ không gửi yêu cầu nào.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Tải xuống genderapi_v2.py →
• Kiểm tra khóa bằng endpoint mức sử dụng miễn phí →

Gửi một yêu cầu chỉ dùng tập dữ liệu một cách rõ ràng

Lưu đoạn mã sau thành single.py cạnh tệp đã tải xuống và chạy python3 single.py. Hàm trợ giúp gửi type: name, value: Alice và options.ai_mode: off dưới dạng JSON. Đọc kết quả ước tính trong data, còn thông tin yêu cầu và tính phí trong meta.

Một lần gọi thành công tốn 1 tín dụng, kể cả khi kết quả không xác định; tên mẫu không bảo đảm sẽ có dự đoán. make_item chấp nhận name, email hoặc username và yêu cầu chế độ AI rõ ràng. Chỉ thêm country khi bạn có ngữ cảnh liên quan.

Hàm trợ giúp yêu cầu khóa API gồm 24 ký tự thập lục phân trước khi gửi. Việc này chỉ kiểm tra định dạng, không kiểm tra khóa có tồn tại hay không. Hàm cũng từ chối phản hồi thành công của dùng thử theo IP vì chế độ truy cập không khớp; việc kiểm tra này diễn ra sau khi nhận phản hồi, nên không hoàn lại tín dụng dùng thử đã bị trừ.

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"])

• Tất cả các trường của yêu cầu đơn lẻ →

Lưu kết quả cùng với bằng chứng của nó

Một mối liên hệ được suy luận không phải là giới tính do chính người đó tự công bố. Hãy lưu riêng đầu vào gốc, bằng chứng được trả về và mọi thông tin do người đó cung cấp. Kết quả không xác định là một kết quả hợp lệ; không nên biến nó thành một nhóm được đoán trong ứng dụng của bạn.

• Trường phản hồi và kết quả không xác định →
• Giải thích về độ chính xác và độ tin cậy →
• Nguồn dữ liệu và hồ sơ tập dữ liệu có ghi ngày →

Xử lý yêu cầu hàng loạt hỗn hợp và giữ ID của từng dòng

GenderAPI.io V2 xử lý yêu cầu hàng loạt hỗn hợp qua POST https://api.genderapi.io/api/v2/gender/batch: tối đa 50 mục với khóa API của tài khoản hoặc 10 mục khi dùng thử theo IP. Các ví dụ này cần khóa API của tài khoản. Hãy gán cho mỗi mục một id ổn định, duy nhất và một chế độ AI rõ ràng. Một yêu cầu hàng loạt có thể kết hợp tên, địa chỉ email và tên người dùng, với ngữ cảnh quốc gia tùy chọn cho từng mục.

Hãy đọc mọi mục trong data và phần tóm tắt trong meta.summary. HTTP 200 vẫn có thể chứa lỗi của từng mục; một yêu cầu hàng loạt mà mọi mục đều thất bại có thể trả về phản hồi Problem ở cấp cao nhất, kèm theo các kết quả. Kết quả không xác định thành công được tính là succeeded. index và id gốc giúp bạn gắn từng kết quả vào đúng dòng nguồn.

Với các tác vụ lớn hơn, hãy chia đầu vào thành các nhóm tối đa 50 mục và ban đầu gửi tuần tự. Lưu từng phản hồi và mức sử dụng của nó trước khi chuyển sang nhóm tiếp theo. Dừng lại khi gặp lỗi truyền tải, lỗi tài khoản hoặc lỗi chưa xác nhận tính phí, rồi đối chiếu nhóm hiện tại. Chỉ thêm xử lý song song sau khi đã kiểm tra giới hạn của tài khoản; số mục tối đa trong một yêu cầu hàng loạt không phải là cam kết về thông lượng.

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)

• Đầu vào, kết quả và tính phí của yêu cầu hàng loạt →

Chọn khi nào dùng AI

forceToGenderize là tùy chọn cho tên, địa chỉ email và tên người dùng. Khi bật trường này, hãy bỏ qua ai_mode hoặc dùng fallback; off và always xung đột với nó và trả về 422. Chỉ cần số dư ban đầu dương là đủ để bắt đầu một yêu cầu, kể cả khi lần tính phí cuối cùng làm số dư xuống dưới 0.

Chế độ biệt danh có thể trả về giới tính cùng name: null. Chế độ này cũng có thể trả về kết quả không xác định. Cả AI dự phòng thông thường lẫn suy luận biệt danh đều không bảo đảm câu trả lời đúng hoặc khác null.

Hàm trợ giúp Python này luôn yêu cầu ai_mode. Để cho phép suy luận biệt danh, hãy gọi make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Hàm trợ giúp ánh xạ force_to_genderize sang trường JSON forceToGenderize.

• Tùy chọn AI và suy luận biệt danh →
• Tín dụng và mức sử dụng →

Quyết định cách xử lý sau khi thất bại

Các ví dụ gửi mỗi thao tác một lần và không tự động thử lại: một lần gửi mới là một thao tác mới có tính phí. Hết thời gian chờ hoặc lỗi kết nối có nghĩa là máy khách không nhận được phản hồi đầy đủ; điều đó không chứng minh rằng máy chủ đã dừng xử lý hay không có tín dụng nào bị trừ.

Hãy lưu ID yêu cầu được trả về và trạng thái tính phí cùng với hồ sơ tác vụ. Đối tượng lỗi giữ lại phản hồi để kiểm tra có kiểm soát, nhưng có thể chứa đầu vào gốc; đừng ghi toàn bộ đối tượng, phản hồi hoặc khóa API vào nhật ký thông thường.

• Problem Details và quyết định thử lại →
• Tín dụng và xác nhận tính phí →

Hiểu cách truyền tải của ví dụ này

Thời gian chờ 10 giây của urllib áp dụng cho các thao tác socket chặn, không phải là giới hạn bảo đảm cho tổng thời gian của toàn bộ yêu cầu. Ví dụ tắt chuyển hướng HTTP, phân tích JSON thành công và giữ lại các phản hồi HTTP Problem. Ví dụ không bao giờ tự động thử lại.

Kiểm thử cục bộ dùng dữ liệu truyền tải giả lập cho các trường hợp thành công, không xác định, yêu cầu hàng loạt có lỗi một phần, quyền truy cập tài khoản và lỗi. Các kiểm thử này xác minh luồng điều khiển của ví dụ; chúng không đo tính sẵn sàng của API thực tế, độ chính xác suy luận hay độ trễ trong môi trường production. Mỗi lệnh demo tùy chọn bên dưới gửi yêu cầu riêng và bị tính phí.

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

• Tài liệu tham khảo Python: urllib.request →
• Tài liệu tham khảo Python: HTTPError →

Câu hỏi thường gặp