Dùng tên gốc mà không giả định một hệ chữ hay một kiểu đặt tên duy nhất
Bản demo này dùng một ví dụ bằng chữ Devanagari và ngữ cảnh quốc gia IN. Đây chỉ là một ví dụ đầu vào, không phải định nghĩa cho mọi tên được dùng ở Ấn Độ. API nhận chuỗi Unicode, nên bạn có thể gửi đúng cách viết có trong bản ghi mà không cần chuyển sang chữ Latin trước.
Khi tra cứu tập dữ liệu, API dùng các token đã chuẩn hóa, không chuyển đổi hệ chữ một cách tổng quát và không cam kết rằng cách viết Latin và cách viết bằng hệ chữ gốc sẽ dẫn đến cùng một bản ghi. Hãy lưu đầu vào gốc cùng với mọi tên được trả về. Việc chấp nhận một hệ chữ không có nghĩa là đã có độ chính xác được đo độc lập cho ngôn ngữ hoặc cộng đồng đó.
Đừng giả định token đầu tiên hay cuối cùng có vai trò cố định. V2 chọn bản ghi ứng viên hiện có với tổng số lượng đã lưu lớn nhất, thay vì bảo đảm một vị trí cụ thể cho tên riêng. Chữ cái viết tắt, token ngắn và việc không có kết quả khớp đã lưu có thể khiến tập dữ liệu không xác định được kết quả; AI dự phòng có thể thử toàn bộ giá trị đã gửi.
| Ví dụ đầu vào | Ý nghĩa | Cần kiểm tra |
|---|---|---|
प्रिया शर्मा | Ví dụ họ tên đầy đủ bằng chữ Devanagari | Nhiều token có thể trở thành ứng viên. Hãy kiểm tra tên và kết quả khớp được chọn thay vì cho rằng token đầu tiên luôn được chọn. |
Priya Sharma | Ví dụ bằng chữ Latin | Đây là một cách viết đầu vào riêng; không có cam kết khớp giống hệt nhau giữa các hệ chữ. |
A. Kumar | Chữ cái viết tắt và một token tên | Chữ cái viết tắt một ký tự không trở thành ứng viên trong tập dữ liệu. Kết quả khớp với token khác không chứng minh đó là tên riêng như dự định. |
country: IN | Ngữ cảnh demo: Ấn Độ | Hãy dùng ngữ cảnh này khi bản ghi của bạn có ngữ cảnh quốc gia liên quan, không chỉ vì tên xuất hiện trong hướng dẫn này. |
Chọn ngữ cảnh IN một cách có chủ đích
Bản demo trực tiếp gửi country: IN (Ấn Độ). API không chọn quốc gia này dựa trên hệ chữ của tên. Trong tích hợp của bạn, hãy dùng ngữ cảnh đã biết và có liên quan, hoặc bỏ qua country; đừng biến giá trị mẫu này thành mặc định cho mọi bản ghi.
Với mỗi ứng viên, khi tra cứu tập dữ liệu, API ưu tiên bản ghi theo quốc gia nếu có, nếu không sẽ xét bản ghi toàn cầu. Sau đó, API chọn ứng viên hiện có với tổng số lượng đã lưu lớn nhất. Hãy kiểm tra data.match.scope và data.match.country để biết phạm vi khớp thực tế. Một bản ghi theo quốc gia có số lượng bằng nhau sẽ không tự động bị thay bằng kết quả toàn cầu; chế độ fallback có thể dùng AI thay thế.
data.input.country mô tả ngữ cảnh của yêu cầu. data.country và data.country_source mô tả mối liên hệ được trả về. Đây là các trường khác nhau và không chứng minh quốc tịch, dân tộc hay nơi cư trú.
Gửi tên Ấn Độ bằng V2
Hãy chạy yêu cầu trên máy chủ của bạn, với GENDERAPI_API_KEY được đặt bằng khóa API hiện có. Ví dụ này bật rõ ràng AI dự phòng thông thường. Đây là minh họa một yêu cầu, không phải kết quả dự đoán hay độ bao phủ đã đo. Hãy dùng options.ai_mode: off để chỉ xử lý bằng tập dữ liệu.
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
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 | Cách sử dụng |
|---|---|
data.gender / data.result_status | Chỉ dùng male hoặc female khi kết quả là identified. Giữ nguyên giá trị JSON null gốc khi kết quả không xác định. |
data.name / data.match | Kiểm tra tên được trả về và ứng viên được chọn. Kết quả khớp theo chuỗi con không chứng minh rằng đầu vào thuộc về người có tên riêng đó. |
data.confidence / data.confidence_kind | Độ tin cậy nằm trên thang từ 0 đến 1 hoặc là null. observed_frequency dựa trên số lượng đã lưu; model_reported là điểm do AI đưa ra. Hãy đánh giá ngưỡng riêng cho từng loại. |
data.source / data.sample_count | Phân biệt dataset, ai và none. Kết quả AI không có số lượng mẫu đã lưu. Số lượng mẫu không phải là điểm độ chính xác đã đo. |
meta.access.mode | Xác nhận api_key với tích hợp dùng tài khoản. Khóa bị thiếu hoặc không được nhận diện có thể chuyển sang dùng thử theo IP dùng chung. |
meta.usage | Đọc charged_credits và billing_status. Kết quả không xác định thành công vẫn bị tính phí. Mất phản hồi không chứng minh rằng yêu cầu được miễn phí. |
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.
| Tùy chọn yêu cầu | Cách hoạt động | Tín dụng cho một lần tra cứu thành công |
|---|---|---|
| options.ai_mode: off | Chỉ dùng tập dữ liệu. | 1, kể cả kết quả không xác định |
| options.ai_mode: fallback | Tra tập dữ liệu trước, sau đó dùng AI thông thường khi không có giới tính được trả về. Đây là mặc định cho yêu cầu đơn lẻ. | Tổng cộng 1, đã gồm AI dự phòng |
| options.ai_mode: always | Dùng AI trực tiếp. | 2 |
| forceToGenderize: true | Tra tập dữ liệu trước, sau đó cho phép AI diễn giải biệt danh cá nhân hoặc bí danh, kể cả khi không có tên thật. | 1 khi tập dữ liệu cho ra kết quả; tổng cộng 2 nếu dùng AI |
Xử lý danh sách tên mà không mất ngữ cảnh
Dùng POST /api/v2/gender/batch cho tối đa 50 mục khi truy cập bằng khóa API đã đăng ký, hoặc 10 mục khi dùng thử theo IP. Hãy gán ID duy nhất cho từng mục và giữ lại giá trị gốc của từng dòng. Mỗi mục có thể có quốc gia và chính sách AI riêng; hãy bỏ qua country khi chưa biết quốc gia.
Khác với mặc định fallback của yêu cầu đơn lẻ, các mục trong yêu cầu hàng loạt mặc định chỉ dùng tập dữ liệu. Hãy đặt options.ai_mode: fallback cho từng mục cần AI. Kiểm tra mọi kết quả, kể cả sau HTTP 200, giữ nguyên kết quả không xác định và xem xét lỗi của từng mục cùng việc tính phí trước khi gửi lại. Mỗi mục thông thường thành công tốn một tín dụng; một yêu cầu HTTP hàng loạt không có nghĩa là chỉ tốn một tín dụng dự đoán.
Hiểu rõ dữ liệu bạn gửi đi
Bản demo trực tiếp chỉ gửi giá trị đã nhập đến GenderAPI.io khi bạn chủ động gửi. Nếu AI được gọi, type, value và ngữ cảnh quốc gia đã gửi sẽ được chuyển đến dịch vụ suy luận đã được cấu hình. Để chỉ dự đoán bằng tập dữ liệu, hãy dùng options.ai_mode: off mà không có forceToGenderize trong tích hợp của bạn.
Chính sách quyền riêng tư, thỏa thuận xử lý dữ liệu và danh sách bên xử lý dữ liệu phụ mô tả các điều kiện xử lý đã công bố. Kết quả là một mối liên hệ được suy luận; hãy ưu tiên thông tin do chính người đó cung cấp. Không dùng kết quả làm cơ sở cho các quyết định có ảnh hưởng quan trọng đến một cá nhân.
Câu hỏi thường gặp
Bản demo tên Ấn Độ có chỉ hỗ trợ tên tiếng Hindi không?
Bản demo dùng một ví dụ bằng chữ Devanagari, nhưng API chấp nhận chuỗi tên Unicode. Khả năng nhận đầu vào này không phải là tuyên bố về độ bao phủ đầy đủ của tập dữ liệu hay độ chính xác đã đo cho mọi ngôn ngữ được dùng ở Ấn Độ.
Cách viết Latin có trả về cùng kết quả với hệ chữ gốc không?
Điều đó không được bảo đảm. Khi tra cứu tập dữ liệu, API hiện không cung cấp sự tương đương chuyển tự tổng quát. Hãy lưu từng cách viết đã gửi cùng với thông tin source, kết quả khớp và độ tin cậy được trả về.
Độ chính xác có được đo cho mọi tên Ấn Độ không?
Trang này không công bố phép đo như vậy. Việc chấp nhận đầu vào, số lượng đã lưu và giá trị độ tin cậy không phải là một phép đo độ chính xác độc lập. Hãy xem trang phương pháp đánh giá để biết bằng chứng hiện có và những phép đo chưa được công bố.
Kết quả không xác định có tốn tín dụng không?
Kết quả không xác định thành công vẫn bị tính phí. Chế độ tập dữ liệu hoặc fallback thông thường tốn tổng cộng một tín dụng. Khi bật forceToGenderize, kết quả xác định được từ tập dữ liệu tốn một tín dụng, còn khi dùng AI thì tốn tổng cộng hai tín dụng, kể cả khi AI trả về kết quả không xác định. Lỗi có quy tắc tính phí riêng; hãy kiểm tra meta.usage.