了解 JSON 响应
成功的单个响应包含 data 和 meta。下面的数据集示例是 2026年10月1日使用 API 密钥获取的真实响应，仅替换了账户余额。它并不代表实测的产品准确性，实时请求可能返回不同的结果。使用 API 密钥的请求会返回 access.mode: api_key，且仅适用于试用的额度字段为 null；IP 试用请求会返回 ip_trial，并附带试用限额和重置时间。
{
"data": {
"input": {
"type": "name",
"value": "Wei",
"country": "CN"
},
"name": "wei",
"gender": "male",
"country": "CN",
"confidence": 0.8647342995169082,
"confidence_kind": "observed_frequency",
"sample_count": 207,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "wei",
"method": "normalized",
"scope": "country",
"country": "CN"
}
},
"meta": {
"request_id": "53943fbf-f490-4c0d-902e-b5dac9822b66",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}预测响应字段
| 字段 | 类型 | 可为 null | 示例 | 说明 |
|---|---|---|---|---|
data.input | object | 否 | {"type":"name","value":"Wei","country":"CN"} | 输入类型、值和国家/地区。forceToGenderize 为 true 时会包含该字段。 |
data.name | string | 是 | "wei" | 匹配到或提取出的名字；没有时为 null。 |
data.gender | string | 是 | "male" | male、female 或 JSON null。这是一种推断，而不是经过验证的个人身份。 |
data.result_status | string | 否 | "identified" | 返回性别时为 identified，否则为 unknown。 |
data.reason | string | 是 | null | identified 结果为 null。未知原因：not_found、no_name_candidate、ambiguous 或 insufficient_evidence。 |
data.confidence | number | 是 | 0.95 | 0–1 之间的值或 null。性别为 null 时，置信度也为 null。 |
data.confidence_kind | string | 是 | "observed_frequency" | observed_frequency：主导性别的数据集计数 / 总计数。model_reported：AI 给出的值，不是经过校准的概率。不可用时为 null。 |
data.sample_count | integer | 是 | 1200 | 数据集样本数或 null。AI 不会编造样本数。 |
data.source | string | 否 | "dataset" | dataset、ai 或 none。 |
data.country | string | 是 | "CN" | 来自 dataset 或 ai_association 的国家/地区关联，或为 null。它不能说明国籍、居住地或族裔。 |
data.country_source | string | 是 | "dataset" | 国家/地区关联的来源：dataset、ai_association 或 null。 |
data.match | object | 否 | {"name":"wei","method":"normalized","scope":"country","country":"CN"} | 匹配到的数据集姓名、匹配方式（normalized、token、substring 或 model_inference）、country/global 范围以及匹配的国家/地区。无法提供的依据为 null。 |
返回的输入字段
| 字段 | 类型 | 可为 null | 示例 | 说明 |
|---|---|---|---|---|
data.input.type | string | 否 | "name" | 输入类别：name、email 或 username。 |
data.input.value | string | 否 | "Wei" | 提交的预测输入值。 |
data.input.country | string | 是 | "CN" | 提交的国家/地区背景；省略时为 null。 |
data.input.forceToGenderize | boolean | 否 | true | 仅在启用昵称模式时出现，否则省略。 |
数据集匹配字段
| 字段 | 类型 | 可为 null | 示例 | 说明 |
|---|---|---|---|---|
data.match.name | string | 是 | "wei" | 所选的数据集候选项；没有选用数据行时为 null。 |
data.match.method | string | 是 | "normalized" | normalized、token、substring 或 model_inference；不可用时为 null。 |
data.match.scope | string | 是 | "country" | 数据集查询时为 country 或 global；AI 结果或缺少依据时为 null。 |
data.match.country | string | 是 | "CN" | 所选数据行的国家/地区；全球数据行或 AI 结果为 null。 |
访问、计费与请求元数据
| 字段 | 类型 | 可为 null | 示例 | 说明 |
|---|---|---|---|---|
meta.request_id | string | 否 | "550e8400-e29b-41d4-a716-446655440000" | 本次 HTTP 尝试的唯一标识符，也会通过 X-Request-ID 返回。 |
meta.duration_ms | integer | 否 | 42 | 请求处理时间（毫秒）。 |
meta.access.mode | string | 否 | "api_key" | api_key、ip_trial 或 unauthenticated。使用付费账户时，请确认值为 api_key。 |
meta.access.reason | string | 是 | null | 转为试用的原因：api_key_missing、api_key_invalid 或 api_key_not_found；其他情况为 null。 |
meta.usage.charged_credits | integer | 是 | 1 | 净扣除的积分。扣费前或全额退款确认后为零；计费未确认时为 null。 |
meta.usage.remaining_credits | integer | 是 | 99 | 操作完成时的余额。可能为负数；不可用或计费未确认时为 null。 |
meta.usage.billing_status | string | 否 | "confirmed" | not_charged、confirmed 或 unconfirmed。重试失败的预测前请检查此字段。 |
meta.usage.resets_at | string | 是 | "2026-09-27T12:00:00.000Z" | IP 试用的重置时间，UTC（ISO 8601）；API 密钥账户或时间未知时为 null。 |
meta.usage.limit | integer | 是 | 10 | IP 试用额度；API 密钥账户为 null。 |
meta.usage.period_seconds | integer | 是 | 86400 | IP 试用周期（秒）；API 密钥账户为 null。 |
成功完成的未知结果
HTTP 200 表示操作已完成，但并不保证返回性别。请保留 JSON null，不要把它转换为 male、female、空字符串或零置信度。请将 data.result_status 和 data.reason 与 HTTP 错误分开检查。
这个于 2026年10月1日获取的真实仅数据集示例返回 source: none 和 reason: not_found，仍会消耗 1 个积分。计数持平的数据行可能返回 reason: ambiguous，同时保留其 sample_count。未知的 AI 结果使用 source: ai 和 reason: insufficient_evidence。
{
"data": {
"input": {
"type": "name",
"value": "zzzxxyy",
"country": null
},
"name": null,
"gender": null,
"country": null,
"confidence": null,
"confidence_kind": null,
"sample_count": null,
"source": "none",
"result_status": "unknown",
"reason": "not_found",
"country_source": null,
"match": {
"name": null,
"method": null,
"scope": null,
"country": null
}
},
"meta": {
"request_id": "54fdcd4e-f8bc-4224-918f-3a5732e08b9c",
"duration_ms": 10,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}解读置信度和匹配依据
置信度 0.9 采用 0–1 的刻度。对于 observed_frequency，它表示主导计数除以所选数据集记录的总数；它不是实测的端到端产品准确性。model_reported 值由 AI 提供，并未按照数据集频率进行校准。
请根据您自己的评估数据和 confidence_kind 确定应用中的阈值。不要把数据集的值和 AI 的值当作衡量同一事物的指标直接排序。AI 结果的 match.name、match.scope 和 match.country 为 null，因为没有选用任何数据行；match.method 为 model_inference。
对于全名，数据集结果可能来自其中某个组成部分，而不是完整字符串。data.input 保留提交的值；data.name 表示返回的名字，data.match 表示候选项和查询范围。
决定您的应用下一步该怎么做
请先处理请求错误和单个条目的错误，再检查 result_status。对于单个预测，请读取 data；对于批量请求，请对每个成功条目的 data 采用相同的判断。请在应用中保留未知结果，不要强行标记为 male 或 female。
| 结果 | 含义 | 建议的处理方式 |
|---|---|---|
| identified; gender: male 或 female | 推断得出了性别，依据来自数据集或 AI。 | 采用针对该 confidence_kind 评估过的策略；保留 source 和匹配依据。 |
| unknown; reason: not_found | 没有任何存储的数据集记录与解析出的候选项匹配。 | 让 gender 保持为 null。有意使用不同 AI 选项再次请求，是一次新的计费操作。 |
| unknown; reason: no_name_candidate | 数据集解析没有得到可用的姓名候选项。 | 保留 null；在选择任何额外推断之前，先检查输入类型和值。 |
| unknown; reason: ambiguous | 所选数据集数据行中男性和女性的计数持平；sample_count 仍可能存在。 | 不要自行决定取哪种性别，也不要把为 null 的置信度转换为零。 |
| unknown; reason: insufficient_evidence | AI 已完成处理，但没有足够的依据返回性别。 | 将其视为已完成的未知结果，而不是服务提供方故障，也不是自动重试的对象。 |
| Problem Details 或条目的 error | 执行失败，例如由于 ai_upstream_error 或 prediction_timeout。 | 保存错误代码和请求 ID，检查计费，并遵循重试相关指引。 |
根据您自己的评估选择阈值
不存在能让预测一定正确的通用置信度阈值。请使用来自您的使用场景、具有代表性且经过独立标注的示例，分别评估 observed_frequency 和 model_reported。数据集中的频率和 AI 自行报告的值是不同的信号，即使两者恰好都是 0.9。请衡量您的策略给出答案的频率，以及这些答案的正确率；其余情况请保留未知结果或安排人工审核。
例如，如果 result_status 为 identified，但 confidence_kind 为 model_reported，请采用您评估过的 AI 策略，而不是数据集的阈值。如果使用了 forceToGenderize，name: null 与非 null 的性别同时出现是有效的：别名可以在不提取真实名字的情况下被推断。要判断推断是否给出了答案，请检查 gender 和 result_status，而不要只看 name。这仍然只是估计，而不是对个人身份的验证。