姓名性别查询 API｜单条请求文档

请求概览

每次请求提交一个姓名

在 JSON 对象中提交名字，并通过 Bearer Token 完成身份验证。如果地区命名习惯有助于提高预测质量，请同时添加国家代码。

请求方法POST

内容类型application/json

身份验证Bearer Token

额度消耗1 次查询

HDR

必需的 HTTP 请求头

验证 API 请求

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

请将 API 密钥保存在服务器端环境变量中。有关凭据安全，请查看身份验证指南。

JSON 请求体

请求参数

参数	类型	要求	说明
`name`	string	必填	需要分析的名字。请提供不含称谓或前缀的干净姓名值。
`country`	string	可选	ISO 3166-1 alpha-2 国家代码，例如 CN 或 US，用于添加地区背景。
`askToAI`	boolean	可选	设为 true 时，仅在数据库未找到姓名的情况下使用 AI 补充分析。
`forceToGenderize`	boolean	可选	设为 true 时，尝试分析昵称或看起来不像典型姓名的输入。

关于 AI 补充分析

askToAI 仅在数据库没有结果时生效。对特殊输入进行强制预测时，结果可能不够可靠，因此应重点评估 probability。

代码示例

发送单条姓名请求

以下示例使用 Bearer 身份验证发送相同的请求。

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "US", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "US", "askToAI": True}
)
print(response.json())

200 响应

性别预测结果

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "US",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

响应字段

字段	类型	说明
`status`	boolean	请求是否成功完成。
`used_credits`	integer	本次请求消耗的 API 额度。
`remaining_credits`	integer	请求完成后剩余的 API 额度。
`expires`	integer	套餐到期时间，以 UNIX 时间戳表示。
`q`	string	请求中提交的原始姓名。
`name`	string	GenderAPI 实际分析的姓名。
`gender`	string \| null	预测值：male、female 或 null。
`country`	string	本次预测所使用的国家代码。
`total_names`	integer	支持本次预测的姓名样本数量。
`probability`	integer	以百分比表示的预测概率。
`duration`	string	服务器处理本次请求所用的时间。

发送干净且正确编码的输入

请提交不含称谓或前缀的名字。JSON 客户端会自动处理编码，但在创建请求体之前，仍应验证来自外部的输入。

下一篇指南

一次分析多个姓名

姓名批量请求在一个请求中处理多个姓名 →身份验证再次查看 API 密钥安全 →