# Giới tính từ một địa chỉ email có API v2

> Sử dụng GenderAPI v2 để suy ra giới tính từ tín hiệu tên email. Bao gồm các ví dụ về yêu cầu và phản hồi, xác thực, kết quả không xác định và các tùy chọn AI.

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

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ừ một địa chỉ email

Sử dụng type: email. API tìm kiếm tín hiệu tên có thể sử dụng được trong địa chỉ. Hộp thư đến được chia sẻ và các phần cục bộ không rõ ràng có thể tạo ra kết quả không xác định. forceToGenderize ở đây cũng là tùy chọn; nó cho phép AI suy luận từ một bí danh ngay cả khi không có tên thật.

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": "email",
  "value": "alice.smith@example.com",
  "country": "US"
}'
```

**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": "email",
  "value": "alice.smith@example.com",
  "country": "US"
};

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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\"}")

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":"email","value":"alice.smith@example.com","country":"US"}', 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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\"}";
        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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\"}", 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\":\"email\",\"value\":\"alice.smith@example.com\",\"country\":\"US\"}"
    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": "email",
      "value": "alice.smith@example.com",
      "country": "US"
    },
    "name": "alice",
    "gender": "female",
    "country": "US",
    "confidence": 0.9,
    "confidence_kind": "observed_frequency",
    "sample_count": 100,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "alice",
      "method": "normalized",
      "scope": "country",
      "country": "US"
    }
  },
  "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)

## Tín hiệu xác thực email và tên

value phải là địa chỉ email hợp lệ về mặt cú pháp. Cú pháp không hợp lệ trả về HTTP 422 trước khi thanh toán. Xác thực cú pháp không xác định rằng hộp thư tồn tại hoặc thuộc về một người cụ thể.

Tên cá nhân có thể nhận dạng được trong địa chỉ có thể khớp với tập dữ liệu. Hộp thư dùng chung, địa chỉ vai trò và các phần cục bộ không rõ ràng có thể trả về giới tính: null. Theo mặc định, một tra cứu đơn lẻ chưa được giải quyết sử dụng dự phòng AI thông thường cho tổng cộng 1 tín dụng, bao gồm cả một kết quả không xác định thành công.

Sử dụng forceToGenderize: true nếu bạn muốn suy luận AI nhận biết biệt hiệu khi tập dữ liệu chưa được giải quyết. Việc này tiêu tốn 1 tín dụng cho một kết quả tập dữ liệu đã được giải quyết hoặc tổng cộng 2 tín dụng nếu sử dụng AI. API vẫn có thể trả về null. Miền email không phải là bằng chứng về vị trí của người đó; chỉ cung cấp cho một quốc gia khi biết được bối cảnh liên quan.

## 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)