GenderAPI.io V2 도움말
자주 묻는 질문
V2 요청, 신뢰도, 알 수 없는 결과, 크레딧, 개인정보 보호와 계정에 관한 답변입니다. 이전 버전으로 만든 연동을 운영 중이라면 V1 문서를 참고하세요.
결과 및 신뢰도
예측과 그 한계 이해하기
API V2의 국가 컨텍스트, 신뢰도와 알 수 없는 결과를 설명합니다.
GenderAPI 결과가 개인의 성별을 확정하나요?
아니요. GenderAPI는 이름과 관련된 신호, 또는 옵션을 켠 경우 별명의 신호로 성별을 추정합니다. 예측은 확인된 개인정보가 아닙니다. 불확실성을 그대로 유지하고, 본인이 밝힌 성별 정체성을 존중하며, 중대한 영향을 미치는 결정을 이 추정만으로 내리지 마세요.
국가 컨텍스트는 결과에 어떤 영향을 주나요?
대문자 ISO 국가 코드를 선택적으로 보내면 요청에 지역 컨텍스트가 더해집니다. 국가가 관련이 있고 알려진 경우에만 보내세요. 같은 이름도 지역마다 다르게 쓰일 수 있습니다. 반환되는 국가는 이름과의 연관성을 나타낼 뿐 국적이나 거주지를 증명하지 않습니다.
V2의 신뢰도는 무엇을 의미하나요?
confidence는 0부터 1까지의 값이며, 값이 없으면 null입니다. confidence_kind와 함께 해석하세요. observed_frequency는 데이터셋에서 가장 많은 범주의 건수를 전체 건수로 나눈 값이고, model_reported는 AI가 보고한 값입니다. 이 값들은 개인에 대해 보정된 확률도, 측정된 제품 정확도도 아닙니다. 수동 검토 기준은 대표성 있는 데이터로 정하세요.
gender: null은 무엇을 의미하며 과금되나요?
gender: null이 포함된 정상 V2 결과는 사용할 수 있는 신호만으로 성별을 판단할 수 없었다는 뜻입니다. 이는 문자열 "null"이 아니라 JSON 기본 null 값입니다. 정상 처리된 알 수 없는 결과는 선택한 모드의 요금으로 과금됩니다. 알 수 없는 결과로 그대로 처리하세요. 제공업체나 요청의 실패는 별도의 오류입니다.
여러 문자 체계의 이름을 보낼 수 있나요?
예. 이름은 원래 문자와 의미 있는 발음 구별 기호를 유지한 채 Unicode로 보내세요. 한글 이름은 한글 그대로 보내면 됩니다. 지원 범위와 신뢰도는 이름, 지역과 사용할 수 있는 신호에 따라 달라지므로, 애플리케이션이 다루는 문자 체계와 국가를 대표하는 표본으로 테스트하세요.
API 및 AI
요청 유형과 AI 옵션 선택하기
V2 요청 유형, 일괄 요청, AI 사용 방식과 이용 한도를 설명합니다.
이름, 이메일 주소, 사용자 이름을 하나의 일괄 요청으로 분석할 수 있나요?
예. POST /api/v2/gender/batch는 API 키를 사용하면 최대 50개 항목, IP 체험에서는 최대 10개 항목을 받습니다. 각 항목에는 별도의 type, value, 선택적 country와 AI 설정을 지정할 수 있습니다. 일괄 요청 항목의 AI는 기본적으로 꺼져 있습니다. 일부 항목이 실패해도 일괄 요청은 HTTP 200을 반환할 수 있으므로 결과를 항목마다 확인하세요. 크레딧은 알 수 없는 결과를 포함해 정상 처리된 항목마다 차감됩니다.
이메일 주소 요청은 어떻게 작동하나요?
유효한 주소와 함께 type: email을 사용하세요. API는 @ 앞의 로컬 부분에서 사용할 수 있는 이름 신호를 찾습니다. 도메인으로 개인의 신원이나 국가를 알 수는 없습니다. 공용 메일함이나 이름 신호가 없는 주소는 알 수 없는 결과가 될 수 있습니다. 단일 요청은 데이터셋에서 결과를 얻지 못하면 기본적으로 AI를 사용합니다.
사용자 이름 요청은 어떻게 작동하나요?
type: username을 사용하세요. 일반 요청은 사용자 이름이나 표시 이름에서 알아볼 수 있는 이름을 찾습니다. 추상적인 별칭은 알 수 없는 결과가 될 수 있습니다. 데이터셋에서 결과를 얻지 못한 뒤 별명을 해석하는 AI를 사용하려면 forceToGenderize를 켜세요. 이 경우 실제 이름을 추출하지 못해도 성별이 추정될 수 있습니다.
V2는 언제 AI를 사용하나요?
단일 요청의 기본값은 options.ai_mode: fallback입니다. 먼저 데이터셋을 조회하고 성별을 판단할 수 없으면 AI를 사용하며, 총 1크레딧입니다. off는 데이터셋만 사용하며 1크레딧, always는 데이터셋을 건너뛰고 AI를 사용하며 2크레딧입니다. 일괄 요청 항목의 기본값은 off이며 항목별로 AI를 켤 수 있습니다. 어떤 모드도 null이 아닌 결과를 보장하지 않습니다.
forceToGenderize는 어떤 역할을 하나요?
이 선택적 플래그는 일괄 요청의 개별 항목을 포함해 이름, 이메일 주소, 사용자 이름 입력에 사용할 수 있습니다. 데이터셋에서 판단한 결과는 1크레딧입니다. 그렇지 않으면 별명을 해석하는 AI가 사용되며, 정상 결과가 알 수 없는 결과로 남더라도 총 2크레딧입니다. 실제 이름은 필요하지 않습니다. ai_mode를 생략하거나 fallback을 사용하세요. 이 플래그를 off 또는 always와 함께 쓰면 422가 반환됩니다.
V2에서는 크레딧이 어떻게 차감되나요?
작업에 실제로 차감된 크레딧은 meta.usage.charged_credits에서, 차감이 확정되었는지는 billing_status에서 확인하세요. 일반 데이터셋 예측과 fallback 모드 예측은 정상 처리된 항목마다 1크레딧이고, always와 별명을 해석하는 AI는 2크레딧입니다. 전화번호 검증이 완료되면 결과가 유효하지 않아도 1크레딧입니다. 시작 잔액이 양수이면 충분하므로 최종 차감 후 잔액이 마이너스가 될 수 있습니다. 실패한 예측의 크레딧은 반환되며, 확인되지 않은 차감은 지원팀의 확인이 필요합니다.
V2에 요청 한도가 있나요?
예. 현재 기본값은 계정당 분당 120개 요청, IP당 분당 600개 요청, 계정당 동시 작업 2개입니다. 서비스 전체의 공유 용량도 영향을 줍니다. POST 요청 본문은 64 KiB로 제한되며, 일괄 요청은 키를 사용하면 50개 항목, IP 체험에서는 10개 항목까지 받습니다. 이 한도 안의 요청이 항상 수락된다고 가정하지 말고 HTTP 429와 Retry-After를 처리하세요.
실패하거나 시간이 초과된 요청을 다시 보낼 수 있나요?
예측 요청은 보낼 때마다 새 작업으로 처리되며 일반 요금이 적용됩니다. 시간 초과나 응답 유실이 크레딧이 차감되지 않았다는 뜻은 아닙니다. 다시 보내기 전에 billing_status를 확인하고, 차감이 확인되지 않았다면 request_id를 첨부해 지원팀에 문의하세요. 일부가 실패한 일괄 요청은 차감이 확인된 뒤 실패한 항목만 다시 보내세요. 429 응답에는 Retry-After 헤더를 따르세요.
V2 코드 예시와 도구는 어디에 있나요?
V2 가이드에는 cURL, JavaScript, Python, PHP, Java, C#, Go 예시가 있습니다. Swagger와 Postman도 같은 V2 계약을 사용합니다. 입력 유형을 선택하고, API 키는 서버 측 설정에 보관하세요.
V1을 계속 사용할 수 있나요?
예. 기존 V1 연동은 원래의 엔드포인트와 응답 형식을 그대로 유지합니다. V1과 V2는 같은 API 키와 같은 잔액을 사용하지만 요청 필드, 응답과 오류가 다릅니다. 기존 클라이언트를 유지하려면 별도의 V1 문서를, V2로 전환하려면 마이그레이션 가이드를 참고하세요.
개인정보 및 파일
데이터 처리 방식 이해하기
처리, 보관 및 삭제에 관한 최신 정보를 확인할 수 있는 곳입니다.
정상 처리된 GenderAPI 요청은 저장되나요?
어떤 요청 데이터, 운영 기록과 보안 로그가 보관될 수 있는지, 어떤 목적으로 처리되는지, 어떻게 삭제되는지는 개인정보 처리방침에서 설명합니다. 사용하는 연동에 맞게 이 정보를 확인하고, 불필요한 개인정보는 보내지 마세요.
요청에 포함된 이메일 주소는 저장되나요?
요청에 포함된 이메일 주소와 관련 기술 기록의 처리 방식은 개인정보 처리방침에서 설명합니다. 이메일 주소는 개인정보에 해당할 수 있으므로 요청에 필요한 정보만 보내고, 자체 진단 로그에 전체 주소를 남기지 마세요.
업로드한 Excel 또는 CSV 파일은 얼마나 오래 보관되나요?
서비스 제공업체가 요청 데이터나 업로드 파일을 처리할 수 있나요?
서비스 제공업체가 데이터를 처리하는 방식과 적용되는 보호 조치는 개인정보 처리방침과 하위 처리자 정보에서 설명합니다. 데이터가 어디에서 처리되는지 평가할 때는 이 문서들과 계정에 적용되는 계약을 확인하세요.
계정 및 지원
API 키 연결과 계정 관리
무료 사용, 인증, 잔액 확인과 지원에 관한 안내입니다.
GenderAPI를 무료로 사용해 볼 수 있나요?
예. 가입한 무료 계정에는 매일 200크레딧이 제공됩니다. 이와 별도로 키 없이 사용하는 V2 IP 체험은 공개 IP 주소마다 24시간에 10크레딧을 제공하며, 이 크레딧은 V1 및 같은 IP 주소의 다른 사용자와 공유됩니다. 두 경우 모두 일반 요금이 적용되므로 크레딧 수가 HTTP 요청 횟수와 항상 같지는 않습니다.
요청을 인증하고 API 키를 보호하려면 어떻게 해야 하나요?
신뢰할 수 있는 서버 측 코드에서 Authorization: Bearer YOUR_API_KEY를 사용하세요. POST 요청에는 Content-Type: application/json도 필요합니다. 실제 키를 브라우저 코드, 공개 저장소와 로그에 넣지 마세요. 키가 없거나, 형식이 잘못되었거나, 인식되지 않으면 IP 체험이 사용될 수 있으므로 meta.access.mode가 api_key인지 확인하세요. 인식된 키가 비활성화, 만료 또는 제한된 경우에는 체험으로 전환되지 않습니다.
남은 크레딧은 어떻게 확인하나요?
Bearer 키로 GET /api/v2/usage를 호출하세요. 이 잔액 확인은 무료이며 data.remaining_credits를 반환합니다. 키 없이 호출하면 공유 IP 체험의 잔액을 읽습니다. V1과 V2는 같은 계정 잔액을 사용합니다. 예측 응답의 remaining_credits는 작업이 완료된 시점의 잔액입니다.
구독은 어디에서 관리하거나 취소하나요?
GenderAPI 앱에 로그인해 API 키에 연결된 구독을 관리하세요. 현재 계정 설정에서 요금제와 취소 옵션을 확인할 수 있습니다.
결제 정보는 어디에서 변경하나요?
GenderAPI 앱에 로그인하면 API 키 또는 구독별 청구 및 결제 설정을 관리할 수 있습니다.
잘못된 결과를 신고하거나 연동 지원을 받으려면 어떻게 하나요?
API 버전, 엔드포인트, request_id와 재현 가능한 짧은 예시를 지원팀에 보내세요. 오류 코드가 있으면 함께 보내되, API 키와 민감한 개인정보는 제거하세요.
기술 지식 베이스
구현 및 책임 있는 사용 가이드
V2 결과, 개인정보 보호와 운영에 관한 답변입니다. 관련 가이드 링크와 답변별 Markdown 버전을 제공합니다.
결과, 신뢰도 및 책임 있는 사용
V2에서 성별을 판단하지 못한 예측은 gender에 문자열 "null"이 아니라 JSON 기본 null 값을 반환합니다. 이름이 모호하거나 사용할 수 있는 신호가 충분하지 않을 수 있으므로, result_status와 reason이 있으면 확인하세요. 결과를 억지로 한 범주에 넣지 말고 알 수 없는 결과로 유지하세요. 정상 처리된 알 수 없는 예측은 선택한 모드의 요금으로 과금됩니다. 요청이나 제공업체의 실패는 별도의 오류이며, 과금 정보는 meta.usage에 있습니다.
전체 답변 읽기 →GenderAPI의 정확도는 어떻게 평가하나요?의미 있는 정확도 평가는 평가 대상 집단, 평가 날짜, 표본 추출 방법, 알 수 없는 결과의 비율, 지역별·문자 체계별 결과를 함께 보고합니다. 현재 평가 방법 페이지는 평가 절차를 설명할 뿐, 측정된 정확도 백분율을 제시하지 않습니다. V2의 confidence와 confidence_kind는 각 결과의 근거를 설명하지만, 대표성 있는 데이터로 하는 평가를 대신하지는 않습니다.
전체 답변 읽기 →데이터 출처, 개인정보 보호 및 규정 준수
데이터 출처 페이지는 출처 범주, 선정 기준, 라이선스, 지역과 문자 체계의 제약을 기록하는 틀을 설명합니다. 검증된 출처 목록은 아직 공개되지 않았습니다. 해당 페이지를 확인하고, 연동에 출처 관련 요구 사항이 있으면 지원팀에 문의하세요. 문서화되지 않은 출처, 데이터셋 규모나 지원 범위 수치를 가정하지 마세요.
전체 답변 읽기 →이름 데이터는 얼마나 자주 업데이트되나요?현재 데이터 출처 페이지에는 모든 이름 레코드나 처리 규칙에 공통으로 적용되는 업데이트 일정이 나와 있지 않습니다. 데이터가 얼마나 최신인지가 용도에 중요하다면 해당 데이터셋이나 워크플로에 관해 지원팀에 문의하고, 대표적인 결과를 테스트하세요. 페이지의 검토 날짜가 그날 모든 기반 레코드가 업데이트되었다는 뜻은 아닙니다.
전체 답변 읽기 →GDPR과 데이터 처리 계약 정보는 어디에서 확인하나요?개인정보 처리방침, GDPR 안내, 데이터 처리 계약과 하위 처리자 목록에서 공개된 처리 조건과 보호 조치를 설명합니다. 최신 문서와 계정에 적용되는 계약을 검토하세요. 처리상의 역할, 데이터 이전, 정보주체의 요청 등 조직에 해당하는 질문은 GenderAPI에 문의하세요. 일반적인 FAQ 답변은 적용되는 계약을 대신하지 않습니다.
전체 답변 읽기 →API 운영, 오류 및 과금
신뢰할 수 있는 서버 측 코드에서 Authorization: Bearer YOUR_API_KEY를 사용하세요. V2의 POST 요청에는 Content-Type: application/json도 필요합니다. GET /api/v2/gender는 쿼리 매개변수로도 키를 받지만, 헤더를 사용하면 인증 정보가 브라우저 URL에 드러나지 않습니다. 키가 없거나, 형식이 잘못되었거나, 인식되지 않으면 공유 IP 체험이 사용될 수 있으므로 계정 연동에서는 meta.access.mode가 api_key인지 확인하세요. 인식된 키가 비활성화, 만료 또는 제한된 경우에는 체험으로 전환되지 않습니다.
전체 답변 읽기 →요청 한도와 재시도는 어떻게 처리하나요?V2는 요청 수와 동시 요청에 한도를 적용하므로 HTTP 429와 Retry-After를 처리하세요. 다시 보낸 예측은 각각 새 작업으로 일반 요금이 적용됩니다. 시간 초과, 응답 유실 또는 차감이 확인되지 않은 경우에는 자동으로 재시도하지 마세요. 먼저 code, action과 meta.usage.billing_status를 확인하고, billing_reconciliation_required이면 request_id를 첨부해 지원팀에 문의하세요. 제한된 백오프는 차감이 확인되었고 문서화된 action이 재시도를 허용할 때만 사용하세요.
전체 답변 읽기 →V2 오류는 어떻게 해석하나요?V2 API 오류는 HTTP 오류 상태 코드와 안정적인 code 및 action 필드가 포함된 RFC 9457 Problem Details를 사용합니다. detail의 문구를 비교하지 말고 이 필드를 기준으로 오류를 처리하며, 지원 문의를 위해 request_id를 보관하세요. 입력 검증이나 설정 오류처럼 영구적인 오류는 요청을 수정해야 하고, 일시적인 오류는 차감이 확인된 뒤에만 재시도하세요. 정상 처리된 알 수 없는 결과는 오류가 아닙니다. 일괄 요청 응답은 HTTP 200이어도 항목별 오류를 포함할 수 있습니다. 프록시가 JSON이 아닌 오류를 반환할 수 있으며, 응답이 유실되었거나 읽을 수 없다고 해서 크레딧이 차감되지 않았다는 뜻은 아닙니다.
전체 답변 읽기 →남은 크레딧은 어떻게 확인하나요?신뢰할 수 있는 서버 측 코드에서 Bearer 헤더에 API 키를 넣어 GET /api/v2/usage를 호출하세요. 이 요청은 무료이며 data.remaining_credits를 반환합니다. 키를 생략하면 공유 IP 체험의 잔액을 읽습니다. V1과 V2는 같은 계정 잔액을 사용합니다. 예측 응답의 meta.usage는 해당 작업의 비용과 완료 시점의 잔액을 보여 주며, 동시에 실행된 요청에 따라 달라질 수 있습니다. 인증 정보를 로그에 남기지 말고, 잔액 확인을 응답이 유실된 특정 요청이 과금되지 않았다는 증거로 보지 마세요.
전체 답변 읽기 →V1에서 V2로 안전하게 마이그레이션하려면 어떻게 하나요?새 연동은 V2로 구축하고, 기존 V1 클라이언트는 전환을 결정할 때까지 문서화된 엔드포인트를 그대로 사용하세요. 두 버전은 같은 API 키와 크레딧을 사용하지만 요청 필드, 응답 구조와 오류 형식이 다릅니다. 마이그레이션 가이드를 따르고, 정상 결과, 알 수 없는 결과와 오류를 테스트한 뒤 엔드포인트를 바꾸기 전에 응답 처리 로직을 업데이트하세요. V1 문서는 기존 연동을 위해 계속 제공됩니다.
전체 답변 읽기 →오류를 조사하고 서비스 가용성을 모니터링하려면 어떻게 하나요?요청이 실패하면 반환된 오류 코드로 서비스 장애와 잘못된 입력, 계정 접근 문제, 크레딧 부족, 요청 한도를 구분하세요. 자체 연동에서 요청 성공률과 응답 시간을 모니터링하세요. 원인을 알 수 없는 실패나 불확실한 차감이 있으면 request_id를 첨부해 지원팀에 문의하세요. 가용성에 관한 주장은 측정된 모니터링 데이터에 근거해야 하며, 이 답변은 가용성 비율을 보장하지 않습니다.
전체 답변 읽기 →도움이 더 필요한가요?
재현 가능한 예제를 보내주세요
엔드포인트, 요청 매개변수, 반환된 오류를 포함하되 운영 API 키나 민감한 개인정보는 보내지 마세요.