# API v2 JSON 响应和置信度

> 了解 GenderAPI v2 数据和元字段：性别、未知原因、置信度、数据集证据、AI 分数、访问模式和计费元数据。

Canonical HTML: https://www.genderapi.io/zh/docs/v2/responses

Last reviewed: 2026-09-25

## 了解 JSON 响应

成功的单个响应包含 data 和 meta。下面的数据集响应是一个说明性示例，不是产品准确性的测量或相同实时结果的承诺。它显示 IP 试用访问。使用帐户密钥验证的请求返回 access.mode: api_key；仅适用于试用的字段的值为 null。

| 场 | 含义 |
| --- | --- |
| data.input | 输入类型、值和国家/地区。 true 时包含 forceToGenderize。 |
| data.name | 匹配或提取的名字； null，当没有可用时。 |
| data.gender | male、female 或 JSON null。这是一个预测，而不是一个人身份的证明。 |
| data.result_status / reason | 当result_status为identified时，reason为null。当状态为unknown时，原因为not_found、no_name_candidate、ambiguous或insufficient_evidence。 |
| data.confidence | 0–1 分数或 null。空性别有 null 信心。 |
| data.confidence_kind | observed_frequency：主导性别计数除以所选数据集中的总计数。 model_reported：AI 分数，而不是校准概率。不可用时值为null。 |
| data.sample_count | 数据集样本大小或 null。人工智能并没有发明样本计数。 |
| data.source | dataset、ai 或 none。 |
| data.country / country_source | 数据集或 ai_association 或 null 中的国家/地区关联。不规定国籍、居住地或种族。 |
| data.match | 数据集中匹配的姓名、匹配方法（normalized、token、substring 或 model_inference）、范围（country 或 global）以及匹配的国家。无法提供的依据为 null。 |
| meta.request_id / duration_ms | 操作标识符和处理持续时间（以毫秒为单位）。 |
| meta.access | 如何授予访问权限以及试用回退的原因（如果有）。 |
| meta.usage | 净费用、完成时间余额、计费状态和试用重置信息。 |

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [完整的响应模式和批处理示例](https://api.genderapi.io/api/v2/openapi.json)

## 成功的未知结果

HTTP 200 表示操作完成；它不能保证性别。保留 JSON null 而不是将其转换为 male、female、空字符串或零置信度。与 HTTP 错误分开检查 data.result_status 和 data.reason。

此仅数据集示例返回 source: none 和 reason: not_found，但仍需要 1 个积分。如果两种性别的数据集计数相等，则结果可以包含 reason: ambiguous，同时保留 sample_count。未知的 AI 结果使用 source: ai 和 reason: insufficient_evidence。

```json
{
  "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": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 8,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

## 解释置信度和匹配证据

0-1 范围内的置信度为 0.9。对于 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 描述候选者和查找范围。

## 相关指南

- [批量响应和每项错误](https://www.genderapi.io/zh/docs/v2/batch#batch-response)
- [计费状态和剩余积分](https://www.genderapi.io/zh/docs/v2/credits-and-usage)
- [响应兼容性和重试](https://www.genderapi.io/zh/docs/v2/errors-and-retries#retries)