批量姓名性别查询 API｜多条请求文档

批量请求概览

一次处理最多 100 个姓名

提交 data 数组，每条记录都会返回一个结果。可加入您系统中的 id，从而可靠地将每个预测结果关联回源记录。

方法POST

上限100 个姓名

身份验证Bearer token

AI 回退不支持

批量请求不使用 AI 推理。

批量接口不提供 askToAI 和 forceToGenderize。对于非拉丁文字姓名或需要 AI 回退的输入，请使用单个姓名查询接口。

HDR

必需的 HTTP 请求头

为批量请求授权

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

JSON 请求体

参数

字段	类型	是否必填	说明
`data`	object[]	必填	包含 1 至 100 条姓名记录的数组。
`data[].name`	string	必填	需要分析的名字。
`data[].country`	string	可选	ISO 3166-1 alpha-2 国家/地区代码。指定地区无结果时返回可用的全球结果。
`data[].id`	string \| integer	可选	您系统中的记录标识符；响应会原样返回，便于将结果与输入记录对应。

国家/地区结果回退

如果指定国家/地区没有匹配项，GenderAPI 会返回该姓名可用的全球结果。请使用 ISO 3166-1 alpha-2 代码，例如 CN、US 或 DE。

请求载荷

构建 data 数组

JSON

{
  "data": [
    { "name": "Andrea", "country": "DE", "id": "123" },
    { "name": "andrea", "country": "IT", "id": "456" },
    { "name": "james", "country": "US", "id": "789" }
  ]
}

代码示例

发送多姓名批量请求

cURL

curl -X POST "https://api.genderapi.io/api/name/multi/country" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"data":[{"name":"Andrea","country":"DE","id":"123"},{"name":"andrea","country":"IT","id":"456"}]}'

JavaScript

const data = [
  { name: "Andrea", country: "DE", id: "123" },
  { name: "andrea", country: "IT", id: "456" }
];

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

200 响应

将结果与您的记录对应

JSON

{
  "status": true,
  "used_credits": 3,
  "remaining_credits": 7265,
  "expires": 1717069765,
  "names": [
    { "name": "andrea", "q": "Andrea", "gender": "female", "country": "DE", "total_names": 644, "probability": 88, "id": "123" },
    { "name": "andrea", "q": "andrea", "gender": "male", "country": "IT", "total_names": 13537, "probability": 98, "id": "456" }
  ],
  "duration": "5ms"
}

响应字段

字段	类型	说明
`status`	boolean	批量请求是否成功完成。
`used_credits`	integer	本次提交的全部姓名共消耗的额度。
`remaining_credits`	integer	请求完成后的剩余额度。
`expires`	integer	套餐到期时间，采用 UNIX 时间戳。
`names`	object[]	按输入顺序返回的姓名性别预测结果集合。
`names[].name`	string	用于预测的标准化姓名。
`names[].q`	string	请求中提交的原始姓名。
`names[].gender`	string \| null	预测值：male、female 或 null。
`names[].country`	string	生成该结果时采用的国家/地区代码。
`names[].total_names`	integer	支持该结果的样本数量。
`names[].probability`	integer	预测置信度百分比。
`names[].id`	string \| integer	原样返回的输入标识符，用于关联记录。
`duration`	string	服务器总处理时间。

每次请求不得超过 100 条记录

发送前请验证数组，并为每条记录使用唯一 id，确保结果可准确对应。更大的数据集应拆分为每批不超过 100 个姓名。

下一篇指南

根据邮箱判断性别

邮箱单条请求从邮箱中提取姓名并分析性别 →姓名单条请求为单个姓名启用 AI 回退 →