Python으로 GenderAPI.io V2 사용하기

서버 측 Python 프로젝트 설정하기

이 가이드는 Bearer API 키로 GenderAPI.io V2 엔드포인트 https://api.genderapi.io/api/v2/gender를 호출합니다. Python 3.10 이상을 사용하고 genderapi_v2.py를 프로젝트에 내려받으세요. 예시는 Python 표준 라이브러리의 urllib.request와 json을 사용하므로 pip 패키지가 필요하지 않습니다.

서버 환경에 GENDERAPI_API_KEY를 설정하세요. 아래 예시의 YOUR_API_KEY는 유효한 키가 아닙니다. 실제 인증 정보는 커밋하는 파일, 공유하는 노트북, 클라이언트 측 애플리케이션에 넣지 마세요. 모듈을 가져오거나 데모 옵션 없이 실행하면 요청을 보내지 않습니다.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi_v2.py 내려받기 →
• 무료 사용량 엔드포인트로 키 확인하기 →

데이터셋만 사용하는 명시적 요청 하나 보내기

아래 코드를 내려받은 파일 옆에 single.py로 저장하고 python3 single.py를 실행하세요. 도우미 모듈은 type: name, value: Alice, options.ai_mode: off를 JSON으로 보냅니다. 추정 결과는 data에서, 요청과 과금 정보는 meta에서 읽으세요.

성공한 호출은 알 수 없는 결과를 포함해 1크레딧을 사용합니다. 예시 이름이 추정 결과를 보장하지는 않습니다. make_item은 name, email, username을 받으며 명시적인 AI 모드를 요구합니다. 관련된 컨텍스트가 있을 때만 country를 추가하세요.

도우미 모듈은 보내기 전에 24자리 16진수 API 키를 요구합니다. 이는 형식을 검증할 뿐, 키가 실제로 있는지는 확인하지 않습니다. 또한 접근 방식이 맞지 않는다는 이유로 성공한 IP 체험 응답을 거부합니다. 이 확인은 응답을 받은 뒤에 이루어지므로 IP 체험에서 이미 차감된 크레딧을 되돌릴 수 없습니다.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• 단일 요청의 모든 필드 →

결과와 근거를 함께 보관하기

추정된 연관성은 본인이 밝힌 성별이 아닙니다. 원래 입력값, 반환된 근거, 본인이 제공한 정보는 서로 구분해 보관하세요. 알 수 없는 결과도 유효한 결과이므로 애플리케이션에서 추측한 범주로 바꾸지 마세요.

• 응답 필드와 알 수 없는 결과 →
• 정확도와 신뢰도 설명 →
• 데이터 출처와 날짜가 명시된 데이터셋 개요 →

혼합 일괄 요청을 처리하고 행 ID 유지하기

GenderAPI.io V2는 혼합 일괄 요청에 POST https://api.genderapi.io/api/v2/gender/batch를 사용합니다. 계정 키로는 최대 50개 항목, IP 체험에서는 최대 10개 항목을 보낼 수 있습니다. 이 예시에는 계정 키가 필요합니다. 모든 항목에 안정적이고 고유한 id와 명시적인 AI 모드를 지정하세요. 일괄 요청 하나에 이름, 이메일 주소, 사용자 이름을 섞을 수 있으며, 항목마다 국가 컨텍스트를 선택적으로 지정할 수 있습니다.

data의 모든 항목과 meta.summary의 요약을 읽으세요. HTTP 200 응답에도 항목 오류가 들어 있을 수 있습니다. 모든 항목이 실패한 일괄 요청은 결과가 담긴 최상위 Problem 응답이 될 수 있습니다. 성공한 알 수 없는 결과는 succeeded로 집계됩니다. 원래의 index와 id로 각 결과를 올바른 원본 행에 연결할 수 있습니다.

큰 작업은 입력을 최대 50개씩 나누고 처음에는 순서대로 제출하세요. 다음으로 넘어가기 전에 각 응답과 사용량을 저장하세요. 전송 오류, 계정 오류, 과금이 확인되지 않은 실패가 발생하면 멈추고 현재 그룹을 대조하세요. 계정의 한도를 확인한 뒤에만 동시 요청을 추가하세요. 일괄 요청의 최대 크기가 처리량을 보장하지는 않습니다.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• 일괄 요청의 입력, 결과, 과금 →

AI를 사용할 시점 선택하기

forceToGenderize는 이름, 이메일 주소, 사용자 이름에 선택적으로 사용할 수 있습니다. 이 옵션을 켜면 ai_mode를 생략하거나 fallback을 사용하세요. off와 always는 함께 쓸 수 없으며 422를 반환합니다. 최종 차감으로 잔액이 0 아래로 내려가더라도 시작 잔액이 0보다 크면 요청을 시작할 수 있습니다.

별명 모드는 name: null과 함께 성별을 반환할 수 있으며, 알 수 없는 결과를 반환할 수도 있습니다. 일반 AI 폴백도 별명 추정도 정확하거나 null이 아닌 답을 보장하지 않습니다.

이 Python 도우미 모듈은 항상 ai_mode를 요구합니다. 별명 추정을 허용하려면 make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True)를 사용하세요. 도우미 모듈은 force_to_genderize를 JSON 필드 forceToGenderize로 변환합니다.

• AI 옵션과 별명 추정 →
• 크레딧과 사용량 →

실패한 뒤 할 일 정하기

예시는 각 작업을 한 번만 보내며 자동으로 재시도하지 않습니다. 다시 제출하면 새로 과금되는 작업이 됩니다. 시간 초과나 연결 실패는 클라이언트가 완전한 응답을 받지 못했다는 뜻일 뿐, 서버가 처리를 멈췄거나 크레딧이 차감되지 않았다는 증거가 아닙니다.

반환된 요청 ID와 과금 상태를 작업 기록과 함께 보관하세요. 오류 객체는 통제된 방식으로 확인할 수 있도록 응답을 보관하지만, 원래 입력이 포함될 수 있습니다. 객체 전체, 응답, API 키를 일반 로그에 기록하지 마세요.

• Problem Details와 재시도 판단 →
• 크레딧과 과금 확인 →

이 예시의 전송 동작 이해하기

urllib의 10초 시간 제한은 블로킹 소켓 작업에 적용되며, 요청 전체의 총 소요 시간에 대한 보장된 기한이 아닙니다. 예시는 HTTP 리디렉션을 끄고, 성공한 JSON 응답을 파싱하고, HTTP Problem 응답을 보관합니다. 자동으로 재시도하지 않습니다.

로컬 테스트는 성공, 알 수 없는 결과, 일부만 성공한 일괄 요청, 계정 접근, 실패에 대한 합성 전송 응답을 사용합니다. 테스트는 예시의 제어 흐름을 검증할 뿐이며, 운영 중인 API의 가용성, 추정 정확도, 프로덕션 응답 시간을 측정하지 않습니다. 아래의 선택형 데모 명령은 각각 과금되는 요청을 따로 보냅니다.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Python 문서: urllib.request →
• Python 문서: HTTPError →

자주 묻는 질문