在 Python 中使用 GenderAPI.io V2

准备服务器端的 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 不是有效的密钥。不要把真实的凭据放入受版本控制的文件、共享的笔记本或客户端应用中。导入该模块，或在不带演示选项的情况下运行它，都不会发送任何请求。

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• 下载 genderapi_v2.py →
• 使用免费的用量端点检查密钥 →

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

把下面的代码保存为 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 试用积分。

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"])

• 单个请求的所有字段 →

将结果与其依据一起保存

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

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

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

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)

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

决定何时使用 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。

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

决定出错后的处理方式

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

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

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

了解示例的网络行为

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

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

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

• Python 文档：urllib.request →
• Python 文档：HTTPError →

常见问题