# GenderAPI.io V2 官方 SDK

> 安装适用于 Python、JavaScript、PHP、Ruby、Java、R 和 C# 的 GenderAPI.io V2 官方 SDK。比较各软件包、运行要求以及通用的请求行为。

Canonical HTML: https://www.genderapi.io/zh/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 添加到您的仓库列表中。同一版本也以 io.genderapi:genderapi 发布到 GitHub Packages，使用时需要具有 read:packages 权限的 GitHub 令牌。
- R：在 2.0.0 版本接受 CRAN 审核期间，CRAN 上提供的仍是 1.x 软件包。在 CRAN 发布 2.0.0 之前，请从 GitHub 标签安装该版本。
- 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/zh/docs/v2/authentication)
- [积分与用量](https://www.genderapi.io/zh/docs/v2/credits-and-usage)
- [错误与重试](https://www.genderapi.io/zh/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('Wei', country: 'CN');
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("Ming", country = "CN")  # 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 集成使用，且未被弃用。请固定主版本号，以免更新时安装 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 迁移](https://www.genderapi.io/zh/docs/v2/migration)
- [1.x 版本客户端库](https://www.genderapi.io/zh/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)