# 在 Python 中使用 GenderAPI.io V2

> 通过基于标准库的示例，从 Python 调用 GenderAPI.io V2。发送姓名、电子邮箱地址和用户名，处理混合批量请求，并读取 data/meta 字段。

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

Last reviewed: 2026-09-29

## 运行时与可下载示例

Python 3.10+。可下载的 HTTP 集成示例；不是单独发布的 SDK。

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

## 准备服务器端的 Python 项目

本指南通过 Bearer 请求头中的 API 密钥调用 GenderAPI.io V2 端点 https://api.genderapi.io/api/v2/gender。请使用 Python 3.10 或更高版本，并把 genderapi_v2.py 下载到您的项目中。示例使用 Python 标准库中的 urllib.request 和 json；不需要任何 pip 软件包。

请在服务器环境中设置 GENDERAPI_API_KEY。下面示例中的 YOUR_API_KEY 不是有效的密钥。不要把真实的凭据放入受版本控制的文件、共享的笔记本或客户端应用中。导入该模块，或在不带演示选项的情况下运行它，都不会发送任何请求。

**配置 Python 环境**

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

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

## 发送一个显式仅使用数据集的请求

把下面的代码保存为 single.py，放在下载的文件旁边，然后运行 python3 single.py。辅助模块会以 JSON 形式发送 type: name、value: Alice 和 options.ai_mode: off。预测位于 data 中，请求和计费信息位于 meta 中。

成功的调用消耗 1 个积分，即使结果未知也是如此；示例姓名并不保证得到预测。make_item 接受 name、email 或 username，并要求显式的 AI 模式。只有在掌握相关背景时才添加 country。

在发送任何内容之前，辅助模块要求提供 24 个字符的十六进制 API 密钥。它检查的是密钥的格式，而不是密钥是否存在。该模块还会把 IP 试用的成功响应视为意外的访问模式而拒绝。这项检查在收到响应之后进行，无法退还已经用掉的 IP 试用积分。

**Python 中的单个查询**

```python
from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])
```

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

**Python 中的批量查询**

```python
from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)
```

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

## 决定何时使用 AI

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

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

Python 辅助模块始终要求提供 ai_mode。如需昵称解读，请使用 make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True)。该模块会把 force_to_genderize 转换为 JSON 字段 forceToGenderize。

| 请求选项 | 行为 | 每次成功查询消耗的积分 |
| --- | --- | --- |
| 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)

## 了解示例的网络行为

urllib 的 10 秒超时适用于阻塞式套接字操作，并不是请求总时长的保证上限。示例会禁用 HTTP 重定向，处理成功的 JSON 响应，并保留 HTTP Problem 响应。它从不自动重试。

本地测试使用模拟的传输响应，覆盖成功调用、未知结果、部分成功的批量请求、账户访问和错误。它们验证的是示例的逻辑，但不衡量生产环境中 API 的可用性、预测准确率或响应时间。下面每个显式的演示命令都会发送自己的请求，并会计费。

**可选的显式 Python 演示**

```bash
python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch
```

- [Python 文档：urllib.request](https://docs.python.org/3/library/urllib.request.html)
- [Python 文档：HTTPError](https://docs.python.org/3/library/urllib.error.html)

## 为什么 Python 显示的是 None 而不是 null？

Python 的 JSON 解码器会把 null 转换为 None。保存或导出结果时，请保留这个未知值，不要把它替换为默认性别或零置信度。

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

会。成功完成的普通查询消耗 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)