# Giới tính từ một cái tên có API v2

> Dự đoán giới tính từ họ hoặc tên đầy đủ với GenderAPI v2. Xem bảy ví dụ về ngôn ngữ, phản hồi JSON, bối cảnh quốc gia, dự phòng AI và chi phí tín dụng.

Canonical HTML: https://www.genderapi.io/vi/docs/v2/gender-from-name

Last reviewed: 2026-09-25

## Trước khi gửi yêu cầu

Gửi JSON tới POST https://api.genderapi.io/api/v2/gender. Sử dụng khóa API hiện có của bạn trong Authorization: Bearer YOUR_API_KEY và Content-Type: application/json. Mọi yêu cầu đều được xử lý độc lập.

Chọn ngôn ngữ của bạn trong ví dụ mã. Đặt GENDERAPI_API_KEY trong môi trường quy trình trước khi chạy nó. Key bị thiếu hoặc không nhận dạng được có thể sử dụng bản dùng thử IP được chia sẻ, vì vậy hãy xác nhận meta.access.mode là api_key khi tích hợp tài khoản.

- [Xác thực và truy cập dùng thử](https://www.genderapi.io/vi/docs/v2/authentication)
- [Tất cả các tham số yêu cầu](https://www.genderapi.io/vi/docs/v2/request-parameters)

## Giới tính từ cái tên

Sử dụng type: name để gửi họ hoặc tên đầy đủ. Phản hồi thành công có thể chứa gender: null. Các yêu cầu đơn lẻ trước tiên sẽ tìm kiếm tập dữ liệu. Nếu không xác định được giới tính, họ sẽ sử dụng AI theo mặc định.

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

Mỗi yêu cầu dự đoán là một hoạt động mới có thể tính phí, bao gồm cả số lần thử lại. Những ví dụ này không tự động thử lại. Kiểm tra trạng thái thanh toán trước khi gửi yêu cầu khác.

Phản hồi HTTP 4xx và 5xx JSON giữ nguyên phần thân lỗi và trả về trạng thái 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 vỏ POSIX. Chạy trong terminal của bạn.

```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": "Onur",
  "country": "TR"
}'
```

**JavaScript / Node.js**

Node.js 22+; tìm nạp tích hợp. Lưu dưới dạng 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": "Onur",
  "country": "TR"
};

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 dưới dạng 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\":\"Onur\",\"country\":\"TR\"}")

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 phần mở rộng cURL. Lưu dưới dạng 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":"Onur","country":"TR"}', 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+; máy khách HTTP tiêu chuẩn. Lưu dưới dạng 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\":\"Onur\",\"country\":\"TR\"}";
        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 bảng điều khiển .NET 8+. Sử dụng làm Program.cs trong dự án bảng điều khiển, 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\":\"Onur\",\"country\":\"TR\"}", 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 dưới dạng 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\":\"Onur\",\"country\":\"TR\"}"
    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)
    }
}
```

## Ví dụ phản hồi

Phản hồi tổng hợp này minh họa hình dạng JSON, không phải độ chính xác được đo hoặc kết quả trực tiếp được đảm bảo. Nó hiển thị quyền truy cập dùng thử IP; một hoạt động được xác thực báo cáo các trường hạn ngạch chỉ dùng thử meta.access.mode: api_key và null. Đọc dữ liệu để suy luận và meta.usage để biết kết quả thanh toán của hoạt động.

```json
{
  "data": {
    "input": {
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    "name": "onur",
    "gender": "male",
    "country": "TR",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "onur",
      "method": "normalized",
      "scope": "country",
      "country": "TR"
    }
  },
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 9,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}
```

- [Trường phản hồi và độ tin cậy](https://www.genderapi.io/vi/docs/v2/responses)

## Bối cảnh đất nước và những cái tên chưa biết

Chỉ cung cấp quốc gia khi bạn có bối cảnh liên quan. API có thể chọn hàng tập dữ liệu theo quốc gia cụ thể hoặc quay lại hàng toàn cầu. data.match.scope hiển thị đã được chọn; nước trở về không xác định nơi người đó sống.

Theo mặc định, một yêu cầu duy nhất sử dụng AI khi tập dữ liệu không thể xác định giới tính, với tổng số 1 tín dụng. Để chỉ sử dụng tập dữ liệu, hãy gửi options: {"ai_mode": "off"}. Một yêu cầu đã hoàn thành vẫn bị tính phí nếu nó trả về gender: null. Tra cứu tên đầy đủ có thể khớp với một phần của tên. data.match ghi lại ứng cử viên đã chọn và phương pháp so khớp.

Đối với biệt hiệu được cung cấp dưới dạng tên, forceToGenderize: true cho phép AI suy luận mà không cần tên thật. Giới tính được xác định trong tập dữ liệu có giá 1 tín dụng. Nếu cần AI, tổng chi phí là 2 tín dụng. Bất kỳ số dư ban đầu dương nào cũng đủ; số dư cuối cùng có thể âm.

## Hướng dẫn liên quan

- [Chế độ AI và forceToGenderize](https://www.genderapi.io/vi/docs/v2/ai-options)
- [Dự đoán hàng loạt](https://www.genderapi.io/vi/docs/v2/batch)
- [Tín dụng và cách sử dụng](https://www.genderapi.io/vi/docs/v2/credits-and-usage)
- [Lỗi và thử lại](https://www.genderapi.io/vi/docs/v2/errors-and-retries)