JavaScript와 Node.js로 GenderAPI.io V2 사용하기

Node.js 서버에서 연동 유지하기

이 가이드는 Bearer API 키로 GenderAPI.io V2 엔드포인트 https://api.genderapi.io/api/v2/gender를 호출합니다. Node.js 22 이상을 사용하고 genderapi-v2.mjs를 프로젝트에 내려받으세요. 이 ES 모듈은 내장 fetch와 AbortSignal.timeout을 사용하므로 npm 패키지가 필요하지 않습니다. .mjs 확장자 덕분에 package.json을 바꾸지 않고 다른 ES 모듈에서 가져올 수 있습니다.

서버 환경에 GENDERAPI_API_KEY를 설정하세요. 키를 React, Vue 또는 브라우저용 JavaScript에 번들링하지 마세요. 애플리케이션 사용자는 자체 서버에서 인증하고, 그 서버가 GenderAPI.io를 호출하게 하세요. 아래 예시의 YOUR_API_KEY는 유효한 키가 아닙니다. 모듈을 가져오거나 명시적인 실행 옵션 없이 실행하면 요청을 보내지 않습니다.

node --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi-v2.mjs 내려받기 →
• 무료 사용량 엔드포인트로 키 확인하기 →

명시적인 AI 정책으로 JSON POST 하나 보내기

코드를 내려받은 모듈 옆에 single.mjs로 저장하고 node single.mjs를 실행하세요. V2 필드 type과 value를 options.ai_mode: off와 함께 보냅니다. 추정 결과는 response.data에서, 요청과 과금 정보는 response.meta에서 읽으세요.

완료된 조회는 gender가 null이어도 1크레딧입니다. 예시 이름이 특정 결과를 보장하지는 않습니다.

도우미 모듈은 명시적인 AI 모드와 24자리 16진수 키를 요구하고, 그다음 meta.access.mode가 api_key인지 확인합니다. IP 체험의 성공 응답을 받으면 말없이 계속하지 않고 접근 방식 불일치 오류를 발생시킵니다. 도우미 모듈이 불일치를 감지하기 전에 서버가 이미 IP 체험 크레딧을 사용했을 수 있습니다.

import { predict, GenderAPIError } from "./genderapi-v2.mjs";

try {
  const response = await predict({
    type: "name", value: "Alice", options: { ai_mode: "off" },
  });
  const result = response.data;
  console.log(result.result_status, result.gender);
  console.log(result.confidence, result.confidence_kind);
  console.log(response.meta.usage);
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // Do not log error.body: it can include the submitted value.
  console.error("Request failed:", error.code, error.requestId);
  process.exitCode = 1;
}

• 단일 요청의 모든 필드 →

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

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

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

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

import { predictBatch, GenderAPIError } from "./genderapi-v2.mjs";

const items = [
  { id: "row-1", type: "name", value: "Alice", options: { ai_mode: "off" } },
  { id: "row-2", type: "email", value: "alex@example.com", options: { ai_mode: "off" } },
  { id: "row-3", type: "username", value: "sample_handle", options: { ai_mode: "off" } },
];
try {
  const response = await predictBatch(items);
  for (const item of response.data) {
    if (item.error) {
      console.log(item.id, "failed", item.error.code);
    } else {
      console.log(item.id, item.data.result_status, item.data.gender);
    }
  }
  console.log(response.meta.summary, response.meta.usage);
  if (response.meta.summary.failed > 0) process.exitCode = 2;
} catch (error) {
  if (!(error instanceof GenderAPIError)) throw error;
  // error.body can retain an all-failed batch and billing details.
  console.error("Batch needs review:", error.code, error.requestId);
  process.exitCode = 1;
}

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

AI를 사용할 시점 선택하기

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

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

이 JavaScript 도우미 모듈은 항상 options.ai_mode를 요구합니다. 별명 추정을 사용하려면 options: { ai_mode: 'fallback' }과 함께 forceToGenderize: true를 보내세요.

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

실패한 뒤 할 일 정하기

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

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

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

fetch 시간 제한과 응답 확인 이해하기

기본 시간 제한은 AbortSignal.timeout을 사용한 10,000밀리초이며, 응답 본문을 읽는 시간도 포함합니다. 클라이언트가 요청을 중단해도 서버의 처리나 과금이 멈췄다는 뜻은 아닙니다. 모듈은 리디렉션을 끄고, HTTP 실패와 읽을 수 없는 응답을 구분하며, 자동으로 재시도하지 않습니다.

합성 전송 응답을 사용하는 테스트는 성공 응답, 알 수 없는 결과, 일부만 성공한 일괄 요청, 인증 정보 대체 처리, 오류를 다룹니다. 이 테스트에는 실제 추정이나 크레딧 작업이 필요하지 않으며, 운영 환경의 가용성이나 정확도를 측정하는 벤치마크가 아닙니다. 아래의 선택형 데모 명령은 각각 과금되는 요청을 따로 보냅니다.

node genderapi-v2.mjs --run-single
# Run separately to submit another billable sample batch:
node genderapi-v2.mjs --run-batch

• Node.js 문서: fetch →
• Node.js 문서: AbortSignal.timeout →

자주 묻는 질문