# 根据中文姓名判断性别

> 使用 GenderAPI.io V2 测试中文姓名。了解较短的部分、完整姓名的拆分、原始汉字以及 CN 国家/地区背景如何影响数据集和 AI 的结果。

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

Last reviewed: 2026-09-29

## 区分 Unicode 输入与完整姓名的拆分

您可以把中文姓名作为 Unicode 文本发送，无需事先转写为拉丁字母。当前的查询只检查规范化后的各个部分；没有空格的中文完整姓名不会被自动拆分为姓和名。因此，“王静怡”是一个单独的候选项，并不能保证系统会查询“静怡”。

对于这些示例中的常用汉字，当前的数据集候选项过滤器会跳过只有一个或两个字符的部分。较短的名字可能是有效输入，却不会产生任何候选项。普通的自动 AI 回退仍可能解读最初提交的值；仅使用数据集的请求则会保留未知结果。

Unicode NFKC 规范化不会在简体中文和繁体中文之间进行通用转换，也不会把拉丁字母拼写还原为唯一的中文原名。请保留提交时的写法，并检查返回的匹配。仅凭姓氏的位置、文字或罗马化拼写，不能推断一个人的性别或国家/地区。

| 输入示例 | 说明 | 需要检查的内容 |
| --- | --- | --- |
| `王静怡` | 没有空格的完整姓名 | 在数据集中只是一个候选项。当前的解析不会分离出姓氏。 |
| `静怡` | 两个字的名字 | 因候选项过滤器的长度限制而被跳过；AI 回退可能会解读原始值。 |
| `王 静怡` | 用空格分开的较短部分 | 加一个空格并不能绕过长度限制。示例中的两个部分都太短，无法用于数据集查询。 |
| `Wang Jingyi` | 拉丁字母输入 | 会被当作单独的值，并拆分为它自己的各个部分。无法保证它会还原为原始汉字或对应到同一条记录。 |

## 审慎选择国家/地区背景 CN

实时演示会发送 country: CN（中国）。API 不会根据姓名所用的文字来选择这个国家/地区。请在您的集成中使用已知且相关的国家/地区背景，或者省略 country。不要把这个示例值变成所有记录的默认值。

对于每个候选项，查询会在存在国家/地区专属记录时选择该记录，否则选择全局记录。然后，系统会选择存储总计数最大的可用候选项。实际的匹配范围见 data.match.scope 和 data.match.country。频次相同的国家/地区专属记录不会被自动替换为全局结果；如果启用了回退，则可能改用 AI。

data.input.country 表示请求中发送的国家/地区背景。data.country 和 data.country_source 表示返回的国家/地区关联及其来源。这些字段各不相同，都不能说明国籍、族裔或居住地。

- [国家/地区背景与匹配](https://www.genderapi.io/zh/docs/v2/gender-from-name#country-evidence-workflow)

## 用您应用中的姓名发送 V2 请求

请把您现有的 API 密钥设置到 GENDERAPI_API_KEY 中，然后在您的服务器上运行示例。该请求显式启用了普通的自动 AI 回退。它展示的是请求如何构建，而不是实测的准确率或已确认的覆盖范围。如果您需要仅基于数据集的预测，请设置 options.ai_mode: off。

请在您的服务器上运行这些示例。在进程环境中将 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": "name",
  "value": "王静怡",
  "country": "CN",
  "options": {
    "ai_mode": "fallback"
  }
}'
```

**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": "name",
  "value": "王静怡",
  "country": "CN",
  "options": {
    "ai_mode": "fallback"
  }
};

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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}")

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":"name","value":"王静怡","country":"CN","options":{"ai_mode":"fallback"}}', 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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}", 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\":\"name\",\"value\":\"王静怡\",\"country\":\"CN\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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)
    }
}
```

- [姓名请求的参数](https://www.genderapi.io/zh/docs/v2/gender-from-name)
- [如何提供 API 密钥](https://www.genderapi.io/zh/docs/v2/authentication)

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

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

| 字段 | 使用方式 |
| --- | --- |
| `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 个。请为每个条目设置唯一的 id，并保留每一行的原始值。每个条目都可以有自己的国家/地区和 AI 选项；不了解国家/地区时请省略它。

单个请求默认使用回退，而批量请求中的条目默认只使用数据集。需要 AI 的条目，请分别设置 options.ai_mode: fallback。即使返回 HTTP 200，也请逐条检查结果，保存未知结果，并在重新发送之前检查错误和计费。每个成功的普通条目消耗 1 个积分；一个包含批量条目的 HTTP 请求并不等于每次预测只消耗一个积分。

- [批量请求示例与部分失败](https://www.genderapi.io/zh/docs/v2/batch#batch-application-workflow)
- [在您的应用中处理未知结果](https://www.genderapi.io/zh/docs/v2/responses#application-decisions)

## 了解您发送了什么

实时演示只会在您提交时，才把输入的值发送给 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)

## 为什么仅使用数据集时，两个字的中文名字可能仍是未知结果？

当前的候选项过滤器会跳过 JavaScript 字符串长度不超过 2 的部分。对于这里显示的汉字，两个字的名字是有效输入，但不会成为数据集中的候选项。AI 回退可能会解读原始值。

## V2 会自动把中文姓氏和名字分开吗？

数据集查询不会拆分没有空格的中文完整姓名。AI 可能会从完整的值中推断出一个名字，但两种方式都不能保证选中想要的名字。请检查响应中的 source 和 match。

## 是否已发布针对这类姓名的独立准确率评估？

本页没有发布此类评估。输入被接受、显示了存储的频次或返回了置信度，都不是独立的准确率测量。方法说明介绍了现有哪些数据，以及哪些测量尚未发布。

## 没有预测结果时会消耗积分吗？

成功完成的未知结果同样计费。普通模式（仅使用数据集或使用回退）总共消耗 1 个积分。使用 forceToGenderize 时，结果来自数据集则消耗 1 个积分，使用 AI 则总共消耗 2 个积分，未知结果也是如此。错误适用单独的计费规则；请检查 meta.usage。