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

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

Canonical HTML: https://www.genderapi.io/ko/determine-gender-from-indian-names

Last reviewed: 2026-09-29

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

이 데모는 데바나가리 예시와 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는 반환된 연관성을 나타냅니다. 둘은 서로 다른 필드이며 시민권, 민족, 거주지를 나타내지 않습니다.

- [국가 컨텍스트와 일치 방식 참고 문서](https://www.genderapi.io/ko/docs/v2/gender-from-name#country-evidence-workflow)

## V2로 인도 이름 보내기

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

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

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

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

**cURL**

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

```bash
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"
  }
}'
```

**JavaScript / Node.js**

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

```javascript
// 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.
}
```

**Python**

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

```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.
```

**PHP**

PHP 8+, cURL 확장. example.php로 저장하고 php example.php를 실행하세요.

```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.
```

**Java**

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

```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.
    }
}
```

**C# / .NET**

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

```csharp
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.
}
```

**Go**

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

```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)
    }
}
```

- [이름 요청 매개변수](https://www.genderapi.io/ko/docs/v2/gender-from-name)
- [인증 설정하기](https://www.genderapi.io/ko/docs/v2/authentication)

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

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

| 필드 | 사용 방법 |
| --- | --- |
| `data.gender / data.result_status` | male 또는 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_count` | dataset, ai, none을 구분하세요. AI 결과에는 저장된 표본 수가 없습니다. 표본 수는 측정된 정확도가 아닙니다. |
| `meta.access.mode` | 계정 연동에서는 api_key인지 확인하세요. 키가 없거나 인식되지 않으면 대신 공유 IP 체험이 사용될 수 있습니다. |
| `meta.usage` | charged_credits와 billing_status를 확인하세요. 성공한 알 수 없는 결과도 과금됩니다. 응답을 받지 못했다고 해서 요청이 무료였다는 뜻은 아닙니다. |

- [응답 필드와 알 수 없는 결과](https://www.genderapi.io/ko/docs/v2/responses)
- [정확도와 신뢰도 설명](https://www.genderapi.io/ko/accuracy-methodology)
- [데이터 출처와 날짜가 명시된 데이터셋 개요](https://www.genderapi.io/ko/data-provenance)

## 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: always | AI에 직접 요청합니다. | 2 |
| forceToGenderize: true | 먼저 데이터셋을 조회한 다음, 실제 이름이 없어도 AI가 개인의 별명이나 별칭을 해석할 수 있게 합니다. | 데이터셋에서 결과를 얻으면 1, AI를 사용하면 총 2 |

- [AI 옵션과 별명 추정](https://www.genderapi.io/ko/docs/v2/ai-options)
- [크레딧과 사용량](https://www.genderapi.io/ko/docs/v2/credits-and-usage)

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

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

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

- [일괄 요청 예시와 부분 실패](https://www.genderapi.io/ko/docs/v2/batch#batch-application-workflow)
- [애플리케이션에서 알 수 없는 결과 처리하기](https://www.genderapi.io/ko/docs/v2/responses#application-decisions)

## 보내는 데이터 이해하기

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

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

- [개인정보 처리방침](https://www.genderapi.io/ko/privacy-policy)
- [데이터 처리 계약](https://www.genderapi.io/ko/data-processing-agreement)
- [하위 처리자](https://www.genderapi.io/ko/subprocessors)

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

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

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

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

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

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

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

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