TÀI LIỆU API V2

Giới tính từ tên người dùng với API v2

Dự đoán từ tên người dùng và biệt danh với GenderAPI v2. Tìm hiểu forceToGenderize, tra cứu tập dữ liệu đầu tiên, các trường phản hồi AI và biểu giá tín dụng 1 hoặc 2.

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.

Giới tính từ tên người dùng hoặc biệt danh

Sử dụng type: username làm tên người dùng hoặc biệt danh. Đặt forceToGenderize thành true để suy ra giới tính từ ý nghĩa của bí danh, chẳng hạn như prenses, ngay cả khi không thể trích xuất tên thật. Tập dữ liệu được kiểm tra đầu tiên. Dự đoán biệt hiệu có thể trả về giới tính ngay cả khi name: null.

Chọn ngôn ngữ lập trình. Thiết lập khóa API của bạn, 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 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.

Trước khi chạy: 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 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.

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.

Hướng dẫn lỗi và thử lại →
cURL
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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
}'

cURL 7.76+ trong vỏ POSIX. Chạy trong terminal của bạn. Tài liệu về thời gian chạy

JavaScript / Node.js
// 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": "username",
  "value": "prenses",
  "country": "TR",
  "forceToGenderize": true
};

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.
}

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. Tài liệu về thời gian chạy

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\":\"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",
    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 dưới dạng example.py và chạy python3 example.py. Tài liệu về thời gian chạy

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"username","value":"prenses","country":"TR","forceToGenderize":true}', 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.

PHP 8+ với phần mở rộng cURL. Lưu dưới dạng example.php và chạy php example.php. Tài liệu về thời gian chạy

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\":\"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"))
            .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+; máy khách HTTP tiêu chuẩn. Lưu dưới dạng GenderApiExample.java và chạy java GenderApiExample.java. Tài liệu về thời gian chạy

C# / .NET
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\":\"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 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. Tài liệu về thời gian chạy

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\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}"
    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)
    }
}

Go 1.22+; thư viện chuẩn. Lưu dưới dạng main.go và chạy go run main.go. Tài liệu về thời gian chạy

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.

Phản hồi JSON minh họa
{
  "data": {
    "input": {
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    },
    "name": null,
    "gender": "female",
    "country": "TR",
    "confidence": 0.7,
    "confidence_kind": "model_reported",
    "sample_count": null,
    "source": "ai",
    "result_status": "identified",
    "reason": null,
    "country_source": "ai_association",
    "match": {
      "name": null,
      "method": "model_inference",
      "scope": null,
      "country": null
    }
  },
  "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": -1,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

Đọc dự đoán biệt danh

Ví dụ này sử dụng forceToGenderize: true. Nếu tập dữ liệu xác định giới tính thì chi phí là 1 tín dụng. Mặt khác, AI sẽ giải thích bí danh và một yêu cầu hoàn thành sẽ tốn tổng cộng 2 tín dụng, ngay cả khi vẫn chưa xác định được giới tính. Bỏ qua ai_mode hoặc đặt thành fallback. Sử dụng off hoặc always cùng với forceToGenderize sẽ trả về HTTP 422.

Trong chế độ biệt hiệu, cho phép dự đoán giới tính với name: null. Điều đó có nghĩa là không có tên thật nào được trích xuất, không phải việc phân tích cú pháp đó không thành công. Nếu AI trả về giới tính, sample_count: null và confidence_kind: model_reported sẽ được trả về. Điểm số không phải là xác suất được hiệu chỉnh và không xác minh danh tính cá nhân.

Nếu không có forceToGenderize, một lần tra cứu tên người dùng vẫn mặc định là AI fallback thông thường với tổng 1 tín dụng, nhưng nó yêu cầu một tên thật có thể sử dụng được. Sử dụng options.ai_mode: off để xử lý chỉ tập dữ liệu.

Hướng dẫn liên quan