# Thông số yêu cầu API v2

> Tài liệu về các trường type, value, country, forceToGenderize và ai_mode của GenderAPI V2, cùng sự khác biệt giữa tham số GET và nội dung JSON của yêu cầu POST.

Canonical HTML: https://www.genderapi.io/vi/docs/v2/request-parameters

Last reviewed: 2026-09-25

## Tham số dự đoán đơn

Các trường tùy chọn nên được bỏ qua khi không sử dụng; không gửi null hoặc các chuỗi trống thay cho country hoặc options. Boolean JSON phải là true hoặc false, không phải chuỗi. Văn bản UTF-8 được hỗ trợ; tên không cần phải phiên âm thành ASCII.

GET sử dụng type, value, country, forceToGenderize và ai_mode trực tiếp trong chuỗi truy vấn, cùng với key tùy chọn. Mã hóa các giá trị bằng bộ mã hóa tham số URL của máy khách HTTP của bạn; ví dụ @ trở thành %40. Đối với các boolean GET, hãy gửi true hoặc false. Các trường không xác định và giá trị không hợp lệ sẽ bị từ chối.

| Trường JSON | Loại | Quy tắc |
| --- | --- | --- |
| type | string | Bắt buộc đối với POST: name, email hoặc username. GET mặc định là name. |
| value | string | Bắt buộc. 1–254 ký tự; không trống, không có ký tự điều khiển. Giá trị email phải là cú pháp email hợp lệ. |
| country | string | Mã ISO 3166-1 alpha-2 viết hoa tùy chọn, ví dụ TR hoặc US. Tra cứu theo quốc gia cụ thể có thể quay trở lại tập dữ liệu toàn cầu. |
| forceToGenderize | boolean | Tùy chọn; mặc định là false. Đầu tiên, tìm kiếm tập dữ liệu. Nếu không xác định được giới tính, hãy sử dụng AI để giải thích biệt hiệu. Được hỗ trợ cho cả ba loại đầu vào. |
| options.ai_mode | string | off, fallback hoặc always. Mặc định là fallback cho các yêu cầu đơn lẻ và off cho các mục hàng loạt. |
| id | string | Mã định danh tùy chọn có 1–64 ký tự trong phần nội dung POST JSON. Nó phải là duy nhất trong một lô và được trả về cùng với kết quả của lô đó. Các yêu cầu đơn lẻ chấp nhận mã định danh này nhưng không đưa nó vào phản hồi. Truy vấn GET không hỗ trợ nó. |

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

## Yêu cầu ví dụ theo ngôn ngữ

Ví dụ này sử dụng các trường yêu cầu được chia sẻ để tra cứu tên. Thay đổi type và value cho email hoặc tên người dùng hoặc đặt options.ai_mode và forceToGenderize như mô tả ở trên.

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)
    }
}
```

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