根据姓名判断性别 API
发送一个姓名，接口返回性别、概率、样本量、置信等级和数据来源。一次请求即可，支持汉字和拼音，批量接口保持输入顺序。
这是统计推断，不是身份认定。它适合数据汇总、受众分析和可以保留“未知”的流程；不适合对某个具体的人做出判断。
无需信用卡。已购买的额度不会每月清零。
第一个请求
在控制台创建密钥后直接调用接口。这里用 POST 发送 JSON，可以避免手动处理汉字的 URL 编码；GET 同样可用。
curl -X POST "https://namegender.com/api/v1/gender" \
-H "Authorization: Bearer ng_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"name":"伟","country":"CN"}'{
"query": "伟",
"name": "伟",
"gender": "male",
"probability": 85,
"sample_size": 0,
"confidence": "unverified",
"country": "CN",
"source": "script",
"matched_as": "wei"
}注意 `sample_size` 是 `0`，`confidence` 是 `unverified`。中文姓名没有公开可审计的登记数量，所以这个结果依据的是文字规则而不是计数记录。答案可能正确，但它没有被计数支撑——这一点我们写在响应里，而不是藏起来。
响应字段的含义
生产代码不应该只读取 `gender`。把下面这些字段一起保存，你才能在之后调整阈值，而不必重新调用整批数据。
| 字段 | 开发时的含义 |
|---|---|
| gender | 证据达到阈值时的主要统计类别，否则为 null。 |
| probability | 数据中主要类别所占的比例，不是对这个人的确定度。 |
| sample_size | 支撑结果的可计数记录数。0 表示来源没有公开可审计的数量。 |
| confidence | 根据证据量区分 high、medium、low、unverified 和 unknown。 |
| source | 结果来自数据库、文字规则、模糊匹配、语言模型，还是没有结果。 |
| matched_as | 实际命中的数据库条目。与输入不同时说明发生了转写或模糊匹配。 |
`probability: 90` 不等于“这个人有 90% 的可能是这个性别”。它表示当前数据中该姓名与主要类别的关联比例。把这两件事混为一谈，是姓名性别数据最常见的误用。
汉字、拼音与姓名顺序
中文姓名的难点不在查表，而在输入本身。姓在前、名在后，而多数按西方名单设计的系统默认第一个词是名字。
张伟中的张是姓，伟是名。如果系统把第一个拉丁词当作名字，Zhang Wei 会按姓氏 Zhang 查询，得到的是姓氏的性别倾向，而不是这个人的。
不带声调的 wei 可以对应伟、薇、微、威、唯，这些字的性别倾向并不相同。拼音把这些区别丢掉了，而接口只能看到你发送的内容。
中国没有公开可按姓名统计的登记数量，所以 sample_size 往往是 0，confidence 是 unverified。这不代表结果错误，而是说明它没有计数支撑。
有独立名字字段时只发送名字；只有全名时优先发送汉字，并读取响应中的 first_name 和 last_name；只有拼音时，明确记录姓名顺序，不要假设第一个词是名字。
# 汉字：姓名顺序被正确识别
{"query": "王芳", "first_name": "芳", "last_name": "王",
"gender": "female", "probability": 93, "source": "db"}
# 拼音：同一个人，结果相反
{"query": "Wang Fang", "first_name": "Wang", "last_name": "Fang",
"gender": "male", "probability": 87, "source": "db"}这是真实响应，不是示意。汉字输入时接口识别出王是姓、芳是名，返回 female；换成拼音 Wang Fang 之后，第一个词被当成名字，结果变成 male。差别不在数据，在输入。
汉字姓名上的实测表现
在公开的固定测试集中，汉字文字组包含 222 个姓名。覆盖率为 99.5%，在给出答案的姓名中准确率为 86.9%，把未回答也算作错误的端到端准确率为 86.5%。
这是可复现的产品测试，不是中国人口普查。它不能代表所有地区、所有年代的用名习惯。评估时请用你自己的一小批带标签数据验证，这比任何供应商给出的总准确率都更有说服力。
查看测试方法批量姓名性别识别
不要为每个姓名建立一次连接。批量接口在一个请求中最多接收 100 个姓名，并保持返回顺序与输入一致。
curl -X POST "https://namegender.com/api/v1/gender/bulk" \
-H "Authorization: Bearer ng_live_xxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"names":["伟","静","王芳","Zhang Wei"],"country":"CN"}'不应该用在哪里
姓名性别识别是概率推断。下面这些规则不是免责声明，而是我们自己在文档、接口和响应里坚持的做法。
- —不要用于招聘、医疗、金融、保险、法律或资格判断。
- —在界面和数据库中保留未知值，不要把 null 自动改成概率更高的一侧。
- —针对自己的数据集选择概率阈值，不要直接套用通用数字。
- —同时监控覆盖率和回答后的准确率；只看其中一个都会得出错误结论。
- —对中文数据分别测试汉字、拼音和混合输入。
常见问题
支持。汉字是推荐的输入形式，因为它保留了拼音丢失的区别。接口同时接受汉字、拼音和混合输入。
因为来源没有公开按姓名统计的登记数量。confidence 反映的是证据是否可计数，不是答案是否正确。我们选择把这件事写在响应里，而不是用一个看起来更好的数字覆盖它。
在 222 个汉字姓名的固定测试集中，覆盖率 99.5%，回答后的准确率 86.9%，端到端准确率 86.5%。测试集和方法都是公开的。
不会。查询内容不会被存储，也不会用于训练。账户中只保留调用次数和计费记录。
不能，任何姓名接口都不能。返回的是这个姓名在数据中的统计倾向。涉及个人的重要判断请使用本人提供的信息。