Trước khi gửi yêu cầu
Gửi JSON đến POST https://api.genderapi.io/api/v2/gender. Dùng khóa API hiện có trong Authorization: Bearer YOUR_API_KEY và Content-Type: application/json. Mỗi yêu cầu được xử lý độc lập.
Chọn ngôn ngữ lập trình trong ví dụ mã. Đặt GENDERAPI_API_KEY trong biến môi trường của tiến trình trước khi chạy. Khóa bị thiếu hoặc không được nhận diện có thể dùng thử theo IP dùng chung, vì vậy khi tích hợp một tài khoản, hãy xác nhận meta.access.mode là api_key.
Giới tính từ tên người dùng hoặc biệt danh
| Tham số | Kiểu | Bắt buộc | Mặc định | Mô tả |
|---|---|---|---|---|
type | string | Có | — | Loại đầu vào: name, email hoặc username. |
value | string | Có | — | Bắt buộc. 1–254 ký tự; không để trống, không chứa ký tự điều khiển. Giá trị email phải đúng cú pháp email. |
country | string | Không | — | Mã ISO 3166-1 alpha-2 viết hoa, tùy chọn, ví dụ TR hoặc US. Tra cứu theo quốc gia có thể chuyển sang tập dữ liệu toàn cầu. |
forceToGenderize | boolean | Không | false | Tra tập dữ liệu trước, sau đó dùng AI có phân tích biệt danh nếu chưa xác định được. Hỗ trợ name, email và username. |
options | object | Không | — | Đối tượng chứa tùy chọn AI cho từng đầu vào. |
options.ai_mode | string | Không | fallback | Giá trị hợp lệ: off, fallback, always. Với forceToGenderize: true, bỏ qua trường này hoặc dùng fallback. |
id | string | Không | — | Mã định danh tùy chọn dài 1–64 ký tự trong JSON của POST. Được trả về cùng từng kết quả trong lô; phải là duy nhất trong một lô. Yêu cầu đơn lẻ chấp nhận trường này nhưng không trả lại. Không hỗ trợ trong truy vấn GET. |
Dùng type: username cho tên tài khoản và biệt danh. Đặt forceToGenderize thành true khi bạn muốn thử suy luận dựa trên ý nghĩa của biệt danh, chẳng hạn prenses, ngay cả khi không trích xuất được tên thật. Tập dữ liệu vẫn được tra trước. Dự đoán từ biệt danh có thể trả về gender khác null cùng name: null.
Chọn ngôn ngữ lập trình. Thiết lập khóa API, sau đó chạy ví dụ trên máy chủ của bạn.
Mỗi yêu cầu dự đoán là một thao tác mới bị tính phí, kể cả khi thử lại. Các ví dụ này không tự động thử lại. Kiểm tra trạng thái tính phí trước khi gửi yêu cầu khác.
Trước khi chạy: quyền truy cập và xử lý lỗi
Chạy các ví dụ này trên máy chủ của bạn. Đặt GENDERAPI_API_KEY trong biến môi trường của tiến trình bằng khóa API hiện có. Xác nhận meta.access.mode là api_key: khóa không được nhận diện có thể chuyển sang dùng thử theo IP.
Với phản hồi JSON HTTP 4xx và 5xx, ví dụ giữ nguyên nội dung lỗi và kết thúc với mã thoát khác 0. Kiểm tra code, action và meta.usage.billing_status trước khi thử lại.
Hướng dẫn về lỗi và thử lại →cURL 7.76+ trong shell POSIX. Chạy trong terminal. Tài liệu môi trường chạy
Node.js 22+; fetch tích hợp sẵn. Lưu thành example.mjs và chạy node example.mjs. Tài liệu môi trường chạy
Python 3.10+; thư viện chuẩn. Lưu thành example.py và chạy python3 example.py. Tài liệu môi trường chạy
PHP 8+ với tiện ích mở rộng cURL. Lưu thành example.php và chạy php example.php. Tài liệu môi trường chạy
Java 17+; HTTP client chuẩn. Lưu thành GenderApiExample.java và chạy java GenderApiExample.java. Tài liệu môi trường chạy
Ứng dụng console .NET 8+. Dùng làm Program.cs trong một dự án console, sau đó chạy dotnet run. Tài liệu môi trường chạy
Go 1.22+; thư viện chuẩn. Lưu thành main.go và chạy go run main.go. Tài liệu môi trường chạy
Ví dụ phản hồi
Đây là phản hồi thực được ghi lại ngày 1 tháng 10 năm 2026 bằng khóa API; chỉ số dư tài khoản đã được thay thế. Đây không phải là thước đo độ chính xác, và một yêu cầu trực tiếp có thể trả về kết quả khác. Yêu cầu dùng khóa API trả về meta.access.mode: api_key và null ở các trường hạn mức chỉ dành cho dùng thử; yêu cầu dùng thử theo IP trả về ip_trial. Đọc data để xem kết quả suy luận và meta.usage để biết kết quả tính phí của thao tác.
{
"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
}
}
}Trường phản hồi dự đoán
| Trường | Kiểu | Có thể là null | Ví dụ | Mô tả |
|---|---|---|---|---|
data.input | object | Không | {"type":"name","value":"Tuấn","country":"VN"} | Loại đầu vào, giá trị và quốc gia. forceToGenderize được đưa vào khi là true. |
data.name | string | Có | "tuấn" | Tên riêng đã khớp hoặc trích xuất được; null khi không có. |
data.gender | string | Có | "male" | male, female hoặc JSON null. Đây là suy luận, không phải danh tính cá nhân đã xác minh. |
data.result_status | string | Không | "identified" | identified khi có giới tính được trả về; nếu không thì unknown. |
data.reason | string | Có | null | null với kết quả identified. Lý do cho unknown: not_found, no_name_candidate, ambiguous hoặc insufficient_evidence. |
data.confidence | number | Có | 0.95 | Giá trị từ 0 đến 1 hoặc null. Khi gender là null, độ tin cậy cũng là null. |
data.confidence_kind | string | Có | "observed_frequency" | observed_frequency: số lượng của nhóm chiếm ưu thế trong tập dữ liệu chia cho tổng số. model_reported: điểm do AI đưa ra, không phải xác suất đã hiệu chỉnh. Là null khi không có. |
data.sample_count | integer | Có | 1200 | Cỡ mẫu trong tập dữ liệu hoặc null. AI không tự tạo ra số lượng mẫu. |
data.source | string | Không | "dataset" | dataset, ai hoặc none. |
data.country | string | Có | "VN" | Mối liên hệ quốc gia từ dataset hoặc ai_association, hoặc null. Không xác định quốc tịch, nơi cư trú hay dân tộc. |
data.country_source | string | Có | "dataset" | Nguồn của mối liên hệ quốc gia: dataset, ai_association hoặc null. |
data.match | object | Không | {"name":"tuấn","method":"normalized","scope":"country","country":"VN"} | Tên khớp trong tập dữ liệu, phương thức (normalized, token, substring hoặc model_inference), phạm vi country hoặc global và quốc gia đã khớp. Bằng chứng không có sẽ là null. |
Siêu dữ liệu về truy cập, tính phí và yêu cầu
| Trường | Kiểu | Có thể là null | Ví dụ | Mô tả |
|---|---|---|---|---|
meta.request_id | string | Không | "550e8400-e29b-41d4-a716-446655440000" | Mã định danh duy nhất của lần gửi HTTP này; cũng được gửi trong X-Request-ID. |
meta.duration_ms | integer | Không | 42 | Thời gian xử lý yêu cầu tính bằng mili giây. |
meta.access.mode | string | Không | "api_key" | api_key, ip_trial hoặc unauthenticated. Khi dùng tài khoản trả phí, hãy kiểm tra giá trị là api_key. |
meta.access.reason | string | Có | null | Lý do chuyển sang dùng thử: api_key_missing, api_key_invalid hoặc api_key_not_found; trường hợp khác là null. |
meta.usage.charged_credits | integer | Có | 1 | Số tín dụng thực tính. Bằng 0 trước khi tính phí hoặc sau khi hoàn trả toàn bộ đã được xác nhận; null khi việc tính phí chưa được xác nhận. |
meta.usage.remaining_credits | integer | Có | 99 | Số dư khi thao tác hoàn tất. Có thể âm; null khi không có thông tin hoặc việc tính phí chưa được xác nhận. |
meta.usage.billing_status | string | Không | "confirmed" | not_charged, confirmed hoặc unconfirmed. Kiểm tra trường này trước khi thử lại một dự đoán thất bại. |
meta.usage.resets_at | string | Có | "2026-09-27T12:00:00.000Z" | Thời điểm đặt lại dùng thử theo IP, theo UTC (ISO 8601); null với tài khoản dùng khóa API hoặc khi chưa biết. |
meta.usage.limit | integer | Có | 10 | Hạn mức dùng thử theo IP; null với tài khoản dùng khóa API. |
meta.usage.period_seconds | integer | Có | 86400 | Chu kỳ dùng thử theo IP tính bằng giây; null với tài khoản dùng khóa API. |
Đọc dự đoán từ biệt danh
Ví dụ dùng forceToGenderize: true. Tra cứu xác định được từ tập dữ liệu tốn 1 tín dụng. Nếu chưa xác định được, API yêu cầu AI diễn giải bí danh và tính tổng cộng 2 tín dụng cho thao tác thành công, kể cả khi kết quả không xác định. Bỏ qua ai_mode hoặc đặt thành fallback; off và always xung đột với forceToGenderize và trả về 422.
Ở chế độ biệt danh, giới tính được suy luận đi kèm name: null là hợp lệ. Điều này nghĩa là không trích xuất được tên thật; đây không phải lỗi phân tích. Kết quả AI có sample_count: null và confidence_kind: model_reported khi trả về giới tính. Giá trị này không phải xác suất đã hiệu chỉnh hay danh tính đã xác minh.
Khi không có forceToGenderize, một tra cứu tên người dùng đơn lẻ vẫn mặc định dùng AI dự phòng thông thường với tổng chi phí 1 tín dụng, nhưng cần có một tên thật dùng được. Dùng options.ai_mode: off để chỉ xử lý bằng tập dữ liệu.