GenderAPI.io V2 JSON 응답과 신뢰도

JSON 응답 이해하기

성공한 단일 응답에는 data와 meta가 포함됩니다. 다음 데이터셋 예시는 2026년 10월 1일에 API 키로 받은 실제 응답이며, 계정 잔액만 바꿨습니다. 측정된 제품 정확도를 나타내지 않으며, 실제 요청에서는 다른 결과가 반환될 수 있습니다. API 키 요청에서는 access.mode: api_key와 null인 IP 체험 전용 한도 필드가 반환되고, IP 체험 요청에서는 체험 한도 및 초기화 시각과 함께 ip_trial이 반환됩니다.

{
  "data": {
    "input": {
      "type": "name",
      "value": "Jihoon",
      "country": "KR"
    },
    "name": "jihoon",
    "gender": "male",
    "country": "KR",
    "confidence": 0.9693877551020408,
    "confidence_kind": "observed_frequency",
    "sample_count": 196,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "jihoon",
      "method": "normalized",
      "scope": "country",
      "country": "KR"
    }
  },
  "meta": {
    "request_id": "81a126a7-5333-4023-ada5-19823d8e9bf4",
    "duration_ms": 8,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

• 전체 응답 스키마와 일괄 요청 예시

추정 응답 필드

반환되는 입력 필드

데이터셋 일치 필드

접근, 과금과 요청 메타데이터

성공한 알 수 없는 결과

HTTP 200은 작업이 완료되었다는 뜻이며 성별을 보장하지 않습니다. JSON null을 male, female, 빈 문자열 또는 신뢰도 0으로 바꾸지 말고 그대로 유지하세요. data.result_status와 data.reason은 HTTP 오류와 별도로 확인하세요.

2026년 10월 1일에 받은 이 데이터셋 전용 실제 예시는 source: none과 reason: not_found를 반환하며, 이 경우에도 1크레딧이 차감됩니다. 두 성별의 건수가 같은 데이터셋 행은 sample_count를 유지한 채 reason: ambiguous를 반환할 수 있습니다. 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 레이블을 억지로 붙이지 말고 알 수 없는 결과를 애플리케이션에 그대로 남겨 두세요.

• 운영상 오류와 알 수 없는 결과 구분하기
• 이 판단을 일괄 요청에 적용하기

자체 평가를 바탕으로 임계값 정하기

추정을 항상 정확하게 만드는 보편적인 신뢰도 기준값은 없습니다. 사용 사례를 대표하면서 독립적으로 레이블이 지정된 예시로 observed_frequency와 model_reported를 따로 평가하세요. 데이터셋 빈도와 AI가 스스로 보고한 점수는 둘 다 0.9이더라도 서로 다른 신호입니다. 기준이 얼마나 자주 답을 내는지, 답을 낸 추정이 얼마나 자주 맞는지 측정하고, 나머지는 알 수 없는 결과로 두거나 검토 절차로 넘기세요.

예를 들어 result_status가 identified이지만 confidence_kind가 model_reported이면 데이터셋 임계값이 아니라 평가를 거친 AI 기준을 적용하세요. forceToGenderize를 사용했다면 name: null과 null이 아닌 성별이 함께 반환되는 것은 유효한 결과입니다. 실제 이름을 추출하지 않아도 별칭으로 추정할 수 있기 때문입니다. 추정이 답을 냈는지는 name만 보지 말고 gender와 result_status로 판단하세요. 이는 여전히 추정일 뿐 개인의 신원 확인이 아닙니다.

• 평가 지표와 신뢰도의 한계
• 데이터셋 개요와 근거의 범위
• 별명 추정과 null이 될 수 있는 name

관련 가이드

• 일괄 응답과 항목별 오류
• 과금 상태와 남은 크레딧
• 응답 호환성과 재시도