基础使用
GenderAPI 允许你通过不同类型的输入数据来判断一个人的性别。
你可以直接分析名字，或者从电子邮件地址和用户名中提取名字。
以下是开始使用的方法：
1. 通过名字判断性别
向以下 endpoint 发送一个名字：
https://api.genderapi.io/api
示例：
curl "https://api.genderapi.io/api?name=Alice&key=YOUR_API_KEY"
你还可以添加可选参数：
country：传入两位国家代码
(
ISO 3166-1 alpha-2
)
以提高预测的准确度。例如：土耳其使用 country=TR。
askToAI：如果设置为 true，当数据库中找不到该名字时，API 会请求 AI 模型来判断性别。
forceToGenderize：如果设置为 true，即使输入的内容看起来不像真实的人名（例如昵称或像 sparkling unicorn、mystic warrior 这样的幻想名称），API 也会尝试猜测性别。这在分析用户名时很有用，但结果可能不够准确。
注意： 该参数不适用于 email endpoint。
带参数示例：
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"
2. 通过电子邮件地址判断性别
如果你只有电子邮件地址，可以使用以下 endpoint：
https://api.genderapi.io/api/email
示例：
curl "https://api.genderapi.io/api/email?email=alice.smith@example.com&country=TR&askToAI=true&key=YOUR_API_KEY"
注意： forceToGenderize 参数在 email endpoint 中不可用，因为此 endpoint 会先在内部提取名字。
3. 通过用户名判断性别
对于用户名或昵称，请使用：
https://api.genderapi.io/api/username
示例：
curl "https://api.genderapi.io/api/username?username=sparkling_unicorn&country=US&askToAI=true&forceToGenderize=true&key=YOUR_API_KEY"
forceToGenderize 参数在这里尤为有用，因为用户名通常包含不是人名的单词或幻想词汇。它会强制 API 尝试预测性别，即使输入的内容并不是典型的人名。
所有方法都支持单次或批量请求。欲了解更多细节，请查看左侧导航菜单中的相关部分。
✅ API 响应
以下是所有 endpoint 的 JSON 响应示例：
{
"status": true,
"used_credits": 1,
"remaining_credits": 4999,
"expires": 1743659200,
"q": "michael.smith@example.com",
"name": "Michael",
"gender": "male",
"country": "US",
"total_names": 325,
"probability": 98,
"duration": "4ms"
}
响应字段
字段
类型
描述
status
Boolean
如果请求成功，则为 true。如为 false，请检查错误信息。
used_credits
Integer
本次请求消耗的积分数量。
remaining_credits
Integer
本次请求后账户剩余的积分数量。
expires
Integer (timestamp)
套餐的过期时间，以 UNIX timestamp（秒）表示。
q
String
你的输入查询（名字、电子邮件或用户名）。
name
String
找到或提取出来的名字。
gender
Enum[String]
预测的性别。可能的值：male、female 或 null。
country
Enum[String]
最可能的国家代码（例如 US 或 DE）。
total_names
Integer
用于预测的样本数量。
probability
Integer
预测性别的概率百分比（例如 50-100）。
duration
String
本次请求的处理时间（例如 4ms）。
警告：
如果你的输入值包含空格或特殊字符（例如 sparkling unicorn），
在发送 GET 请求之前一定要进行 URL 编码。否则，可能导致请求失败，
或者其他参数在你的编程语言或 HTTP 库中被误解。
curl "https://api.genderapi.io/api?name=sparkling unicorn&key=YOUR_API_KEY"
你应该改为使用：
curl "https://api.genderapi.io/api?name=sparkling%20unicorn&key=YOUR_API_KEY"
或者在你的编程语言中使用合适的 URL 编码函数。