# 根据用户名或昵称判断性别

> 使用 GenderAPI.io V2 解读用户名。试用普通的姓名匹配或可选的昵称解读，了解 1 或 2 个积分的费用，并保留未知结果。

Canonical HTML: https://www.genderapi.io/zh/determine-gender-from-username

Last reviewed: 2026-09-29

## 姓名信号与昵称含义是两回事

对用户名或昵称请使用 type: username。进行数据集匹配时，开头可选的 @ 会被去掉。候选项提取会考虑分隔符和数字，并可能检查有限的子字符串。昵称模式保留按完整部分进行的匹配，但不会添加这些基于子字符串的候选项。系统选中的存储记录是可用候选项中总计数最大的那一条；这并不能说明账号背后那个人的真实姓名。

普通的 AI 回退会寻找可识别的名字。forceToGenderize 还允许在无法提取真实名字时，根据个人昵称建立关联。两种方式都可能返回 unknown；品牌、虚构角色或共享账号不一定代表某一个人。

| 输入示例 | 处理方式 | 需要检查的内容 |
| --- | --- | --- |
| `@alice.smith` | 从先查询数据集的普通回退开始。 | 检查所选的名字和匹配方式；不要假定被选中的是第一部分。 |
| `robert89` | 提取候选项时，数字可能会被去掉。 | 匹配到的名字只是一种关联，而不是经过确认的身份。 |
| `prenses` | 启用 forceToGenderize，以便在没有结果时允许 AI 根据昵称进行尝试。 | gender 可能不为 null，而 name 为 null。AI 给出的值属于 model_reported。 |
| `team_support` | 职能账号和共享账号可能不属于某一个人，请据此处理。 | 保留 unknown，不要为共享账号指定个人身份。 |

## 在您的集成中测试昵称解读

此请求启用了昵称解读。系统会先查询数据集；如果没有返回性别，AI 可以利用别名的含义。进行普通查询时请省略 forceToGenderize；单个请求默认仍会使用普通的 AI 回退。

此示例提供了国家/地区背景 TR。请使用您应用中相关的背景，并检查 data.match.scope；提供了国家/地区并不保证会得到该国家/地区特定的记录。它也不代表国籍或居住地。

请在您的服务器上运行这些示例。在进程环境中将 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 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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
}'
```

**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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
};

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}")

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":"username","value":"prenses","country":"TR","forceToGenderize":true}', 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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}";
        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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}", 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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}"
    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)
    }
}
```

- [用户名的完整 V2 参考](https://www.genderapi.io/zh/docs/v2/gender-from-username)

## 将结果与其依据一起保存

推断出的关联并不是本人自述的性别。请把原始输入、返回的依据以及本人提供的信息分开保存。未知结果是有效的结果，不应在您的应用中变成一个猜测出来的类别。

| 字段 | 使用方式 |
| --- | --- |
| `data.gender / data.result_status` | 只有在 identified 时才使用 male 或 female。结果未知时，请保留 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/zh/docs/v2/responses)
- [准确性与置信度说明](https://www.genderapi.io/zh/accuracy-methodology)
- [数据来源与注明日期的数据库概况](https://www.genderapi.io/zh/data-provenance)

## 决定何时使用 AI

forceToGenderize 对姓名、电子邮箱地址和用户名都是可选的。启用时，请省略 ai_mode 或使用 fallback；off 和 always 不能与此选项组合，否则会返回 422。起始余额为正即可发起请求，即使最终扣费后余额变为负数。

昵称模式可能在 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/zh/docs/v2/ai-options)
- [积分与用量](https://www.genderapi.io/zh/docs/v2/credits-and-usage)

## 处理列表时保留每个用户名的结果

对用户名列表，或由姓名、电子邮箱地址和用户名混合组成的列表，请使用 POST /api/v2/gender/batch。使用 API 密钥时上限为 50 个条目，使用 IP 试用时为 10 个。每个条目都有各自的国家/地区和 AI 选项，可选的 ID 在同一批量请求中必须唯一。

默认情况下，批量请求只使用数据集。如需使用普通 AI，请为条目分别启用 fallback；如需解读昵称，请为条目分别设置 forceToGenderize。请检查每个结果中的 data 或 error，并使用 id 或 index 将结果对应到原始行。成功完成的未知条目同样计费。

- [构建批量请求并处理部分失败](https://www.genderapi.io/zh/docs/v2/batch)
- [错误、丢失的响应与重试](https://www.genderapi.io/zh/docs/v2/errors-and-retries)

## 了解您发送了什么

实时演示只会在您提交时，才把输入的值发送给 GenderAPI.io。如果调用了 AI，提交的 type、value 和国家/地区背景会被发送给已配置的推断服务。如需仅基于数据集的预测，请在您的集成中使用 options.ai_mode: off，且不要使用 forceToGenderize。

隐私政策、数据处理协议和次级处理方名单说明了已公布的处理条款。结果只是推断出的关联，本人的自述优先。请不要把它作为对个人有重大影响的决策依据。

- [隐私政策](https://www.genderapi.io/zh/privacy-policy)
- [数据处理协议](https://www.genderapi.io/zh/data-processing-agreement)
- [次级处理方](https://www.genderapi.io/zh/subprocessors)

## 用户名必须包含真实的名字吗？

普通的 AI 预测需要可用的名字。使用 forceToGenderize 时，如果数据集查询没有结果，API 还可以尝试根据昵称建立关联。此模式不需要真实名字，并且可能返回 name: null。

## forceToGenderize 能保证返回性别吗？

不能。它允许昵称解读，但最终结果仍可能是未知。请保留 JSON 原生的 null 值，并检查 result_status 和 reason。

## API 会查看社交媒体上的个人资料吗？

此端点只解读提交的值。它不会获取该账号的个人资料、帖子或照片来判断持有人是谁。

## 姓名或电子邮箱地址也可以使用 forceToGenderize 吗？

可以。它对 name、email 和 username 类型的输入都是可选的。系统会先使用数据集，没有结果时再使用带昵称解读的 AI：数据集得出结果时消耗 1 个积分，使用 AI 时总共消耗 2 个积分。