요청을 보내기 전에
POST https://api.genderapi.io/api/v2/gender로 JSON을 보내세요. Authorization: Bearer YOUR_API_KEY 헤더에 기존 API 키를 넣고 Content-Type: application/json을 지정하세요. 모든 요청은 독립적으로 처리됩니다.
코드 예시에서 언어를 선택하세요. 실행하기 전에 프로세스 환경 변수 GENDERAPI_API_KEY를 설정하세요. 키가 없거나 인식되지 않으면 공유 IP 체험이 사용될 수 있으므로, 계정을 연동할 때는 meta.access.mode가 api_key인지 확인하세요.
사용자 이름이나 별명에서 성별 추정
| 매개변수 | 유형 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
type | string | 예 | — | 입력 종류: name, email 또는 username. |
value | string | 예 | — | 필수. 1~254자이며 공백만으로 이루어질 수 없고 제어 문자를 포함할 수 없습니다. 이메일 값은 올바른 이메일 구문이어야 합니다. |
country | string | 아니요 | — | 선택 사항. TR이나 US 같은 대문자 ISO 3166-1 alpha-2 코드입니다. 국가별 조회는 전역 데이터셋으로 대체될 수 있습니다. |
forceToGenderize | boolean | 아니요 | false | 먼저 데이터셋을 조회하고, 결과가 없으면 별명을 해석하는 AI를 사용합니다. name, email, username을 지원합니다. |
options | object | 아니요 | — | 입력별 AI 옵션을 담는 객체입니다. |
options.ai_mode | string | 아니요 | fallback | 허용값: off, fallback, always. forceToGenderize: true이면 이 필드를 생략하거나 fallback을 사용하세요. |
id | string | 아니요 | — | POST JSON에서 쓸 수 있는 1~64자의 선택적 식별자입니다. 일괄 요청에서는 각 결과와 함께 반환되며 일괄 요청 안에서 고유해야 합니다. 단일 추정 요청에서는 받기만 하고 응답에 다시 포함하지 않습니다. GET 쿼리에서는 지원하지 않습니다. |
핸들과 별명에는 type: username을 사용하세요. prenses처럼 실제 이름을 추출할 수 없더라도 별명의 의미로 추정하려면 forceToGenderize를 true로 설정하세요. 이때도 데이터셋을 먼저 확인합니다. 별명 추정은 name: null과 함께 null이 아닌 gender를 반환할 수 있습니다.
프로그래밍 언어를 선택하세요. API 키 설정하기, 그다음 서버에서 예시를 실행하세요.
재시도를 포함해 모든 추정 요청은 새로 과금되는 작업입니다. 이 예시는 자동으로 재시도하지 않습니다. 다른 요청을 보내기 전에 과금 상태를 확인하세요.
실행하기 전에: 접근과 오류 처리
이 예시는 서버에서 실행하세요. 프로세스 환경 변수 GENDERAPI_API_KEY에 기존 API 키를 설정하세요. 인식되지 않는 키는 IP 체험으로 전환될 수 있으므로 meta.access.mode가 api_key인지 확인하세요.
HTTP 4xx 및 5xx JSON 응답에서는 오류 본문을 그대로 출력하고 0이 아닌 종료 코드를 반환합니다. 재시도하기 전에 code, action과 meta.usage.billing_status를 확인하세요.
오류와 재시도 가이드 →POSIX 셸의 cURL 7.76+. 터미널에서 실행하세요. 런타임 문서
Node.js 22+, 내장 fetch. example.mjs로 저장하고 node example.mjs를 실행하세요. 런타임 문서
Python 3.10+, 표준 라이브러리. example.py로 저장하고 python3 example.py를 실행하세요. 런타임 문서
PHP 8+, cURL 확장. example.php로 저장하고 php example.php를 실행하세요. 런타임 문서
Java 17+, 표준 HTTP 클라이언트. GenderApiExample.java로 저장하고 java GenderApiExample.java를 실행하세요. 런타임 문서
.NET 8+ 콘솔 애플리케이션. 콘솔 프로젝트의 Program.cs로 사용한 다음 dotnet run을 실행하세요. 런타임 문서
Go 1.22+, 표준 라이브러리. main.go로 저장하고 go run main.go를 실행하세요. 런타임 문서
응답 예시
이 응답은 2026년 10월 1일에 API 키로 받은 실제 응답이며, 계정 잔액만 바꿨습니다. 정확도를 측정한 값이 아니며, 실제 요청에서는 다른 결과가 반환될 수 있습니다. API 키 요청에서는 meta.access.mode: api_key와 null인 IP 체험 전용 한도 필드가 반환되고, IP 체험 요청에서는 ip_trial이 반환됩니다. 추정 결과는 data에서, 작업의 과금 결과는 meta.usage에서 확인하세요.
{
"data": {
"input": {
"type": "username",
"value": "prenses",
"country": "TR",
"forceToGenderize": true
},
"name": "prenses",
"gender": "female",
"country": "TR",
"confidence": 0.9456521739130435,
"confidence_kind": "observed_frequency",
"sample_count": 184,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "prenses",
"method": "normalized",
"scope": "country",
"country": "TR"
}
},
"meta": {
"request_id": "a799faa4-bc1a-4537-90b3-2c1b60205499",
"duration_ms": 15,
"access": {
"mode": "api_key",
"reason": null
},
"usage": {
"charged_credits": 1,
"remaining_credits": 49999,
"billing_status": "confirmed",
"resets_at": null,
"limit": null,
"period_seconds": null
}
}
}추정 응답 필드
| 필드 | 유형 | null 허용 | 예시 | 설명 |
|---|---|---|---|---|
data.input | object | 아니요 | {"type":"name","value":"Jihoon","country":"KR"} | 입력 유형, 값과 국가입니다. forceToGenderize가 true이면 함께 포함됩니다. |
data.name | string | 예 | "jihoon" | 일치하거나 추출된 이름이며, 없으면 null입니다. |
data.gender | string | 예 | "male" | male, female 또는 JSON null. 확인된 개인 신원이 아닌 추정입니다. |
data.result_status | string | 아니요 | "identified" | 성별이 반환되면 identified, 그렇지 않으면 unknown입니다. |
data.reason | string | 예 | null | identified 결과에서는 null입니다. 알 수 없는 결과의 사유: not_found, no_name_candidate, ambiguous 또는 insufficient_evidence. |
data.confidence | number | 예 | 0.95 | 0~1 점수 또는 null. 성별이 null이면 신뢰도도 null입니다. |
data.confidence_kind | string | 예 | "observed_frequency" | observed_frequency: 가장 많은 성별의 데이터셋 건수 / 전체 건수. model_reported: 보정된 확률이 아닌 AI 점수. 확인할 수 없으면 null입니다. |
data.sample_count | integer | 예 | 1200 | 데이터셋 표본 수 또는 null. AI는 표본 수를 만들어 내지 않습니다. |
data.source | string | 아니요 | "dataset" | dataset, ai 또는 none. |
data.country | string | 예 | "KR" | dataset 또는 ai_association에서 나온 국가 연관성, 또는 null. 국적, 거주지, 민족을 나타내지 않습니다. |
data.country_source | string | 예 | "dataset" | 국가 연관성의 출처: dataset, ai_association 또는 null. |
data.match | object | 아니요 | {"name":"jihoon","method":"normalized","scope":"country","country":"KR"} | 일치한 데이터셋 이름, 일치 방법(normalized, token, substring 또는 model_inference), 국가/전역 범위와 일치한 국가입니다. 확인할 수 없는 근거는 null입니다. |
접근, 과금과 요청 메타데이터
| 필드 | 유형 | null 허용 | 예시 | 설명 |
|---|---|---|---|---|
meta.request_id | string | 아니요 | "550e8400-e29b-41d4-a716-446655440000" | 이 HTTP 시도의 고유 식별자이며 X-Request-ID로도 전송됩니다. |
meta.duration_ms | integer | 아니요 | 42 | 요청 처리 시간(밀리초)입니다. |
meta.access.mode | string | 아니요 | "api_key" | api_key, ip_trial 또는 unauthenticated. 유료 계정을 사용할 때는 api_key인지 확인하세요. |
meta.access.reason | string | 예 | null | IP 체험으로 전환된 사유: api_key_missing, api_key_invalid 또는 api_key_not_found. 그 외에는 null입니다. |
meta.usage.charged_credits | integer | 예 | 1 | 차감된 순 크레딧입니다. 차감 전이나 전액 반환이 확인된 뒤에는 0이며, 과금이 미확정이면 null입니다. |
meta.usage.remaining_credits | integer | 예 | 99 | 작업 완료 시점의 잔액입니다. 음수일 수 있으며, 확인할 수 없거나 과금이 미확정이면 null입니다. |
meta.usage.billing_status | string | 아니요 | "confirmed" | not_charged, confirmed 또는 unconfirmed. 실패한 추정을 재시도하기 전에 확인하세요. |
meta.usage.resets_at | string | 예 | "2026-09-27T12:00:00.000Z" | IP 체험 초기화 시각(UTC, ISO 8601)입니다. API 키 계정이거나 알 수 없으면 null입니다. |
meta.usage.limit | integer | 예 | 10 | IP 체험 크레딧 한도이며, API 키 계정에서는 null입니다. |
meta.usage.period_seconds | integer | 예 | 86400 | IP 체험 기간(초)이며, API 키 계정에서는 null입니다. |
별명 추정 결과 읽기
이 예시는 forceToGenderize: true를 사용합니다. 데이터셋 조회로 결과를 얻으면 1크레딧입니다. 그렇지 않으면 API가 AI에 별칭 해석을 요청하며, 알 수 없는 결과를 포함해 성공한 작업에는 총 2크레딧이 차감됩니다. ai_mode는 생략하거나 fallback으로 설정하세요. off와 always는 forceToGenderize와 함께 쓸 수 없으며 422를 반환합니다.
별명 모드에서는 name: null과 함께 추정된 성별이 반환될 수 있습니다. 이는 실제 이름을 추출하지 않았다는 뜻이며 파싱 오류가 아닙니다. AI가 성별을 반환하면 sample_count: null과 confidence_kind: model_reported가 포함됩니다. 이 점수는 보정된 확률이 아니며 확인된 신원도 아닙니다.
forceToGenderize가 없어도 단일 사용자 이름 조회는 기본적으로 일반 AI 폴백을 사용하며 총 1크레딧이지만, 사용할 수 있는 실제 이름이 있어야 합니다. 데이터셋만으로 처리하려면 options.ai_mode: off를 사용하세요.