이름으로 성별 예측 API

요청 개요

요청당 이름 하나 전송

이름이 포함된 JSON 객체를 전송하고 Bearer 토큰으로 인증합니다. 지역별 이름 사용 패턴이 예측 품질을 높일 수 있다면 국가 코드를 추가하세요.

방식POST

콘텐츠 유형application/json

인증Bearer 토큰

크레딧 비용조회 1건

HDR

필수 HTTP 헤더

요청 인증하기

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

API 키는 서버 환경 변수에 보관하세요. 자격 증명을 안전하게 처리하려면 인증 가이드를 확인하세요.

JSON 요청 본문

매개변수

매개변수	유형	필수 여부	설명
`name`	string	필수	분석할 이름입니다. 호칭이나 접두사 없이 이름 필드만 전송하세요.
`country`	string	선택	KR 또는 US 같은 ISO 3166-1 alpha-2 국가 코드로 지역별 맥락을 제공합니다.
`askToAI`	boolean	선택	true이면 데이터베이스에 이름이 없을 때 AI 보완 분석을 사용합니다.
`forceToGenderize`	boolean	선택	true이면 별명이나 일반적인 이름처럼 보이지 않는 입력도 예측을 시도합니다.

AI 보완 기능 안내

askToAI는 데이터베이스에서 결과가 없을 때만 사용됩니다. 특이한 입력에 대한 강제 예측은 신뢰도가 낮을 수 있으므로 probability를 중요한 품질 신호로 활용하세요.

코드 예제

단일 요청 보내기

모든 예제는 Bearer 인증으로 동일한 요청을 전송합니다.

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Jiwon","country":"KR","askToAI":true}'

JavaScript

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

Python

import requests
response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Jiwon", "country": "KR", "askToAI": True}
)
print(response.json())

200 응답

성별 예측 결과

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Jiwon",
  "name": "Jiwon",
  "gender": "female",
  "country": "KR",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

응답 필드

필드	유형	설명
`status`	boolean	요청이 오류 없이 처리되었는지 나타냅니다.
`used_credits`	integer	요청에 사용된 크레딧 수입니다.
`remaining_credits`	integer	요청 처리 후 사용할 수 있는 크레딧 수입니다.
`expires`	integer	요금제 만료 시각의 UNIX 타임스탬프입니다.
`q`	string	요청으로 전송한 원래 이름입니다.
`name`	string	GenderAPI가 분석한 이름입니다.
`gender`	string \| null	예측값으로 male, female 또는 null을 반환합니다.
`country`	string	예측에 사용된 국가 코드입니다.
`total_names`	integer	예측의 근거가 된 이름 레코드 수입니다.
`probability`	integer	예측 신뢰도를 백분율로 표시합니다.
`duration`	string	서버 처리 시간입니다.

정제되고 올바르게 인코딩된 입력 전송

호칭이나 접두사 없이 이름만 사용하세요. JSON 클라이언트가 인코딩을 자동 처리하더라도 요청 본문을 만들기 전에 외부 입력을 항상 검증하세요.

다음 가이드

여러 이름 분석하기

다중 이름 요청한 번의 요청으로 여러 이름 처리 →인증API 키 보안 다시 확인 →