# Xác định giới tính từ tên tiếng Trung

> Thử tên tiếng Trung với GenderAPI.io V2. Tìm hiểu cách token ngắn, việc tách họ tên đầy đủ, ký tự gốc và ngữ cảnh CN ảnh hưởng đến kết quả từ tập dữ liệu và AI.

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

Last reviewed: 2026-09-29

## Phân biệt đầu vào Unicode với việc tách tên

Bạn có thể gửi tên tiếng Trung dưới dạng văn bản Unicode mà không cần chuyển sang chữ Latin. Khi tra cứu tập dữ liệu, API hiện tìm theo các token đã chuẩn hóa; API không tự động tách một họ tên tiếng Trung viết liền thành họ và tên riêng. Vì vậy, 王静怡 là một ứng viên, không phải một lượt tra cứu chắc chắn cho 静怡.

Với các ký tự tiếng Trung thông dụng trong những ví dụ này, bộ lọc ứng viên hiện tại của tập dữ liệu bỏ qua token có một hoặc hai ký tự. Một tên riêng ngắn có thể là đầu vào hợp lệ nhưng vẫn không có ứng viên trong tập dữ liệu. AI dự phòng thông thường vẫn có thể xét giá trị gốc đã gửi; chế độ chỉ dùng tập dữ liệu sẽ giữ nguyên kết quả không xác định.

Chuẩn hóa Unicode NFKC không chuyển đổi tổng quát từ chữ giản thể sang phồn thể, cũng không quy một cách viết Latin về một tên tiếng Trung duy nhất. Hãy giữ nguyên hệ chữ đã gửi và kiểm tra kết quả khớp được trả về. Đừng suy ra giới tính hay quốc gia của một người chỉ từ vị trí của họ, hệ chữ hoặc cách Latin hóa.

| Ví dụ đầu vào | Ý nghĩa | Cần kiểm tra |
| --- | --- | --- |
| `王静怡` | Họ tên đầy đủ viết liền | Một ứng viên trong tập dữ liệu. Bộ phân tích hiện tại không tách riêng phần họ. |
| `静怡` | Đầu vào tên riêng hai ký tự | Bị bộ lọc độ dài ứng viên của tập dữ liệu bỏ qua; AI dự phòng có thể thử giá trị gốc. |
| `王 静怡` | Các token ngắn được tách rời | Thêm dấu cách không khắc phục được bộ lọc độ dài. Cả hai token trong ví dụ đều quá ngắn để tra cứu trong tập dữ liệu. |
| `Wang Jingyi` | Đầu vào bằng chữ Latin | Được xử lý như một đầu vào riêng và được tách token riêng. Không có gì bảo đảm giá trị này dẫn về các ký tự gốc hoặc cùng một bản ghi. |

## Chọn ngữ cảnh CN một cách có chủ đích

Bản demo trực tiếp gửi country: CN (Trung Quốc). API không chọn quốc gia này dựa trên hệ chữ của tên. Trong tích hợp của bạn, hãy dùng ngữ cảnh đã biết và có liên quan, hoặc bỏ qua country; đừng biến giá trị mẫu này thành mặc định cho mọi bản ghi.

Với mỗi ứng viên, khi tra cứu tập dữ liệu, API ưu tiên bản ghi theo quốc gia nếu có, nếu không sẽ xét bản ghi toàn cầu. Sau đó, API chọn ứng viên hiện có với tổng số lượng đã lưu lớn nhất. Hãy kiểm tra data.match.scope và data.match.country để biết phạm vi khớp thực tế. Một bản ghi theo quốc gia có số lượng bằng nhau sẽ không tự động bị thay bằng kết quả toàn cầu; chế độ fallback có thể dùng AI thay thế.

data.input.country mô tả ngữ cảnh của yêu cầu. data.country và data.country_source mô tả mối liên hệ được trả về. Đây là các trường khác nhau và không chứng minh quốc tịch, dân tộc hay nơi cư trú.

- [Ngữ cảnh quốc gia và tài liệu tham khảo về so khớp](https://www.genderapi.io/vi/docs/v2/gender-from-name#country-evidence-workflow)

## Gửi tên tiếng Trung bằng V2

Hãy chạy yêu cầu trên máy chủ của bạn, với GENDERAPI_API_KEY được đặt bằng khóa API hiện có. Ví dụ này bật rõ ràng AI dự phòng thông thường. Đây là minh họa một yêu cầu, không phải kết quả dự đoán hay độ bao phủ đã đo. Hãy dùng options.ai_mode: off để chỉ xử lý bằng tập dữ liệu.

Chạy các ví dụ này trên máy chủ của bạn. Đặt GENDERAPI_API_KEY trong biến môi trường của tiến trình bằng khóa API hiện có. Xác nhận meta.access.mode là api_key: khóa không được nhận diện có thể chuyển sang dùng thử theo IP.

Mỗi yêu cầu dự đoán là một thao tác mới bị tính phí, kể cả khi thử lại. Các ví dụ này không tự động thử lại. Kiểm tra trạng thái tính phí trước khi gửi yêu cầu khác.

Với phản hồi JSON HTTP 4xx và 5xx, ví dụ giữ nguyên nội dung lỗi và kết thúc với mã thoát khác 0. Kiểm tra code, action và meta.usage.billing_status trước khi thử lại.

**cURL**

cURL 7.76+ trong shell POSIX. Chạy trong terminal.

```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 tích hợp sẵn. Lưu thành example.mjs và chạy 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+; thư viện chuẩn. Lưu thành example.py và chạy 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+ với tiện ích mở rộng cURL. Lưu thành example.php và chạy 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 client chuẩn. Lưu thành GenderApiExample.java và chạy 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**

Ứng dụng console .NET 8+. Dùng làm Program.cs trong một dự án console, sau đó chạy 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+; thư viện chuẩn. Lưu thành main.go và chạy 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)
    }
}
```

- [Tham số yêu cầu cho tên](https://www.genderapi.io/vi/docs/v2/gender-from-name)
- [Thiết lập xác thực](https://www.genderapi.io/vi/docs/v2/authentication)

## Lưu kết quả cùng với bằng chứng của nó

Một mối liên hệ được suy luận không phải là giới tính do chính người đó tự công bố. Hãy lưu riêng đầu vào gốc, bằng chứng được trả về và mọi thông tin do người đó cung cấp. Kết quả không xác định là một kết quả hợp lệ; không nên biến nó thành một nhóm được đoán trong ứng dụng của bạn.

| Trường | Cách sử dụng |
| --- | --- |
| `data.gender / data.result_status` | Chỉ dùng male hoặc female khi kết quả là identified. Giữ nguyên giá trị JSON null gốc khi kết quả không xác định. |
| `data.name / data.match` | Kiểm tra tên được trả về và ứng viên được chọn. Kết quả khớp theo chuỗi con không chứng minh rằng đầu vào thuộc về người có tên riêng đó. |
| `data.confidence / data.confidence_kind` | Độ tin cậy nằm trên thang từ 0 đến 1 hoặc là null. observed_frequency dựa trên số lượng đã lưu; model_reported là điểm do AI đưa ra. Hãy đánh giá ngưỡng riêng cho từng loại. |
| `data.source / data.sample_count` | Phân biệt dataset, ai và none. Kết quả AI không có số lượng mẫu đã lưu. Số lượng mẫu không phải là điểm độ chính xác đã đo. |
| `meta.access.mode` | Xác nhận api_key với tích hợp dùng tài khoản. Khóa bị thiếu hoặc không được nhận diện có thể chuyển sang dùng thử theo IP dùng chung. |
| `meta.usage` | Đọc charged_credits và billing_status. Kết quả không xác định thành công vẫn bị tính phí. Mất phản hồi không chứng minh rằng yêu cầu được miễn phí. |

- [Trường phản hồi và kết quả không xác định](https://www.genderapi.io/vi/docs/v2/responses)
- [Giải thích về độ chính xác và độ tin cậy](https://www.genderapi.io/vi/accuracy-methodology)
- [Nguồn dữ liệu và hồ sơ tập dữ liệu có ghi ngày](https://www.genderapi.io/vi/data-provenance)

## Chọn khi nào dùng AI

forceToGenderize là tùy chọn cho tên, địa chỉ email và tên người dùng. Khi bật trường này, hãy bỏ qua ai_mode hoặc dùng fallback; off và always xung đột với nó và trả về 422. Chỉ cần số dư ban đầu dương là đủ để bắt đầu một yêu cầu, kể cả khi lần tính phí cuối cùng làm số dư xuống dưới 0.

Chế độ biệt danh có thể trả về giới tính cùng name: null. Chế độ này cũng có thể trả về kết quả không xác định. Cả AI dự phòng thông thường lẫn suy luận biệt danh đều không bảo đảm câu trả lời đúng hoặc khác null.

| Tùy chọn yêu cầu | Cách hoạt động | Tín dụng cho một lần tra cứu thành công |
| --- | --- | --- |
| options.ai_mode: off | Chỉ dùng tập dữ liệu. | 1, kể cả kết quả không xác định |
| options.ai_mode: fallback | Tra tập dữ liệu trước, sau đó dùng AI thông thường khi không có giới tính được trả về. Đây là mặc định cho yêu cầu đơn lẻ. | Tổng cộng 1, đã gồm AI dự phòng |
| options.ai_mode: always | Dùng AI trực tiếp. | 2 |
| forceToGenderize: true | Tra tập dữ liệu trước, sau đó cho phép AI diễn giải biệt danh cá nhân hoặc bí danh, kể cả khi không có tên thật. | 1 khi tập dữ liệu cho ra kết quả; tổng cộng 2 nếu dùng AI |

- [Tùy chọn AI và suy luận biệt danh](https://www.genderapi.io/vi/docs/v2/ai-options)
- [Tín dụng và mức sử dụng](https://www.genderapi.io/vi/docs/v2/credits-and-usage)

## Xử lý danh sách tên mà không mất ngữ cảnh

Dùng POST /api/v2/gender/batch cho tối đa 50 mục khi truy cập bằng khóa API đã đăng ký, hoặc 10 mục khi dùng thử theo IP. Hãy gán ID duy nhất cho từng mục và giữ lại giá trị gốc của từng dòng. Mỗi mục có thể có quốc gia và chính sách AI riêng; hãy bỏ qua country khi chưa biết quốc gia.

Khác với mặc định fallback của yêu cầu đơn lẻ, các mục trong yêu cầu hàng loạt mặc định chỉ dùng tập dữ liệu. Hãy đặt options.ai_mode: fallback cho từng mục cần AI. Kiểm tra mọi kết quả, kể cả sau HTTP 200, giữ nguyên kết quả không xác định và xem xét lỗi của từng mục cùng việc tính phí trước khi gửi lại. Mỗi mục thông thường thành công tốn một tín dụng; một yêu cầu HTTP hàng loạt không có nghĩa là chỉ tốn một tín dụng dự đoán.

- [Ví dụ yêu cầu hàng loạt và lỗi một phần](https://www.genderapi.io/vi/docs/v2/batch#batch-application-workflow)
- [Xử lý kết quả không xác định trong ứng dụng](https://www.genderapi.io/vi/docs/v2/responses#application-decisions)

## Hiểu rõ dữ liệu bạn gửi đi

Bản demo trực tiếp chỉ gửi giá trị đã nhập đến GenderAPI.io khi bạn chủ động gửi. Nếu AI được gọi, type, value và ngữ cảnh quốc gia đã gửi sẽ được chuyển đến dịch vụ suy luận đã được cấu hình. Để chỉ dự đoán bằng tập dữ liệu, hãy dùng options.ai_mode: off mà không có forceToGenderize trong tích hợp của bạn.

Chính sách quyền riêng tư, thỏa thuận xử lý dữ liệu và danh sách bên xử lý dữ liệu phụ mô tả các điều kiện xử lý đã công bố. Kết quả là một mối liên hệ được suy luận; hãy ưu tiên thông tin do chính người đó cung cấp. Không dùng kết quả làm cơ sở cho các quyết định có ảnh hưởng quan trọng đến một cá nhân.

- [Chính sách quyền riêng tư](https://www.genderapi.io/vi/privacy-policy)
- [Thỏa thuận xử lý dữ liệu](https://www.genderapi.io/vi/data-processing-agreement)
- [Danh sách bên xử lý dữ liệu phụ](https://www.genderapi.io/vi/subprocessors)

## Vì sao một tên tiếng Trung hai ký tự có thể không xác định ở chế độ chỉ dùng tập dữ liệu?

Bộ lọc ứng viên hiện tại của tập dữ liệu bỏ qua token có độ dài chuỗi JavaScript tối đa là hai. Với các ký tự tiếng Trung trong ví dụ này, tên hai ký tự là đầu vào hợp lệ nhưng không trở thành ứng viên trong tập dữ liệu. AI dự phòng có thể xét đầu vào gốc.

## V2 có tự động tách họ khỏi tên riêng trong tên tiếng Trung không?

Khi tra cứu tập dữ liệu, API không tách một họ tên tiếng Trung viết liền. AI có thể suy ra một tên từ toàn bộ giá trị, nhưng không cách nào bảo đảm đó đúng là tên riêng bạn muốn. Hãy kiểm tra source và kết quả khớp được trả về.

## Độ chính xác có được đo cho mọi tên tiếng Trung không?

Trang này không công bố phép đo như vậy. Việc chấp nhận đầu vào, số lượng đã lưu và giá trị độ tin cậy không phải là một phép đo độ chính xác độc lập. Hãy xem trang phương pháp đánh giá để biết bằng chứng hiện có và những phép đo chưa được công bố.

## Kết quả không xác định có tốn tín dụng không?

Kết quả không xác định thành công vẫn bị tính phí. Chế độ tập dữ liệu hoặc fallback thông thường tốn tổng cộng một tín dụng. Khi bật forceToGenderize, kết quả xác định được từ tập dữ liệu tốn một tín dụng, còn khi dùng AI thì tốn tổng cộng hai tín dụng, kể cả khi AI trả về kết quả không xác định. Lỗi có quy tắc tính phí riêng; hãy kiểm tra meta.usage.