사용자 이름으로 성별 예측 API

요청 개요

사용자 이름에서 이름 신호 추출

GenderAPI는 입력한 핸들에서 이름 신호를 찾은 뒤 데이터베이스 근거와 국가 맥락을 사용해 성별을 예측합니다. 요청한 경우 AI 보완 기능도 적용할 수 있습니다.

입력sparkling_unicorn

추출된 이름Sparkling

예측female · 92%

방식POST

콘텐츠 유형application/json

인증Bearer token

AI 옵션사용 가능

HDR

필수 HTTP 헤더

요청 인증하기

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

JSON 요청 본문

매개변수

매개변수	유형	필수 여부	설명
`username`	string	필수	분석할 사용자 이름, 소셜 미디어 핸들, 표시 이름 또는 별칭입니다.
`country`	string	선택	지역 맥락에 사용할 KR 또는 US 같은 ISO 3166-1 alpha-2 국가 코드입니다.
`askToAI`	boolean	선택	true이면 추출된 이름이 데이터베이스에 없을 때 AI 보완 기능을 사용합니다.
`forceToGenderize`	boolean	선택	true이면 일반적인 사람 이름과 닮지 않은 별칭이나 입력도 예측을 시도합니다.

askToAI

추출된 이름이 데이터베이스에 없을 때만 AI 보완 기능을 사용합니다.

forceToGenderize

판타지 용어, 브랜드형 별칭과 일반적이지 않은 닉네임도 예측을 시도합니다.

신뢰도를 확인하세요: 약하거나 사람 이름이 아닌 신호를 강제 예측한 결과는 신뢰도가 낮을 수 있습니다. 결과를 활용하기 전에 probability를 평가하세요.

코드 예제

사용자 이름 요청 보내기

cURL

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

JavaScript

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

Python

import requests
response = requests.post(
  "https://api.genderapi.io/api/username",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"username": "sparkling_unicorn", "country": "US", "askToAI": True, "forceToGenderize": True}
)
print(response.json())

200 응답

추출된 이름 신호와 예측 결과

JSON

{
  "status": true, "used_credits": 1, "remaining_credits": 4999,
  "expires": 1743659200, "q": "sparkling_unicorn",
  "name": "Sparkling", "gender": "female", "country": "US",
  "total_names": 9876, "probability": 92, "duration": "6ms"
}

응답 필드

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

사용자 이름은 간접 신호로 활용하세요

사용자 이름은 사람이 아니라 브랜드, 캐릭터 또는 개념을 나타낼 수 있습니다. 추출된 name이 의미 있는 사람 이름인지 확인하고 사용 사례에 맞는 최소 확률 기준을 정하세요.

다음 가이드

여러 사용자 이름 분석하기

다중 사용자 이름 요청여러 핸들을 한 번에 처리하기 →단일 이메일 요청이메일에서 이름 추출하기 →