GenderAPI.io V2 · 가이드

인도 이름으로 성별 추정하기

GenderAPI.io V2로 인도에서 쓰이는 이름을 입력해 보세요. 원래 철자를 유지하고, IN 컨텍스트를 신중하게 선택하고, 전체 이름, AI와 알 수 없는 결과를 해석하는 방법을 알아보세요.

최종 업데이트:

V2 API 사용해 보기

이름 분석하기

데이터셋 + AI

값을 하나 보내면 알 수 없는 결과와 사용한 크레딧을 포함한 전체 응답을 확인할 수 있습니다.

이 도구는 예시로 인도(IN) 국가 컨텍스트를 사용합니다. 이 언어의 모든 이름에 적용되는 기본값이 아니며 국적을 나타내지도 않습니다.

일반 요청: AI 폴백과 알 수 없는 결과를 포함해 1크레딧. 별명 해석 사용 시: 데이터셋에서 결과를 얻으면 1크레딧, AI를 사용하면 결과가 알 수 없음이어도 총 2크레딧.

보내는 값(이름)은 GenderAPI.io로 전송되며, AI 폴백이 필요하면 설정된 AI 서비스로 전달될 수 있습니다. 데이터 처리 방식 자세히 보기.

저장된 API 키가 없습니다. 크레딧이 남아 있는 동안 공유 IP 체험을 사용할 수 있습니다.

아래 응답은 설명용 예시입니다. 분석을 선택하면 요청을 보냅니다.

V2 응답 예시 · 실시간 결과 아님
이름—
성별알 수 없음
신뢰도—
출처AI 모델
사용한 크레딧1

예시의 빈도, 값과 잔액은 응답 형식을 보여 줄 뿐이며 실제 값은 다를 수 있습니다. 추정 결과는 확인된 신원이 아닙니다.

하나의 문자 체계나 작명 방식을 가정하지 않고 원래 이름 사용하기

이 데모는 데바나가리 예시와 IN 국가 컨텍스트를 사용합니다. 이는 입력 예시 하나일 뿐이며, 인도에서 쓰이는 모든 이름을 정의하지 않습니다. API는 유니코드 문자열을 받으므로 레코드에 있는 철자를 라틴 문자로 먼저 바꾸지 않고 그대로 보낼 수 있습니다.

현재 데이터셋 조회는 정규화된 토큰을 사용합니다. 일반적인 문자 체계 변환은 하지 않으며, 라틴 문자 철자와 원래 문자 체계의 철자가 같은 행으로 연결된다고 약속하지도 않습니다. 반환된 이름과 함께 원래 입력을 보관하세요. 어떤 문자 체계를 받는다고 해서 그 언어나 공동체에 대해 독립적으로 측정된 정확도가 있다는 뜻은 아닙니다.

첫 번째나 마지막 토큰에 고정된 역할이 있다고 가정하지 마세요. V2는 특정 위치의 이름을 보장하지 않고, 사용할 수 있는 후보 행 가운데 저장된 합계가 가장 큰 행을 선택합니다. 이니셜, 짧은 토큰, 저장된 일치 결과가 없는 경우에는 데이터셋 결과가 나오지 않을 수 있으며, AI 폴백은 제출한 전체 값을 시도할 수 있습니다.

입력 예시의미확인할 점
प्रिया शर्मा데바나가리 전체 이름 예시여러 토큰이 후보가 될 수 있습니다. 첫 번째 토큰이 선택된다고 가정하지 말고 선택된 이름과 일치 결과를 확인하세요.
Priya Sharma라틴 문자 예시별도의 입력 철자입니다. 문자 체계가 달라도 같은 결과가 나온다는 약속은 없습니다.
A. Kumar이니셜과 이름 토큰한 글자 이니셜은 데이터셋 후보가 되지 않습니다. 다른 토큰이 일치했다고 해서 의도한 이름이 확인되는 것은 아닙니다.
country: IN인도 데모 컨텍스트이름이 이 가이드에 나온다는 이유만으로 쓰지 말고, 레코드에 관련된 국가 컨텍스트가 있을 때 사용하세요.

IN 국가 컨텍스트를 신중하게 선택하기

실시간 데모는 country: IN(인도) 컨텍스트를 보냅니다. API는 이름의 문자 체계를 보고 이 국가를 고르지 않습니다. 연동에서는 알고 있고 관련된 컨텍스트를 사용하거나 country를 생략하세요. 이 예시 값을 모든 레코드의 기본값으로 삼지 마세요.

각 후보에 대해 데이터셋 조회는 국가별 행이 있으면 그 행을 우선하고, 없으면 전역 행을 검토합니다. 그런 다음 사용할 수 있는 후보 가운데 저장된 합계가 가장 큰 후보를 선택합니다. 실제 일치 범위는 data.match.scope와 data.match.country에서 확인하세요. 모호한 국가별 행은 전역 결과로 자동 대체되지 않으며, 폴백에서는 그 대신 AI가 사용될 수 있습니다.

data.input.country는 요청의 컨텍스트를 나타냅니다. data.country와 data.country_source는 반환된 연관성을 나타냅니다. 둘은 서로 다른 필드이며 시민권, 민족, 거주지를 나타내지 않습니다.

V2로 인도 이름 보내기

GENDERAPI_API_KEY에 기존 API 키를 설정하고 서버에서 요청을 실행하세요. 이 예시는 일반 AI 폴백을 명시적으로 활성화합니다. 요청의 형태를 보여 줄 뿐이며, 측정된 추정 결과나 커버리지 결과가 아닙니다. 데이터셋만 사용하려면 options.ai_mode: off를 사용하세요.

프로그래밍 언어를 선택하세요. API 키 설정하기, 그다음 서버에서 예시를 실행하세요.

재시도를 포함해 모든 추정 요청은 새로 과금되는 작업입니다. 이 예시는 자동으로 재시도하지 않습니다. 다른 요청을 보내기 전에 과금 상태를 확인하세요.

실행하기 전에: 접근과 오류 처리

이 예시는 서버에서 실행하세요. 프로세스 환경 변수 GENDERAPI_API_KEY에 기존 API 키를 설정하세요. 인식되지 않는 키는 IP 체험으로 전환될 수 있으므로 meta.access.mode가 api_key인지 확인하세요.

HTTP 4xx 및 5xx JSON 응답에서는 오류 본문을 그대로 출력하고 0이 아닌 종료 코드를 반환합니다. 재시도하기 전에 code, action과 meta.usage.billing_status를 확인하세요.

오류와 재시도 가이드 →
cURL
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
}'

POSIX 셸의 cURL 7.76+. 터미널에서 실행하세요. 런타임 문서

JavaScript / Node.js
// Server-side Node.js. Save as example.mjs.
const apiKey = process.env.GENDERAPI_API_KEY;
if (!apiKey) throw new Error("Set GENDERAPI_API_KEY");
const body = {
  "type": "name",
  "value": "प्रिया शर्मा",
  "country": "IN",
  "options": {
    "ai_mode": "fallback"
  }
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify(body),
  signal: AbortSignal.timeout(30_000),
  redirect: "error",
});
const raw = await response.text();
if (!(response.headers.get("content-type") ?? "").includes("json")) {
  throw new Error(`HTTP ${response.status}: expected JSON; request ID ${response.headers.get("x-request-id")}`);
}
const result = JSON.parse(raw); // Also accepts application/problem+json.
if (!response.ok) {
  console.error(`HTTP ${response.status}`, result);
  process.exitCode = 1; // A retry is a new operation; inspect billing first.
} else {
  console.log(JSON.stringify(result, null, 2));
  // For batches, inspect every item: HTTP 200 may contain item errors.
}

Node.js 22+, 내장 fetch. example.mjs로 저장하고 node example.mjs를 실행하세요. 런타임 문서

Python
import json
import os
import sys
import urllib.error
import urllib.request

api_key = os.environ.get("GENDERAPI_API_KEY")
if not api_key:
    raise RuntimeError("Set GENDERAPI_API_KEY")
body = json.loads("{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}")

class NoRedirect(urllib.request.HTTPRedirectHandler):
    def redirect_request(self, req, fp, code, msg, headers, newurl):
        return None

request = urllib.request.Request(
    "https://api.genderapi.io/api/v2/gender",
    method="POST",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": "Bearer " + api_key,
        "Content-Type": "application/json",
    },
)
opener = urllib.request.build_opener(NoRedirect())
try:
    response = opener.open(request, timeout=30)
except urllib.error.HTTPError as error:
    response = error  # Keep the Problem Details body on non-2xx responses.
with response:
    status = response.status
    raw = response.read().decode("utf-8")
    if "json" not in response.headers.get("Content-Type", ""):
        raise RuntimeError(f"HTTP {status}: expected a JSON response")
    result = json.loads(raw)
print(json.dumps(result, indent=2), file=sys.stderr if status >= 300 else sys.stdout)
if not 200 <= status < 300:
    sys.exit(1)  # Inspect code, action and billing before retrying.
# For batches, inspect every item even when HTTP status is 200.

Python 3.10+, 표준 라이브러리. example.py로 저장하고 python3 example.py를 실행하세요. 런타임 문서

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"प्रिया शर्मा","country":"IN","options":{"ai_mode":"fallback"}}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($body, JSON_THROW_ON_ERROR),
]);
$raw = curl_exec($ch);
if ($raw === false) {
    throw new RuntimeException(curl_error($ch));
}
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$contentType = curl_getinfo($ch, CURLINFO_CONTENT_TYPE) ?: '';
curl_close($ch);
if (strpos($contentType, 'json') === false) {
    throw new RuntimeException("HTTP $status: expected a JSON response");
}
$result = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
$output = json_encode($result, JSON_PRETTY_PRINT | JSON_THROW_ON_ERROR) . PHP_EOL;
if ($status < 200 || $status >= 300) {
    fwrite(STDERR, $output); // Preserve the Problem Details body.
    exit(1);
}
echo $output;
// For batches, inspect every item; HTTP 200 can contain item errors.

PHP 8+, cURL 확장. example.php로 저장하고 php example.php를 실행하세요. 런타임 문서

Java
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class GenderApiExample {
    private static String requiredEnv(String name) {
        String value = System.getenv(name);
        if (value == null || value.isBlank()) throw new IllegalStateException("Set " + name);
        return value;
    }

    public static void main(String[] args) throws Exception {
        String apiKey = requiredEnv("GENDERAPI_API_KEY");
        String body = "{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        HttpClient client = HttpClient.newBuilder()
            .connectTimeout(Duration.ofSeconds(10))
            .followRedirects(HttpClient.Redirect.NEVER)
            .build();
        HttpRequest request = HttpRequest.newBuilder(URI.create("https://api.genderapi.io/api/v2/gender"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .header("Content-Type", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
            .build();
        HttpResponse<String> response = client.send(request,
            HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8));
        if (!response.headers().firstValue("content-type").orElse("").contains("json")) {
            throw new IllegalStateException("HTTP " + response.statusCode() + ": expected JSON");
        }
        // JSON text; parse with your application's JSON library when integrating.
        if (response.statusCode() < 200 || response.statusCode() >= 300) {
            System.err.println(response.body()); // Includes Problem Details.
            System.exit(1);
        }
        System.out.println(response.body());
        // For batches, inspect each item's data or error, including on HTTP 200.
    }
}

Java 17+, 표준 HTTP 클라이언트. GenderApiExample.java로 저장하고 java GenderApiExample.java를 실행하세요. 런타임 문서

C# / .NET
using System;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string RequiredEnv(string name) =>
    !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(name))
        ? Environment.GetEnvironmentVariable(name)!
        : throw new InvalidOperationException($"Set {name}");

var apiKey = RequiredEnv("GENDERAPI_API_KEY");
using var handler = new HttpClientHandler { AllowAutoRedirect = false };
using var client = new HttpClient(handler) { Timeout = TimeSpan.FromSeconds(30) };
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.genderapi.io/api/v2/gender");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}", Encoding.UTF8, "application/json");

using var response = await client.SendAsync(request);
var raw = await response.Content.ReadAsStringAsync();
if (!(response.Content.Headers.ContentType?.MediaType?.Contains("json") ?? false))
    throw new InvalidOperationException($"HTTP {(int)response.StatusCode}: expected JSON");
using var result = JsonDocument.Parse(raw);
if (!response.IsSuccessStatusCode)
{
    Console.Error.WriteLine(result.RootElement); // Preserve Problem Details.
    Environment.ExitCode = 1;
}
else
{
    Console.WriteLine(result.RootElement);
    // For batches, inspect every item even on HTTP 200.
}

.NET 8+ 콘솔 애플리케이션. 콘솔 프로젝트의 Program.cs로 사용한 다음 dotnet run을 실행하세요. 런타임 문서

Go
package main

import (
    "encoding/json"
    "fmt"
    "io"
    "net/http"
    "os"
    "strings"
    "time"
)

func requiredEnv(name string) string {
    value := os.Getenv(name)
    if value == "" { panic("Set " + name) }
    return value
}

func run() error {
    apiKey := requiredEnv("GENDERAPI_API_KEY")
    body := "{\"type\":\"name\",\"value\":\"प्रिया शर्मा\",\"country\":\"IN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", strings.NewReader(body))
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    request.Header.Set("Content-Type", "application/json")
    client := &http.Client{
        Timeout: 30 * time.Second,
        CheckRedirect: func(req *http.Request, via []*http.Request) error {
            return http.ErrUseLastResponse
        },
    }
    response, err := client.Do(request)
    if err != nil { return err }
    defer response.Body.Close()
    raw, err := io.ReadAll(response.Body)
    if err != nil { return err }
    if !strings.Contains(response.Header.Get("Content-Type"), "json") || !json.Valid(raw) {
        return fmt.Errorf("HTTP %d: expected a JSON response", response.StatusCode)
    }
    if response.StatusCode < 200 || response.StatusCode >= 300 {
        return fmt.Errorf("HTTP %d: %s", response.StatusCode, raw)
    }
    fmt.Println(string(raw))
    // For batches, inspect every item even on HTTP 200.
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err) // Keep Problem Details for error handling.
        os.Exit(1)
    }
}

Go 1.22+, 표준 라이브러리. main.go로 저장하고 go run main.go를 실행하세요. 런타임 문서

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

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

필드사용 방법
data.gender / data.result_statusmale 또는 female은 identified일 때만 사용하세요. 결과가 알 수 없음이면 원래의 JSON null을 그대로 유지하세요.
data.name / data.match반환된 이름과 선택된 후보를 확인하세요. 부분 문자열이 일치했다고 해서 입력값이 그 이름을 가진 사람의 것이라는 증거가 되지는 않습니다.
data.confidence / data.confidence_kind신뢰도는 0~1 척도의 값 또는 null입니다. observed_frequency는 저장된 건수에서 나오고, model_reported는 AI 점수입니다. 임계값은 종류별로 따로 평가하세요.
data.source / data.sample_countdataset, ai, none을 구분하세요. AI 결과에는 저장된 표본 수가 없습니다. 표본 수는 측정된 정확도가 아닙니다.
meta.access.mode계정 연동에서는 api_key인지 확인하세요. 키가 없거나 인식되지 않으면 대신 공유 IP 체험이 사용될 수 있습니다.
meta.usagecharged_credits와 billing_status를 확인하세요. 성공한 알 수 없는 결과도 과금됩니다. 응답을 받지 못했다고 해서 요청이 무료였다는 뜻은 아닙니다.

AI를 사용할 시점 선택하기

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

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

요청 옵션동작성공한 조회의 크레딧
options.ai_mode: off데이터셋만 사용합니다.1(알 수 없는 결과 포함)
options.ai_mode: fallback먼저 데이터셋을 조회하고, 성별이 반환되지 않으면 일반 AI를 사용합니다. 단일 요청의 기본값입니다.총 1(AI 폴백 포함)
options.ai_mode: alwaysAI에 직접 요청합니다.2
forceToGenderize: true먼저 데이터셋을 조회한 다음, 실제 이름이 없어도 AI가 개인의 별명이나 별칭을 해석할 수 있게 합니다.데이터셋에서 결과를 얻으면 1, AI를 사용하면 총 2

컨텍스트를 잃지 않고 이름 목록 처리하기

POST /api/v2/gender/batch는 등록된 API 키로 최대 50개 항목, IP 체험에서 최대 10개 항목까지 사용할 수 있습니다. 항목마다 고유한 ID를 지정하고 각 행의 원래 값을 보관하세요. 항목마다 국가와 AI 정책을 따로 지정할 수 있으며, 국가를 알 수 없으면 country를 생략하세요.

단일 요청의 기본값이 폴백인 것과 달리, 일괄 요청 항목의 기본값은 데이터셋 전용 모드입니다. AI가 필요한 항목마다 options.ai_mode: fallback을 설정하세요. HTTP 200을 받은 뒤에도 모든 결과를 확인하고, 알 수 없는 결과를 그대로 유지하고, 다시 제출하기 전에 항목 오류와 과금을 검토하세요. 성공한 일반 항목은 각각 1크레딧을 사용합니다. 일괄 HTTP 요청 하나가 추정 1크레딧에 해당하는 것은 아닙니다.

보내는 데이터 이해하기

실시간 데모는 사용자가 직접 제출할 때만 입력한 값을 GenderAPI.io로 보냅니다. AI가 사용되면 제출한 type, value와 국가 컨텍스트가 추정용으로 설정된 서비스에 전송됩니다. 데이터셋만으로 추정하려면 연동에서 forceToGenderize 없이 options.ai_mode: off를 사용하세요.

개인정보 처리방침, 데이터 처리 계약, 하위 처리자 목록에 공개된 처리 조건이 설명되어 있습니다. 결과는 추정된 연관성이므로 본인이 제공한 정보를 우선하세요. 개인에게 중대한 영향을 미치는 결정의 근거로 사용하지 마세요.

자주 묻는 질문

인도 이름 데모는 힌디어 이름만 지원하나요?

데모는 데바나가리 예시 하나를 사용하지만, API는 유니코드 이름 문자열을 받습니다. 이러한 입력 기능이 데이터셋에 모든 이름이 있다거나 인도에서 쓰이는 모든 언어에 대해 정확도가 측정되었다는 뜻은 아닙니다.

라틴 문자 철자로도 원래 문자 체계와 같은 결과가 나오나요?

보장되지 않습니다. 현재 데이터셋 조회는 일반적인 음역 동등성을 제공하지 않습니다. 제출한 각 철자를 반환된 source, match와 신뢰도 정보와 함께 보관하세요.

모든 인도 이름에 대해 정확도가 측정되었나요?

이 페이지에는 그러한 측정 결과가 게시되어 있지 않습니다. 입력을 받는다는 사실, 저장된 건수, 신뢰도 값은 독립적인 정확도 벤치마크가 아닙니다. 이용할 수 있는 근거와 아직 게시되지 않은 측정은 방법론 페이지에서 확인하세요.

알 수 없는 결과에도 크레딧이 사용되나요?

성공한 알 수 없는 결과도 과금됩니다. 일반 데이터셋 모드나 폴백 모드는 총 1크레딧입니다. forceToGenderize를 사용하면 데이터셋에서 결과를 얻을 때 1크레딧, AI를 사용하면 AI의 알 수 없는 결과를 포함해 총 2크레딧입니다. 오류에는 별도의 과금 규칙이 있으므로 meta.usage를 확인하세요.

계속 테스트하기

GenderAPI 키 사용

공유 IP 체험의 24시간 크레딧을 모두 사용한 뒤에도 테스트하려면 GenderAPI 계정의 API 키를 입력하세요. 키를 저장해도 요청은 전송되지 않으므로 준비되면 다시 제출하세요.

현재 브라우저 탭에만 저장되며 탭을 닫으면 삭제됩니다.