# Xác định giới tính từ tên tiếng Ả Rập

> Thử tên viết bằng chữ Ả Rập với GenderAPI.io V2. Tìm hiểu về dấu phụ, so khớp họ tên đầy đủ, ngữ cảnh quốc gia, AI dự phòng và kết quả không xác định trước khi tích hợp.

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

Last reviewed: 2026-09-29

## Giữ nguyên cách viết tiếng Ả Rập và kiểm tra tên đã khớp

Hãy gửi tên theo cách viết Unicode gốc. Ô nhập của công cụ dùng chữ Ả Rập viết từ phải sang trái, còn phần hướng dẫn tiếng Việt và JSON vẫn hiển thị từ trái sang phải. API có thể nhận văn bản này mà không cần chuyển tự ở phía máy khách; việc chấp nhận đầu vào không phải là cam kết về độ bao phủ của tập dữ liệu.

Khi tra cứu tập dữ liệu, API áp dụng chuẩn hóa Unicode NFKC và tách token. API không có quy tắc chung để loại bỏ dấu phụ tiếng Ả Rập hay coi các cách viết khác nhau là tương đương. Vì vậy, dấu nguyên âm và những khác biệt chính tả khác có thể ảnh hưởng đến khóa tra cứu đã lưu được tìm thấy. Hãy giữ nguyên giá trị gốc thay vì ngầm coi mọi biến thể là cùng một người.

Một họ tên đầy đủ có thể tạo ra nhiều token ứng viên. Bản ghi hiện có với tổng số lượng đã lưu lớn nhất sẽ được chọn, nên từ đầu tiên chưa chắc là tên riêng được trả về. Hãy kiểm tra data.name và data.match.name trước khi dùng kết quả để bổ sung dữ liệu cho một bản ghi.

| Ví dụ đầu vào | Ý nghĩa | Cần kiểm tra |
| --- | --- | --- |
| `ليلى الخطيب` | Ví dụ họ tên đầy đủ | Nhiều token có thể được xét. Hãy kiểm tra kết quả khớp được chọn; ví dụ này không khẳng định một kết quả trực tiếp nào. |
| `ليلى / لَيْلَى` | Cách viết không có và có dấu nguyên âm | Hãy gửi đúng cách viết thực tế. Không có gì bảo đảm hai chuỗi này dẫn đến cùng một bản ghi đã lưu. |
| `Layla / Leila` | Cách viết bằng chữ Latin | Đây là các giá trị đầu vào riêng biệt. V2 không cam kết tự động coi các cách chuyển tự là tương đương. |
| `country: SA` | Ngữ cảnh demo: Ả Rập Xê Út | Ngữ cảnh này không phải giá trị mặc định cho mọi cộng đồng nói tiếng Ả Rập. Hãy bỏ qua country khi chưa biết quốc gia. |

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

Bản demo trực tiếp gửi country: SA (Ả Rập Xê Út). 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 Ả Rập 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": "SA",
  "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": "SA",
  "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\":\"SA\",\"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":"SA","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\":\"SA\",\"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\":\"SA\",\"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\":\"SA\",\"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)

## V2 có chấp nhận tên tiếng Ả Rập có dấu phụ không?

V2 chấp nhận tên ở dạng Unicode, bao gồm văn bản tiếng Ả Rập. Việc chuẩn hóa tập dữ liệu nhìn chung không loại bỏ dấu nguyên âm tiếng Ả Rập, vì vậy cách viết có dấu và không dấu có thể cho kết quả khớp khác nhau hoặc kết quả không xác định.

## Công cụ này có xác định quốc tịch của người nói tiếng Ả Rập không?

Không. SA là ngữ cảnh quốc gia được chỉ định rõ cho bản demo này. Hệ chữ viết, mối liên hệ của tên và trường quốc gia được trả về không chứng minh quốc tịch hay nơi cư trú.

## Độ chính xác có được đo cho mọi tên tiếng Ả Rập 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.