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

> 使用原生 fetch 从 Node.js 调用 GenderAPI.io V2。下载一个 ES 模块，用于单个请求和混合批量请求、读取 data/meta 响应，以及处理影响积分的错误。

Canonical HTML: https://www.genderapi.io/zh/integrations/javascript

Last reviewed: 2026-09-29

## 运行时与可下载示例

Node.js 22+。可下载的 HTTP 集成示例；不是单独发布的 SDK。

- [下载示例](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)

## 将集成保留在 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.js 环境**

```bash
node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"
```

- [下载 genderapi-v2.mjs](https://www.genderapi.io/examples/v2/genderapi-v2.mjs)
- [使用免费的用量端点检查密钥](https://www.genderapi.io/zh/docs/v2/authentication#environment-setup)

## 发送带有 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 试用积分。

**Node.js 中的单个查询**

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

- [单个请求的所有字段](https://www.genderapi.io/zh/docs/v2/request-parameters)

## 将结果与其依据一起保存

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

| 字段 | 使用方式 |
| --- | --- |
| `data.gender / data.result_status` | 只有在 identified 时才使用 male 或 female。结果未知时，请保留 JSON 原生的 null 值。 |
| `data.name / data.match` | 检查返回的名字和所选的候选项。子字符串匹配并不能证明该输入属于拥有这个名字的人。 |
| `data.confidence / data.confidence_kind` | 置信度为 0–1 之间的值或 null。observed_frequency 来自存储的计数；model_reported 是 AI 给出的值。请针对每种类型分别评估阈值。 |
| `data.source / data.sample_count` | 区分 dataset、ai 和 none。AI 结果没有存储的样本数。样本数并不是实测的准确率。 |
| `meta.access.mode` | 在账户集成中，请确认值为 api_key。缺失或无法识别的密钥可能会转为使用共享的 IP 试用。 |
| `meta.usage` | 读取 charged_credits 和 billing_status。成功完成的未知结果同样计费。响应丢失并不能证明该请求是免费的。 |

- [响应字段与未知结果](https://www.genderapi.io/zh/docs/v2/responses)
- [准确性与置信度说明](https://www.genderapi.io/zh/accuracy-methodology)
- [数据来源与注明日期的数据库概况](https://www.genderapi.io/zh/data-provenance)

## 处理混合批量请求，并保留每一行的 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 个条目，开始时一次只发送一组。在处理下一组之前，保存每个响应及对应的用量。遇到传输错误、账户访问错误或未确认的计费时请停止，先弄清当前这一组的情况。只有在核实账户的限制之后，才并行发送。批量请求的最大条目数并不保证特定的处理能力。

**Node.js 中的批量查询**

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

- [批量请求的输入、结果与计费](https://www.genderapi.io/zh/docs/v2/batch)

## 决定何时使用 AI

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

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

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

| 请求选项 | 行为 | 每次成功查询消耗的积分 |
| --- | --- | --- |
| options.ai_mode: off | 仅使用数据集。 | 1，未知结果也是如此 |
| options.ai_mode: fallback | 先查询数据集；如果没有返回性别，再使用普通的 AI。这是单个请求的默认值。 | 总共 1，包括 AI 回退 |
| options.ai_mode: always | 直接使用 AI。 | 2 |
| forceToGenderize: true | 先查询数据集，然后允许 AI 解读个人昵称或别名，即使没有真实名字也可以。 | 数据集得出结果时为 1；使用 AI 时总共为 2 |

- [AI 选项与昵称解读](https://www.genderapi.io/zh/docs/v2/ai-options)
- [积分与用量](https://www.genderapi.io/zh/docs/v2/credits-and-usage)

## 决定出错后的处理方式

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

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

| 情况 | 应用中的决定 |
| --- | --- |
| 成功完成的未知结果 | 保留 null、reason 和 usage。这是已完成且已计费的结果，而不是需要自动重试的失败行。 |
| 422 验证错误 | 先根据 Problem Details 字段中指出的问题修正输入，再发送新的请求。 |
| 401 / 403 | 检查账户访问权限或可用余额。重新发送相同的请求无法解决问题。 |
| 429 | 如有 Retry-After 请求头，请遵守它。检查错误和计费状态，然后审慎安排下一次尝试。 |
| 网络错误、超时或无法读取的响应 | 记录结果和计费均未确认。重新发送前先调查情况。客户端无法撤销服务器已经完成的处理。 |
| billing_status: unconfirmed | charged_credits 和 remaining_credits 可能为 null。重试前请联系支持团队并提供 request_id。不要把 null 替换为零积分。 |
| 批量请求中部分条目出错 | 先保存已完成的条目。检查失败的条目及其计费，只重新发送适合重试的错误条目，而不是整个批量请求。 |

- [Problem Details 与重试决策](https://www.genderapi.io/zh/docs/v2/errors-and-retries)
- [积分与计费确认](https://www.genderapi.io/zh/docs/v2/credits-and-usage)

## 了解 fetch 超时与响应检查

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

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

**可选的显式 Node.js 演示**

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

- [Node.js 文档：fetch](https://nodejs.org/api/globals.html#fetch)
- [Node.js 文档：AbortSignal.timeout](https://nodejs.org/api/globals.html#static-method-abortsignaltimeoutdelay)

## 可以在浏览器中运行的 JavaScript 里使用这段代码吗？

请把代码保留在您的服务器上。在浏览器中运行的应用代码会让用户看到 API 密钥。请从浏览器调用您自己的、经过身份验证的后端，再由后端向 GenderAPI.io 发送请求。

## 未知结果会消耗积分吗？

会。成功完成的普通查询消耗 1 个积分，即使 gender 为 null 也是如此。普通的自动 AI 回退已包含在这个积分中。always 模式消耗 2 个积分；使用 forceToGenderize 时，结果来自数据集则消耗 1 个积分，使用 AI 则消耗 2 个积分。

## 示例会重试失败的请求吗？

不会。每个新请求都是一个单独的操作。在决定是否重新发送之前，请检查错误、每个条目的结果和计费状态。没有收到响应并不能证明上一次尝试是免费的。

## 需要安装软件包吗？

不需要。请直接从本 GenderAPI.io 指南下载示例。它在运行时不依赖外部软件包，也不是通过 pip 或 npm 单独发布的 SDK。请审查代码并根据您的应用进行调整。API 约定以 GenderAPI.io V2 文档为准。

## 参考文档

- [GenderAPI.io V2 身份验证](https://www.genderapi.io/zh/docs/v2/authentication)
- [V2 响应字段](https://www.genderapi.io/zh/docs/v2/responses)
- [批量请求的结果与限制](https://www.genderapi.io/zh/docs/v2/batch)
- [错误与重试文档](https://www.genderapi.io/zh/docs/v2/errors-and-retries)