结果与置信度
理解预测结果及其局限
API V2 中的国家/地区背景、置信度和未知结果。
GenderAPI 的结果能确定一个人的性别吗？
不能。GenderAPI 根据与姓名相关的信号推断性别；启用相应选项时，也会参考昵称中的信号。预测并不是经过核实的个人信息。请保留不确定性，尊重本人自述的性别认同，也不要仅凭这一推断做出影响重大的决定。
国家/地区背景如何影响结果？
可选的大写 ISO 国家代码可为请求提供地区背景。仅在国家/地区相关且已知时提供。同一个姓名在不同地区的用法可能不同；返回的国家/地区表示与该姓名的关联，不能证明国籍或居住地。
V2 中的置信度表示什么？
confidence 是 0 到 1 之间的数值；无法提供时为 null。请结合 confidence_kind 解读：observed_frequency 表示数据集中占多数的性别计数除以总计数；model_reported 是 AI 给出的分数。这些数值既不是针对个人的校准概率，也不是经过测量的产品准确率。请根据具有代表性的数据设定人工复核阈值。
gender: null 表示什么？这种结果会计费吗？
可以提交不同文字系统的姓名吗？
可以。请以 Unicode 提交姓名，保留原始字符和有意义的变音符号。覆盖范围和置信度取决于姓名、地区和现有信号，因此请用您的应用所涉及的文字系统和国家/地区的代表性样本进行测试。
API 与 AI
选择请求类型和 AI 选项
V2 请求类型、批量请求、AI 行为和使用限制。
可以在一个批量请求中分析姓名、电子邮箱和用户名吗？
可以。POST /api/v2/gender/batch 使用 API 密钥时最多接受 50 个条目，使用 IP 试用时最多 10 个。每个条目都有自己的 type、value、可选的 country 和 AI 设置。批量条目默认不使用 AI。请检查每条结果：即使部分条目失败，批量请求也可能返回 HTTP 200。积分按每个成功处理的条目扣除，未知结果同样计费。
电子邮箱请求如何工作？
使用 type: email 并提交有效的邮箱地址。API 会在 @ 之前的本地部分中寻找可用的姓名信号；域名无法说明一个人的身份或所在国家。共享邮箱和不含姓名信号的地址可能返回未知结果。数据集无法确定性别时，单条请求默认使用 AI 回退。
用户名请求如何工作？
使用 type: username。普通请求会在用户名或显示名称中寻找可识别的名字。抽象的别名可能返回未知结果。如果希望在数据集查询无结果后使用可识别昵称的 AI，请启用 forceToGenderize；这样即使没有提取到真实名字，也可能得出性别。
V2 什么时候使用 AI？
单条请求默认使用 options.ai_mode: fallback：先查询数据集，无法确定性别时再使用 AI，总共消耗 1 个积分。off 只使用数据集，消耗 1 个积分；always 跳过数据集直接使用 AI，消耗 2 个积分。批量条目默认使用 off，可为单个条目启用 AI。任何模式都不能保证结果不为 null。
forceToGenderize 有什么作用？
这个可选参数适用于姓名、电子邮箱和用户名，也可用于批量请求中的单个条目。由数据集确定的结果消耗 1 个积分。否则会使用可识别昵称的 AI，总共消耗 2 个积分，即使成功处理的结果仍为未知。不需要真实名字。请省略 ai_mode 或使用 fallback；与 off 或 always 同时使用会返回 422。
V2 如何扣除积分？
V2 有请求限制吗？
有。当前默认值为每个账户每分钟 120 个请求、每个 IP 地址每分钟 600 个请求，以及每个账户 2 个并发操作。此外还受服务共享容量的限制。POST 请求体上限为 64 KiB；批量请求使用 API 密钥时最多 50 个条目，使用 IP 试用时最多 10 个。请处理 HTTP 429 和 Retry-After，不要假定在这些上限内的请求总会被接受。
可以重试失败或超时的请求吗？
每条预测请求都是一次新的操作，会正常计费。超时或响应丢失并不能证明没有扣除积分。重试前请检查 billing_status；如果扣费未确认，请附上 request_id 联系支持团队。批量请求部分失败时，请在扣费确认后只重试失败的条目。遇到 429 时，请遵循 Retry-After 响应头。
在哪里可以找到 V2 的代码示例和工具？
V2 指南提供 cURL、JavaScript、Python、PHP、Java、C# 和 Go 示例。Swagger 和 Postman 使用同一份 V2 接口规范。请选择输入类型，并将 API 密钥保存在服务器端配置中。
还可以继续使用 V1 吗？
可以。现有的 V1 集成保留原来的接口和响应格式。V1 和 V2 使用同一个 API 密钥和同一个积分余额，但请求字段、响应和错误格式不同。维护现有客户端时请使用单独的 V1 文档；准备更新时请参阅迁移指南。
隐私与文件
了解数据如何处理
在哪里查看有关数据处理、保留和删除的最新信息。
GenderAPI 会保存成功的请求吗？
隐私政策说明了可能保留哪些请求记录、运营记录和安全日志，处理这些数据的目的，以及删除方式。请针对您的集成查阅这些信息，并避免发送不必要的个人数据。
电子邮箱请求中的地址会被保存吗？
有关电子邮箱输入及相关技术记录的当前处理方式，请参阅隐私政策。电子邮箱地址可能属于个人数据：请只发送请求所需的内容，也不要在您自己的诊断日志中记录完整地址。
上传的 Excel 或 CSV 文件会保留多久？
账户与支持
连接 API 密钥并管理账户
免费使用、身份验证、余额查询和支持。
可以免费试用 GenderAPI 吗？
如何进行身份验证并保护 API 密钥？
请在可信的服务器端代码中使用 Authorization: Bearer YOUR_API_KEY；POST 请求还需要 Content-Type: application/json。不要把真实密钥放在浏览器代码、公开代码仓库或日志中。缺失、格式无效或无法识别的密钥可能会使用 IP 试用，因此请确认 meta.access.mode 的值为 api_key。已识别但被停用、已过期或受限的密钥不会转为使用 IP 试用。
如何查询剩余积分？
使用 Bearer 密钥调用 GET /api/v2/usage。这项余额查询免费，会返回 data.remaining_credits。不提供密钥时，读取的是共享的 IP 试用余额。V1 和 V2 使用同一个账户余额；预测响应中的 remaining_credits 表示该操作完成时的余额。
在哪里管理或取消订阅？
登录 GenderAPI 应用，即可管理与您的 API 密钥关联的订阅。在当前的账户设置中可以查看您的套餐和取消选项。
在哪里更新账单信息？
登录 GenderAPI 应用后，可以按 API 密钥或订阅管理账单和付款设置。
如何反馈错误结果或获取集成帮助？
请向支持团队发送 API 版本、接口、request_id 和一个简短的可复现示例。如有错误代码，请一并提供，但请删除您的 API 密钥和敏感个人数据。
技术知识库
实施与负责任使用指南
关于 V2 结果、隐私和运行方式的解答，附有相关指南链接，每条解答都提供 Markdown 版本。
结果、置信度与负责任使用
未能确定性别的 V2 预测会将 gender 设为 JSON 原生的 null 值，而不是字符串 "null"。姓名可能存在歧义，或者现有信号不足；如果响应中包含 result_status 和 reason，请检查这两个字段。请保留未知结果，不要强行归入某个类别。成功处理的未知预测按所选模式的费用计费。请求错误或服务提供方错误属于另一类失败，相关扣费信息见 meta.usage。
阅读完整解答 →如何评估 GenderAPI 的准确性？有意义的准确性评估应说明测试人群、日期、抽样方法、未知结果的比例，以及按地区和文字系统划分的结果。当前的方法说明页面描述的是一套评估方案，而不是已测得的准确率百分比。V2 的 confidence 和 confidence_kind 字段说明了每条结果所依据的信号；它们不能替代基于代表性数据的评估。
阅读完整解答 →数据来源、隐私与合规
数据来源页面介绍了记录来源类别、选择标准、许可以及地域和文字系统限制的框架。该页面目前没有公布经过审核的来源清单。如果您的集成对数据来源有特定要求，请查阅该页面并联系支持团队；不要假定任何未经记录的来源、数据集规模或覆盖率数字。
阅读完整解答 →姓名数据多久更新一次？当前的数据来源页面并未规定适用于所有姓名记录或处理规则的统一更新周期。如果数据时效性对您的使用场景很重要，请就相关数据集或流程咨询支持团队，并评估具有代表性的结果。页面的审核日期并不表示所有底层记录都在当天更新过。
阅读完整解答 →在哪里可以找到 GDPR 和数据处理协议的相关信息？隐私政策、GDPR 信息、数据处理协议和次级处理方名单说明了已公布的处理条款和保护措施。请查阅最新文件以及适用于您账户的任何协议。如有涉及贵组织的具体问题，例如处理角色、数据传输或数据主体请求，请联系 GenderAPI；一般性的常见问题解答不能替代适用的协议。
阅读完整解答 →API 运行、错误与计费
请在可信的服务器端代码中使用 Authorization: Bearer YOUR_API_KEY。V2 的 POST 请求还需要 Content-Type: application/json。GET /api/v2/gender 也接受以查询参数传递的密钥，但使用请求头可以避免凭据出现在浏览器 URL 中。缺失、格式无效或无法识别的密钥可能会使用共享的 IP 试用；对于账户集成，请确认 meta.access.mode 的值为 api_key。已识别但被停用、已过期或受限的密钥不会转为使用试用。
阅读完整解答 →如何处理请求限制和重试？V2 对请求频率和并发数都有限制；请处理 HTTP 429 和 Retry-After。每次重复的预测都是一次新的操作，会正常计费。超时、响应丢失或扣费未确认时，请不要自动重试。请先检查 code、action 和 meta.usage.billing_status；遇到 billing_reconciliation_required 时，请附上 request_id 联系支持团队。只有在扣费已确认且文档中的 action 允许重新尝试时，才使用有上限的退避重试。
阅读完整解答 →如何解读 V2 错误？V2 API 错误使用 HTTP 错误状态码和 RFC 9457 Problem Details，并包含稳定的 code 和 action 字段。请依据这些字段处理，而不是匹配 detail 的文字，并保留 request_id 以便联系支持团队。成功处理的未知结果不是错误。即使返回 HTTP 200，批量响应也可能包含单个条目的错误。代理服务器可能返回非 JSON 格式的错误；响应丢失或无法读取也不能证明没有扣除积分。
阅读完整解答 →如何查询剩余积分？请在可信的服务器端代码中使用 Bearer API 密钥调用 GET /api/v2/usage。该请求免费，并返回 data.remaining_credits；不提供密钥时，读取的是共享的 IP 试用余额。V1 和 V2 使用同一个账户余额。预测响应中的 meta.usage 显示该操作的扣费以及操作完成时的余额，该余额可能因并发请求而变化。请勿在日志中记录凭据，也不要把余额查询结果当作某条响应丢失的请求未被扣费的证明。
阅读完整解答 →如何从 V1 平稳迁移到 V2？新集成请使用 V2；现有的 V1 客户端可以继续使用其文档中的接口，直到您决定迁移。两个版本共用 API 密钥和积分，但请求字段、响应结构和错误格式不同。请按照迁移指南操作，测试成功、未知和错误三类结果，并在切换接口前更新响应处理逻辑。V1 文档仍会为现有集成保留。
阅读完整解答 →如何排查错误并监控服务可用性？请求失败时，请根据返回的错误代码区分服务故障、无效输入、账户访问问题、积分耗尽和请求限制。请在您自己的集成中监控请求成功率和响应时间。如果出现无法解释的错误或扣费不明确，请附上 request_id 联系支持团队。有关可用性的说法应以实际监控数据为依据；本常见问题解答不承诺任何可用性百分比。
阅读完整解答 →仍然需要帮助？
请发送可复现的示例
请提供接口、请求参数和返回的错误，但不要发送生产环境 API 密钥或敏感个人数据。