# API v2认证和免费试用

> 使用现有的 API 密钥对 GenderAPI v2 进行身份验证。了解 Bearer 标头、GET 查询密钥、IP 试用访问和 JSON 请求。

Canonical HTML: https://www.genderapi.io/zh/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 可以存储在浏览器历史记录和日志中。不要将私钥放在前端代码中。

如果 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 / Linux 终端**

```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 响应保留错误主体并返回非零退出状态。重试前请检查 code、action 和 meta.usage.billing_status。

**cURL**

cURL 7.76+ 在 POSIX shell 中. 在终端中运行。

```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/zh/docs/v2/gender-from-name)
- [读取您的信用余额](https://www.genderapi.io/zh/docs/v2/credits-and-usage)
- [安全地重试请求](https://www.genderapi.io/zh/docs/v2/errors-and-retries#retries)