# API v2 인증 및 무료 체험판

> 기존 API 키를 사용하여 GenderAPI v2를 인증하세요. Bearer 헤더, GET 쿼리 키, IP 평가판 액세스 및 JSON 요청에 대해 알아보세요.

Canonical HTML: https://www.genderapi.io/ko/docs/v2/authentication

Last reviewed: 2026-09-25

## 인증 및 무료 체험

서버에서 Authorization: Bearer YOUR_API_KEY를 보냅니다. YOUR_API_KEY를 기존 GenderAPI 키로 교체하세요. 두 버전 모두 잔액을 공유합니다. 별도의 v2 구독이나 키가 필요하지 않습니다.

모든 POST 요청에는 Content-Type: application/json가 필요합니다. 기존 Bearer API 키를 사용하세요. 각 요청은 독립적으로 처리됩니다. 반복 요청에는 일반 청구가 사용됩니다.

GET /gender만이 주요 쿼리 매개변수도 허용합니다. URL이 브라우저 기록 및 로그에 저장될 수 있으므로 통합을 위해 Authorization 헤더를 선호합니다. 프런트엔드 코드에 개인 키를 넣지 마세요.

API 키가 누락되었거나 형식이 잘못되었거나 인식되지 않는 경우 요청은 v1과 공유된 IP 평가판을 사용합니다. 이는 비활성화되거나 만료되거나 제한된 인식된 키에는 적용되지 않습니다. meta.access.mode: api_key, ip_trial 또는 unauthenticated에서 액세스 모드를 확인합니다. 평가판 이유는 api_key_missing, api_key_invalid 또는 api_key_not_found입니다. 따라서 유효하지 않은 키라도 성공적인 시험 응답을 받을 수 있습니다. 프로덕션에서 액세스 모드를 확인하세요.

평가판 크레딧은 24시간 후에 재설정되며 반드시 자정에 재설정되는 것은 아닙니다. /usage를 사용하여 resets_at를 읽습니다. 동일한 공개 IP 뒤에 있는 사람들은 이 수당을 공유합니다.

- [GenderAPI 계정에 로그인하세요](https://app.genderapi.io/user/login)
- [계정 만들기](https://app.genderapi.io/user/register)

## API 키 설정

GenderAPI 계정에서 API 키를 복사하세요. 아래의 YOUR_API_KEY를 해당 키로 바꾼 다음 동일한 터미널 세션에서 선택한 예제를 실행하세요. 이 명령은 해당 세션에 대해서만 환경 변수를 설정합니다. 게시된 자리 표시자는 작동하는 키가 아닙니다.

애플리케이션 또는 배포의 경우 GENDERAPI_API_KEY를 서버 측 비밀로 구성합니다. 예제에서는 .env 파일을 자동으로 로드하지 않습니다. 브라우저 번들, 소스 제어 및 공개 URL에 키를 보관하지 마세요.

**macOS/리눅스 터미널**

```bash
export GENDERAPI_API_KEY='YOUR_API_KEY'
```

**Windows PowerShell**

```powershell
$env:GENDERAPI_API_KEY = 'YOUR_API_KEY'
```

## 크레딧을 사용하지 않고 액세스 권한을 확인하세요

Bearer 헤더를 사용하여 GET /usage를 호출합니다. 유효한 계정 키는 meta.access.mode: api_key를 생성합니다. 결과에 ip_trial가 표시되면 예측을 실행하기 전에 복사된 키를 확인하세요. 이 요청은 잔여 크레딧이 없는 계정을 포함하여 무료입니다.

서버에서 다음 예제를 실행하세요. 프로세스 환경에서 GENDERAPI_API_KEY를 기존 API 키로 설정합니다. meta.access.mode가 api_key인지 확인하세요. 인식되지 않은 키는 IP 평가판으로 대체될 수 있습니다.

이 잔액 읽기에는 크레딧이 필요하지 않습니다. 요청 비율 제한에는 여전히 포함됩니다.

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 GET 'https://api.genderapi.io/api/v2/usage' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}"
```

**JavaScript / Node.js**

Node.js 22+; 내장된 가져오기. 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 response = await fetch("https://api.genderapi.io/api/v2/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
  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")

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/usage",
    method="GET",
    headers={
        "Authorization": "Bearer " + api_key,
    },
)
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');
}

$ch = curl_init('https://api.genderapi.io/api/v2/usage');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$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");
        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/usage"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .GET()
            .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.Get, "https://api.genderapi.io/api/v2/usage");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

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")
    request, err := http.NewRequest("GET", "https://api.genderapi.io/api/v2/usage", nil)
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    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/credits-and-usage)
- [안전하게 요청 재시도](https://www.genderapi.io/ko/docs/v2/errors-and-retries#retries)