# API v2 JSON 응답 및 자신감

> GenderAPI v2 데이터 및 메타 필드(성별, 알 수 없는 이유, 신뢰도, 데이터 세트 증거, AI 점수, 액세스 모드 및 청구 메타데이터)를 이해합니다.

Canonical HTML: https://www.genderapi.io/ko/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 성별에는 null 신뢰도가 있습니다. |
| data.confidence_kind | observed_frequency: 주요 성별 수를 선택한 데이터세트의 총 수로 나눈 값입니다. model_reported: 보정된 확률이 아닌 AI 점수입니다. 사용할 수 없는 경우 값은 null입니다. |
| data.sample_count | 데이터 세트 샘플 크기 또는 null. AI는 샘플 수를 만들어내지 않습니다. |
| 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은 작업이 완료되었음을 의미합니다. 성별을 보장하지는 않습니다. male, female, 빈 문자열 또는 신뢰도 0으로 변환하는 대신 JSON null를 유지합니다. HTTP 오류와 별도로 data.result_status 및 data.reason를 확인하세요.

이 데이터세트 전용 예시는 source: none 및 reason: not_found를 반환하지만 여전히 1크레딧이 필요합니다. 두 성별에 대한 데이터 세트 수가 동일한 경우 결과에는 sample_count를 유지하면서 reason: ambiguous가 포함될 수 있습니다. 알 수 없는 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.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는 후보 및 조회 범위를 설명합니다.

## 관련 가이드

- [일괄 응답 및 항목별 오류](https://www.genderapi.io/ko/docs/v2/batch#batch-response)
- [결제 상태 및 남은 크레딧](https://www.genderapi.io/ko/docs/v2/credits-and-usage)
- [응답 호환성 및 재시도](https://www.genderapi.io/ko/docs/v2/errors-and-retries#retries)