# GenderAPI.io V2 공식 SDK

> Python, JavaScript, PHP, Ruby, Java, R, C#용 GenderAPI.io V2 공식 SDK를 설치하세요. 패키지, 요구 사항과 공통 요청 동작을 비교합니다.

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

Last reviewed: 2026-09-29

## 패키지 선택

공식 오픈 소스 SDK는 이 가이드에서 설명하는 것과 같은 V2 API를 호출합니다. 각 패키지의 2.x 버전은 API V2를 사용합니다. 새 프로젝트에는 2.x 버전을 설치하세요.

| 언어 | 패키지 | 설치 | 요구 사항 |
| --- | --- | --- | --- |
| Python | `genderapi (PyPI)` | `pip install "genderapi>=2,<3"` | Python 3.9+ |
| JavaScript / TypeScript | `genderapi (npm)` | `npm install genderapi@2` | Node.js 18+ |
| PHP | `genderapi/genderapi (Packagist)` | `composer require "genderapi/genderapi:^2.0"` | PHP 8.1+ |
| Ruby | `genderapi (RubyGems)` | `gem install genderapi -v "~> 2.0"` | Ruby 3.0+ |
| Java | `com.github.GenderAPI:genderapi-java (JitPack)` | `implementation 'com.github.GenderAPI:genderapi-java:v2.0.0'` | Java 11+ |
| R | `genderapi (GitHub)` | `remotes::install_github("GenderAPI/genderapi-R", ref = "v2.0.0")` | R 4.1+ |
| C# / .NET | `GenderAPI (NuGet)` | `dotnet add package GenderAPI` | .NET 8 또는 .NET Standard 2.0 |

## 레지스트리 참고 사항

- Java: 저장소 목록에 https://jitpack.io를 추가하세요. 같은 릴리스가 GitHub Packages에도 io.genderapi:genderapi로 게시되어 있으며, 이를 사용하려면 read:packages 권한이 있는 GitHub 토큰이 필요합니다.
- R: 버전 2.0.0이 CRAN 검토를 받는 동안 CRAN에서는 여전히 1.x 패키지를 제공합니다. CRAN에 게시되기 전까지는 GitHub 태그에서 2.0.0을 설치하세요.
- JavaScript: 이 패키지는 서버 측 런타임용입니다. API 키가 노출되므로 브라우저 코드에서는 사용하지 마세요.

## 공통 동작

- 각 클라이언트는 GENDERAPI_API_KEY에서 API 키를 읽거나 생성자로 키를 전달받습니다. 키는 서버에 보관하세요.
- API 키가 없으면 요청에 공유 IP 체험이 사용되며, IP 주소당 24시간마다 10크레딧이 제공됩니다.
- 패키지를 가져오거나 클라이언트를 생성해도 요청은 전송되지 않습니다. 메서드를 한 번 호출할 때마다 정확히 한 번의 요청이 전송됩니다.
- 어떤 SDK도 요청을 자동으로 재시도하지 않습니다. 재시도는 정상적으로 과금되는 새 작업이므로 먼저 오류와 과금 상태를 확인하세요.
- SDK는 리디렉션을 따르지 않으며 기본 타임아웃은 10초입니다.
- 알 수 없는 결과도 성공한 응답입니다. gender는 null이며 요청은 정상적으로 과금됩니다.
- 오류에는 HTTP 상태, 오류 코드, 요청 ID와 함께, 있는 경우 Retry-After 값이 포함됩니다.

- [인증과 IP 체험 접근](https://www.genderapi.io/ko/docs/v2/authentication)
- [크레딧과 사용량](https://www.genderapi.io/ko/docs/v2/credits-and-usage)
- [오류와 재시도](https://www.genderapi.io/ko/docs/v2/errors-and-retries)

## 빠른 시작 예시

각 예시는 이름 추정 요청 한 건을 보내며 1크레딧이 차감됩니다. 먼저 서버 환경에 GENDERAPI_API_KEY를 설정하세요. 일괄 요청, 사용량 확인과 오류 처리는 각 저장소의 README에서 다룹니다.

**Python**

```python
from genderapi import GenderAPI

client = GenderAPI()  # reads GENDERAPI_API_KEY
result = client.name("Alice", country="US")
print(result.data.gender, result.data.result_status)
print(result.meta.usage.charged_credits)
```

**JavaScript / TypeScript**

```javascript
import { GenderAPI } from "genderapi";

const client = new GenderAPI(); // reads GENDERAPI_API_KEY
const { data, meta } = await client.name("Andrea", { country: "IT" });
console.log(data.gender, data.result_status, meta.usage.charged_credits);
```

**PHP**

```php
<?php
require __DIR__ . '/vendor/autoload.php';

use GenderApi\Client;

$client = new Client(); // reads GENDERAPI_API_KEY
$result = $client->name('Jihoon', country: 'KR');
echo $result->data->gender ?? 'unknown', ' ', $result->meta->usage->chargedCredits, "\n";
```

**Ruby**

```ruby
require "genderapi"

client = GenderAPI::Client.new # reads ENV["GENDERAPI_API_KEY"]
result = client.name("Andrea", country: "IT")
puts result.data.gender, result.usage.charged_credits
```

**Java**

```java
import io.genderapi.GenderApiClient;
import io.genderapi.model.GenderResponse;

GenderApiClient client = new GenderApiClient(); // reads GENDERAPI_API_KEY
GenderResponse response = client.name("Andrea", "IT");
System.out.println(response.getData().getGender());
System.out.println(response.getMeta().getUsage().getChargedCredits());
```

**R**

```r
library(genderapi)

res <- genderapi_name("Minseo", country = "KR")  # reads GENDERAPI_API_KEY
res$data$gender
res$meta$usage$charged_credits
```

**C# / .NET**

```csharp
using GenderApi;

using var client = new GenderApiClient(); // reads GENDERAPI_API_KEY
GenderResponse res = await client.NameAsync("Alice", country: "US");
Console.WriteLine(res.Data!.Gender ?? "unknown");
Console.WriteLine(res.Meta!.Usage!.ChargedCredits);
```

## V1 연동은 1.x로 유지

버전 1.x 패키지는 기존 V1 연동을 위해 계속 제공되며 지원 중단(deprecated) 상태가 아닙니다. 업데이트 시 2.x가 설치되지 않도록 메이저 버전을 고정한 다음, 준비가 되면 연동별로 마이그레이션하세요.

| 언어 | 1.x 설치 |
| --- | --- |
| Python | `pip install "genderapi<2"` |
| JavaScript / TypeScript | `npm install genderapi@1` |
| PHP | `composer require "genderapi/genderapi:^1.0"` |
| Ruby | `gem install genderapi -v "~> 1.0"` |
| Java | `implementation 'com.github.GenderAPI:genderapi-java:v1.0.3'` |
| R | `remotes::install_version("genderapi", "1.0.3")` |

- [V1에서 V2로 이전](https://www.genderapi.io/ko/docs/v2/migration)
- [버전 1.x 클라이언트 라이브러리](https://www.genderapi.io/ko/docs-client-libraries)

## 소스 코드와 이슈

모든 SDK는 오픈 소스입니다. 버그 신고나 기능 요청은 해당 GitHub 저장소에 남겨 주세요.

- [GitHub의 Python SDK](https://github.com/GenderAPI/genderapi-python)
- [GitHub의 JavaScript SDK](https://github.com/GenderAPI/genderapi-js)
- [GitHub의 PHP SDK](https://github.com/GenderAPI/genderapi-php)
- [GitHub의 Ruby SDK](https://github.com/GenderAPI/genderapi-ruby)
- [GitHub의 Java SDK](https://github.com/GenderAPI/genderapi-java)
- [GitHub의 R SDK](https://github.com/GenderAPI/genderapi-R)
- [GitHub의 C# SDK](https://github.com/GenderAPI/genderapi-C)