Dùng GenderAPI.io V2 với JavaScript và Node.js

Đặt tích hợp trên máy chủ Node.js của bạn

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 Node.js 22 trở lên và tải genderapi-v2.mjs vào dự án. Mô-đun ES này dùng fetch và AbortSignal.timeout có sẵn; không cần gói npm nào. Phần mở rộng .mjs cho phép import mô-đun từ một mô-đun ES khác mà không cần thay đổi package.json.

Đặt GENDERAPI_API_KEY trong môi trường máy chủ. Đừng đóng gói khóa vào React, Vue hay JavaScript chạy trên trình duyệt. Hãy để máy chủ của bạn xác thực người dùng ứng dụng và gọi GenderAPI.io. YOUR_API_KEY trong ví dụ bên dưới không phải khóa hợp lệ. Việc import mô-đun hoặc chạy mô-đun mà không có tùy chọn chạy rõ ràng sẽ không gửi yêu cầu nào.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

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

Gửi một yêu cầu JSON POST với chính sách AI rõ ràng

Lưu đoạn mã này thành single.mjs cạnh mô-đun đã tải xuống và chạy node single.mjs. Mã gửi các trường V2 type và value cùng options.ai_mode: off. Đọc kết quả ước tính trong response.data, còn thông tin yêu cầu và tính phí trong response.meta.

Một lần tra cứu hoàn tất tốn 1 tín dụng, kể cả khi gender là null; tên mẫu không bảo đảm một kết quả cụ thể.

Hàm trợ giúp yêu cầu chế độ AI rõ ràng và khóa gồm 24 ký tự thập lục phân, sau đó kiểm tra meta.access.mode có phải là api_key hay không. Phản hồi dùng thử thành công sẽ gây ra lỗi chế độ truy cập không khớp thay vì âm thầm tiếp tục. Máy chủ có thể đã trừ một tín dụng dùng thử trước khi hàm trợ giúp phát hiện sự không khớp đó.

import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}

• 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.

import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}

• Đầ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 JavaScript này luôn yêu cầu options.ai_mode. Để suy luận biệt danh, hãy gửi forceToGenderize: true cùng với options: { ai_mode: 'fallback' }.

• 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 thời gian chờ của fetch và các bước kiểm tra phản hồi

Thời gian chờ mặc định là 10.000 mili giây, dùng AbortSignal.timeout, bao gồm cả thời gian đọc nội dung phản hồi. Việc máy khách hủy yêu cầu không chứng minh rằng máy chủ đã ngừng xử lý hoặc ngừng tính phí. Mô-đun tắt chuyển hướng, phân biệt lỗi HTTP với phản hồi không đọc được và không bao giờ tự động thử lại.

Các kiểm thử dùng dữ liệu truyền tải giả lập kiểm tra phản hồi thành công, kết quả không xác định, yêu cầu hàng loạt có lỗi một phần, các trường hợp dự phòng về thông tin xác thực và lỗi. Các kiểm thử này không cần dự đoán thực hay thao tác tín dụng nào; chúng không phải phép đo chuẩn về tính sẵn sàng hay độ chính xác trong môi trường thực tế. 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í.

node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch

• Tài liệu tham khảo Node.js: fetch →
• Tài liệu tham khảo Node.js: AbortSignal.timeout →

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