Dự đoán hàng loạt cho tên, email và tên người dùng

Tên, email và tên người dùng theo lô

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`items`	`array<object>`	Có	`—`	Từ 1 đến 50 mục dự đoán; tối đa 10 khi dùng thử theo IP. Kết quả giữ nguyên thứ tự đầu vào.
`items[].type`	`string`	Có	`—`	Loại đầu vào: name, email hoặc username.
`items[].value`	`string`	Có	`—`	Bắt buộc. 1–254 ký tự; không để trống, không chứa ký tự điều khiển. Giá trị email phải đúng cú pháp email.
`items[].country`	`string`	Không	`—`	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ể chuyển sang tập dữ liệu toàn cầu.
`items[].forceToGenderize`	`boolean`	Không	`false`	Tra tập dữ liệu trước, sau đó dùng AI có phân tích biệt danh nếu chưa xác định được. Hỗ trợ name, email và username.
`items[].options`	`object`	Không	`—`	Đối tượng chứa tùy chọn AI cho từng đầu vào.
`items[].options.ai_mode`	`string`	Không	`off`	Giá trị hợp lệ: off, fallback, always. Với forceToGenderize: true, bỏ qua trường này hoặc dùng fallback.
`items[].id`	`string`	Không	`—`	Mã định danh tùy chọn dài 1–64 ký tự trong JSON của POST. Được trả về cùng từng kết quả trong lô; phải là duy nhất trong một lô. Yêu cầu đơn lẻ chấp nhận trường này nhưng không trả lại. Không hỗ trợ trong truy vấn GET.

POST /gender/batch nhận mảng items gồm 1–50 mục khi truy cập bằng khóa API, hoặc tối đa 10 mục khi dùng thử theo IP. Bạn có thể chỉ gửi tên, chỉ gửi email, chỉ gửi tên người dùng hoặc kết hợp cả ba. Mỗi mục có country, forceToGenderize và options riêng. ID là tùy chọn và phải là duy nhất.

Kết quả giữ nguyên thứ tự đầu vào và gồm index, id tùy chọn của bạn, charged_credits cùng đúng một trong hai trường data hoặc error. HTTP 200 có thể chứa lỗi ở từng mục, vì vậy hãy kiểm tra mọi mục. meta.summary báo cáo total, succeeded, identified, unknown và failed. Dự đoán không xác định là một mục thành công và bị tính phí.

Nếu yêu cầu không vượt qua bước xác thực hoặc lập kế hoạch, cả lô bị từ chối trước khi trừ tín dụng. Nếu mọi mục đã thực thi đều thất bại, API trả về phản hồi Problem với mã trạng thái ngoài 2xx, kèm mảng data và bí danh cũ results. Các mục thất bại không tốn tín dụng sau khi việc hoàn trả được xác nhận. Nếu việc tính phí chưa được xác nhận, đừng coi phí của từng mục là cuối cùng.

Chọn ngôn ngữ lập trình. Thiết lập khóa API, sau đó chạy ví dụ trên máy chủ của bạn.

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.

Trước khi chạy: quyền truy cập và xử lý lỗi

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.

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. Với phản hồi lô HTTP 200, hãy kiểm tra thêm data hoặc error của từng mục.

Hướng dẫn về lỗi và thử lại →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Long",
      "country": "VN"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ trong shell POSIX. Chạy trong terminal. Tài liệu môi trường chạy

// 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 = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Long",
      "country": "VN"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  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.
}

Node.js 22+; fetch tích hợp sẵn. Lưu thành example.mjs và chạy node example.mjs. Tài liệu môi trường chạy

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("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Long\",\"country\":\"VN\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}")

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/batch",
    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.

Python 3.10+; thư viện chuẩn. Lưu thành example.py và chạy python3 example.py. Tài liệu môi trường chạy

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"contact-1","type":"name","value":"Long","country":"VN"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
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.

PHP 8+ với tiện ích mở rộng cURL. Lưu thành example.php và chạy php example.php. Tài liệu môi trường chạy

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 = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Long\",\"country\":\"VN\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}";
        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/batch"))
            .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.
    }
}

Java 17+; HTTP client chuẩn. Lưu thành GenderApiExample.java và chạy java GenderApiExample.java. Tài liệu môi trường chạy

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/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Long\",\"country\":\"VN\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", 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.
}

Ứng dụng console .NET 8+. Dùng làm Program.cs trong một dự án console, sau đó chạy dotnet run. Tài liệu môi trường chạy

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 := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Long\",\"country\":\"VN\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", 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)
    }
}

Go 1.22+; thư viện chuẩn. Lưu thành main.go và chạy go run main.go. Tài liệu môi trường chạy

Đọc phản hồi của lô

Ví dụ này kết hợp hai kết quả thực được ghi lại ngày 1 tháng 10 năm 2026, gồm một kết quả khớp tập dữ liệu và một kết quả không xác định, với một lỗi minh họa của nhà cung cấp. Ví dụ thể hiện phản hồi HTTP 200 thành công một phần, không phải kết quả dự kiến của yêu cầu lô ở trên. Hai mục thành công tốn 1 tín dụng mỗi mục; mục thất bại được xác nhận là không tính phí.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Long",
          "country": "VN"
        },
        "name": "long",
        "gender": "male",
        "country": "VN",
        "confidence": 0.9830866807610994,
        "confidence_kind": "observed_frequency",
        "sample_count": 473,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "long",
          "method": "normalized",
          "scope": "country",
          "country": "VN"
        }
      }
    },
    {
      "index": 1,
      "id": "missing",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "zzzxxyy",
          "country": null
        },
        "name": null,
        "gender": null,
        "country": null,
        "confidence": null,
        "confidence_kind": null,
        "sample_count": null,
        "source": "none",
        "result_status": "unknown",
        "reason": "not_found",
        "country_source": null,
        "match": {
          "name": null,
          "method": null,
          "scope": null,
          "country": null
        }
      }
    },
    {
      "index": 2,
      "id": "failed",
      "charged_credits": 0,
      "error": {
        "type": "urn:genderapi:problem:ai_upstream_error",
        "title": "ai upstream error",
        "status": 502,
        "detail": "The AI provider could not complete the request.",
        "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
        "code": "ai_upstream_error",
        "request_id": "11111111-1111-4111-8111-111111111111",
        "documentation": "https://api.genderapi.io/api/v2/errors",
        "action": "inspect_billing_before_retry"
      }
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 2,
      "remaining_credits": 6,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    },
    "summary": {
      "total": 3,
      "succeeded": 2,
      "identified": 1,
      "unknown": 1,
      "failed": 1
    }
  }
}

Trường kết quả của lô

Trường	Kiểu	Có thể là null	Ví dụ	Mô tả
`data`	`array<object>`	Không	`[…]`	Kết quả theo thứ tự. Mỗi mục chứa một dự đoán hoặc một lỗi; hãy kiểm tra từng mục.
`data[].index`	`integer`	Không	`0`	Vị trí trong mảng items đã gửi, bắt đầu từ 0.
`data[].id`	`string`	Không	`"contact-1"`	Mã định danh đầu vào của bạn, chỉ có khi được cung cấp.
`data[].charged_credits`	`integer`	Không	`1`	Phí thực tính của mục sau các lần hoàn trả đã xác nhận. Đừng coi là cuối cùng nếu việc tính phí của cả yêu cầu chưa được xác nhận.
`data[].data`	`object`	Không	`{…}`	Có ở mục thành công, kể cả kết quả không xác định. Dùng các trường dự đoán được mô tả trong hướng dẫn về phản hồi.
`data[].error`	`object`	Không	`{…}`	Có ở mục thất bại, thay cho data. Dùng các trường Problem Details được mô tả trong hướng dẫn về lỗi.

Trường tóm tắt của lô

Trường	Kiểu	Có thể là null	Ví dụ	Mô tả
`meta.summary.total`	`integer`	Không	`3`	Tổng số mục trong lô.
`meta.summary.succeeded`	`integer`	Không	`2`	Các mục thành công, kể cả dự đoán không xác định.
`meta.summary.identified`	`integer`	Không	`1`	Các mục thành công có gender khác null.
`meta.summary.unknown`	`integer`	Không	`1`	Các mục thành công có gender là null; đây là kết quả bị tính phí.
`meta.summary.failed`	`integer`	Không	`1`	Các mục thất bại. total = succeeded + failed; succeeded = identified + unknown.

Siêu dữ liệu về truy cập, tính phí và yêu cầu

Trường	Kiểu	Có thể là null	Ví dụ	Mô tả
`meta.request_id`	`string`	Không	`"550e8400-e29b-41d4-a716-446655440000"`	Mã định danh duy nhất của lần gửi HTTP này; cũng được gửi trong X-Request-ID.
`meta.duration_ms`	`integer`	Không	`42`	Thời gian xử lý yêu cầu tính bằng mili giây.
`meta.access.mode`	`string`	Không	`"api_key"`	api_key, ip_trial hoặc unauthenticated. Khi dùng tài khoản trả phí, hãy kiểm tra giá trị là api_key.
`meta.access.reason`	`string`	Có	`null`	Lý do chuyển sang dùng thử: api_key_missing, api_key_invalid hoặc api_key_not_found; trường hợp khác là null.
`meta.usage.charged_credits`	`integer`	Có	`1`	Số tín dụng thực tính. Bằng 0 trước khi tính phí hoặc sau khi hoàn trả toàn bộ đã được xác nhận; null khi việc tính phí chưa được xác nhận.
`meta.usage.remaining_credits`	`integer`	Có	`99`	Số dư khi thao tác hoàn tất. Có thể âm; null khi không có thông tin hoặc việc tính phí chưa được xác nhận.
`meta.usage.billing_status`	`string`	Không	`"confirmed"`	not_charged, confirmed hoặc unconfirmed. Kiểm tra trường này trước khi thử lại một dự đoán thất bại.
`meta.usage.resets_at`	`string`	Có	`"2026-09-27T12:00:00.000Z"`	Thời điểm đặt lại dùng thử theo IP, theo UTC (ISO 8601); null với tài khoản dùng khóa API hoặc khi chưa biết.
`meta.usage.limit`	`integer`	Có	`10`	Hạn mức dùng thử theo IP; null với tài khoản dùng khóa API.
`meta.usage.period_seconds`	`integer`	Có	`86400`	Chu kỳ dùng thử theo IP tính bằng giây; null với tài khoản dùng khóa API.

Lập kế hoạch tín dụng và thử lại cho lô

Xác thực bằng khóa API hiện có trong tiêu đề Bearer và gửi Content-Type: application/json. Mỗi lô được gửi là một thao tác mới. Nếu thử lại sau lỗi một phần, chỉ gửi các mục thất bại sau khi đã kiểm tra việc tính phí; gửi lại các mục thành công sẽ bị tính phí lần nữa.

Theo mặc định, các mục trong lô tắt AI (off) và tốn 1 tín dụng cho mỗi mục thành công. fallback được chọn rõ ràng cũng tốn tổng cộng 1 tín dụng, đã gồm AI. always tốn 2 tín dụng. forceToGenderize tốn 1 tín dụng khi tập dữ liệu cho ra kết quả, hoặc 2 tín dụng nếu dùng AI. Kết quả không xác định thành công vẫn bị tính phí. Chỉ cần số dư ban đầu dương là đủ để bắt đầu lô; lần tính phí cuối cùng có thể làm số dư âm.

Xử lý danh sách liên hệ và theo dõi đầy đủ từng dòng

Endpoint lô xử lý danh sách chỉ gồm tên, danh sách chỉ gồm email và đầu vào kết hợp. Chia một tác vụ dùng khóa API thành các phần tối đa 50 mục; dùng thử theo IP cho phép tối đa 10 mục mỗi yêu cầu. Tự lưu vị trí xử lý của tác vụ và đặt cho mỗi mục một id duy nhất trong lô của nó. index được trả về là vị trí bắt đầu từ 0 trong phần đã gửi, không phải trong toàn bộ danh sách liên hệ.

Bước	Cần lưu hoặc kiểm tra gì	Vì sao quan trọng
1. Chuẩn bị từng phần	Giữ lại dòng nguồn và id của mục; đặt country và tùy chọn AI cho từng mục.	Đừng dựa vào việc một tên là duy nhất trong danh sách liên hệ.
2. Đọc toàn bộ phản hồi	Lưu meta.request_id và đối chiếu từng mục trong data[] bằng id hoặc index.	HTTP 200 có thể chứa cả dự đoán thành công lẫn lỗi của từng mục.
3. Lưu kết quả thành công	Giữ các dự đoán identified và unknown, kể cả giá trị JSON null và các trường bằng chứng.	Kết quả không xác định là kết quả đã hoàn tất và bị tính phí; đó không phải dòng lỗi cần tự động thử lại.
4. Đối chiếu lỗi và tín dụng	Kiểm tra từng error và meta.usage.billing_status trước khi quyết định gửi yêu cầu khác.	Khi việc tính phí đã được xác nhận, chỉ thử lại những mục lỗi có mã lỗi cho phép thử lại. Các mục thành công sẽ bị tính phí lần nữa.
5. Tạm dừng các lần thử lại chưa chắc chắn	Giữ lại request ID khi việc tính phí chưa được xác nhận hoặc lỗi mạng khiến kết quả không rõ.	Đừng gửi lại toàn bộ phần một cách máy móc; trước tiên hãy làm theo hướng dẫn về lỗi và tính phí.

Chọn chế độ suy luận cho từng liên hệ

Yêu cầu có thể chạy ngay này dùng ba chính sách khác nhau: chỉ dùng tập dữ liệu cho một họ tên đầy đủ, AI dự phòng thông thường cho một email và AI dự phòng có phân tích biệt danh cho một tên người dùng. Đây chỉ là đầu vào ví dụ, không phải lời hứa rằng cả ba liên hệ đều sẽ nhận được giới tính. Chọn ngôn ngữ lập trình phía trên đoạn mã và đặt GENDERAPI_API_KEY trước khi chạy.

Khi không có forceToGenderize, AI mặc định bị tắt (off) cho các mục trong lô, khác với yêu cầu đơn lẻ. Hãy đặt fallback một cách rõ ràng nếu muốn dùng AI dự phòng thông thường. Cả off và fallback thông thường đều tốn 1 tín dụng cho mỗi mục thành công; always bỏ qua tập dữ liệu và tốn 2 tín dụng. forceToGenderize tốn 1 tín dụng khi tập dữ liệu cho ra kết quả, hoặc tổng cộng 2 tín dụng nếu dùng AI. Kết quả không xác định thành công cũng bị tính phí. Không kết hợp forceToGenderize với off hoặc always.