在 JavaScript 和 Node.js 中使用 GenderAPI.io V2

将集成保留在 Node.js 服务器上

本指南通过 Bearer 请求头中的 API 密钥调用 GenderAPI.io V2 端点 https://api.genderapi.io/api/v2/gender。请使用 Node.js 22 或更高版本，并把 genderapi-v2.mjs 下载到您的项目中。该 ES 模块使用原生的 fetch 和 AbortSignal.timeout；不需要任何 npm 软件包。由于使用 .mjs 扩展名，您无需修改 package.json 即可从其他 ES 模块导入它。

请在服务器环境中设置 GENDERAPI_API_KEY。不要把密钥放入 React、Vue 或任何其他在浏览器中运行的 JavaScript 代码。请让您的服务器对应用用户进行身份验证，并由服务器调用 GenderAPI.io。下面示例中的 YOUR_API_KEY 不是有效的密钥；导入该模块，或在没有显式运行选项的情况下执行它，都不会发送任何请求。

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• 下载 genderapi-v2.mjs →
• 使用免费的用量端点检查密钥 →

发送带有 JSON 和显式 AI 策略的 POST 请求

把代码保存为 single.mjs，放在下载的模块旁边，然后运行 node single.mjs。该请求会发送 V2 的 type 和 value 字段以及 options.ai_mode: off。预测位于 response.data 中，请求和计费信息位于 response.meta 中。

完成的查询消耗 1 个积分，即使 gender 为 null 也是如此；示例姓名并不保证得到特定的结果。

辅助模块要求显式的 AI 模式和 24 个字符的十六进制密钥，然后检查 meta.access.mode 的值是否为 api_key。IP 试用的成功响应会引发意外访问模式错误，而不是悄悄继续。在模块发现这一差异之前，服务器可能已经用掉了一个 IP 试用积分。

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;
}

• 单个请求的所有字段 →

将结果与其依据一起保存

推断出的关联并不是本人自述的性别。请把原始输入、返回的依据以及本人提供的信息分开保存。未知结果是有效的结果，不应在您的应用中变成一个猜测出来的类别。

• 响应字段与未知结果 →
• 准确性与置信度说明 →
• 数据来源与注明日期的数据库概况 →

处理混合批量请求，并保留每一行的 id

GenderAPI.io V2 通过 POST https://api.genderapi.io/api/v2/gender/batch 处理混合批量请求：使用账户密钥时最多 50 个条目，使用 IP 试用时最多 10 个。这些示例需要账户密钥。请为每个条目设置稳定且唯一的 id 和显式的 AI 模式。一个批量请求可以混合姓名、电子邮箱地址和用户名，每个条目都可以带有可选的 country 背景。

请逐条读取 data 中的条目，并读取 meta.summary 中的汇总。HTTP 200 响应中可能包含单个条目的错误；所有条目都失败的批量请求可能返回带有结果的顶层 Problem 响应。成功完成的未知结果计入 succeeded。借助 index 和 id，您可以把每个结果对应到正确的原始行。

请把较大的任务拆分为每组最多 50 个条目，开始时一次只发送一组。在处理下一组之前，保存每个响应及对应的用量。遇到传输错误、账户访问错误或未确认的计费时请停止，先弄清当前这一组的情况。只有在核实账户的限制之后，才并行发送。批量请求的最大条目数并不保证特定的处理能力。

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;
}

• 批量请求的输入、结果与计费 →

决定何时使用 AI

forceToGenderize 对姓名、电子邮箱地址和用户名都是可选的。启用时，请省略 ai_mode 或使用 fallback；off 和 always 不能与此选项组合，否则会返回 422。起始余额为正即可发起请求，即使最终扣费后余额变为负数。

昵称模式可能在 name: null 的同时返回性别，也可能得到未知结果。无论是普通的 AI 回退还是昵称解读，都不能保证答案正确或返回非 null 的值。

JavaScript 辅助模块始终要求提供 options.ai_mode。如需昵称解读，请同时发送 forceToGenderize: true 和 options: { ai_mode: 'fallback' }。

• AI 选项与昵称解读 →
• 积分与用量 →

决定出错后的处理方式

示例中的每个操作只发送一次。它们从不自动重试：重新发送是一个新的操作，可能会计费。超时或连接错误表示客户端没有收到完整的响应。这并不能证明服务器停止了处理，也不能证明没有扣除积分。

请把返回的 request_id 和计费状态与您的任务记录一起保存。错误对象保留了响应以便进行受控分析，但其中可能包含原始输入：不要把整个对象、响应和 API 密钥写入普通日志文件。

• Problem Details 与重试决策 →
• 积分与计费确认 →

了解 fetch 超时与响应检查

默认超时为 10,000 毫秒，通过 AbortSignal.timeout 实现，包括读取响应正文的时间。客户端中止并不能证明服务器上的处理或计费已经停止。该模块会禁用重定向，区分 HTTP 错误和无法读取的响应，并且从不自动重试。

使用模拟传输的测试覆盖成功响应、未知结果、部分成功的批量请求、凭据回退和错误。它们不会获取真实的预测，也不会执行消耗积分的操作，不衡量生产环境中的可用性或准确率。下面每个显式的演示命令都会发送自己的请求，并会计费。

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

• Node.js 文档：fetch →
• Node.js 文档：AbortSignal.timeout →

常见问题