根据阿拉伯姓名判断性别

姓名	—
性别	未知
置信度	—
来源	AI 模型
已用积分	1

保留阿拉伯文拼写，并检查匹配到的名字

请按原始的 Unicode 拼写发送姓名。工具的输入框按从右到左显示阿拉伯文，而本页的中文说明和响应 JSON 按从左到右阅读。您无需事先把姓名转写为拉丁字母。API 接受这种文字，并不代表数据集中一定有对应的记录。

数据集查询会进行 Unicode NFKC 规范化，并把文本拆分为多个部分。系统没有通用规则去除阿拉伯文元音符号，也不会把不同拼写视为等同。因此，元音符号和其他拼写差异可能决定匹配到哪条存储记录。请保留原始值，不要悄悄把所有变体当作同一个名字处理。

一个完整姓名可能产生多个候选项。系统会选择存储总计数最大的可用记录，因此第一个词不一定就是返回的名字。在用结果补充记录之前，请检查 data.name 和 data.match.name。

输入示例	说明	需要检查的内容
`ليلى الخطيب`	完整姓名示例	多个部分都可能参与查询。请检查所选的匹配；此示例并不预示实时结果。
`ليلى / لَيْلَى`	不带与带元音符号的拼写	请发送实际的拼写。无法保证这两个字符串会对应到同一条存储记录。
`Layla / Leila`	拉丁字母拼写	这是不同的输入值。V2 不保证会自动把不同的转写视为等同。
`country: SA`	示例背景：沙特阿拉伯	此背景并不是所有阿拉伯语社群的默认值。不了解国家/地区时，请省略 country。

审慎选择国家/地区背景 SA

实时演示会发送 country: SA（沙特阿拉伯）。API 不会根据姓名所用的文字来选择这个国家/地区。请在您的集成中使用已知且相关的国家/地区背景，或者省略 country。不要把这个示例值变成所有记录的默认值。

对于每个候选项，查询会在存在国家/地区专属记录时选择该记录，否则选择全局记录。然后，系统会选择存储总计数最大的可用候选项。实际的匹配范围见 data.match.scope 和 data.match.country。频次相同的国家/地区专属记录不会被自动替换为全局结果；如果启用了回退，则可能改用 AI。

data.input.country 表示请求中发送的国家/地区背景。data.country 和 data.country_source 表示返回的国家/地区关联及其来源。这些字段各不相同，都不能说明国籍、族裔或居住地。

国家/地区背景与匹配

用您应用中的姓名发送 V2 请求

请把您现有的 API 密钥设置到 GENDERAPI_API_KEY 中，然后在您的服务器上运行示例。该请求显式启用了普通的自动 AI 回退。它展示的是请求如何构建，而不是实测的准确率或已确认的覆盖范围。如果您需要仅基于数据集的预测，请设置 options.ai_mode: off。

选择编程语言。设置您的 API 密钥，然后在您的服务器上运行示例。

每个预测请求（包括重试）都是一次新的计费操作。这些示例不会自动重试。发送下一个请求之前，请先检查计费状态。

运行之前：访问与错误处理

请在您的服务器上运行这些示例。在进程环境中将 GENDERAPI_API_KEY 设置为您现有的 API 密钥。请确认 meta.access.mode 为 api_key：无法识别的密钥可能会转为使用 IP 试用。

对于 HTTP 4xx 和 5xx JSON 响应，示例会保留错误响应体并以非零状态退出。重试前请检查 code、action 和 meta.usage.billing_status。

错误与重试指南 →

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": "ليلى الخطيب",
  "country": "SA",
  "options": {
    "ai_mode": "fallback"
  }
}'

cURL 7.76+，在 POSIX shell 中运行。在终端中运行。运行环境文档

// 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": "ليلى الخطيب",
  "country": "SA",
  "options": {
    "ai_mode": "fallback"
  }
};

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+；内置 fetch。保存为 example.mjs，然后运行 node example.mjs。运行环境文档

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\":\"ليلى الخطيب\",\"country\":\"SA\",\"options\":{\"ai_mode\":\"fallback\"}}")

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+；标准库。保存为 example.py，然后运行 python3 example.py。运行环境文档

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"ليلى الخطيب","country":"SA","options":{"ai_mode":"fallback"}}', 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+，需要 cURL 扩展。保存为 example.php，然后运行 php example.php。运行环境文档

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\":\"ليلى الخطيب\",\"country\":\"SA\",\"options\":{\"ai_mode\":\"fallback\"}}";
        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+；标准 HTTP 客户端。保存为 GenderApiExample.java，然后运行 java GenderApiExample.java。运行环境文档

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\":\"ليلى الخطيب\",\"country\":\"SA\",\"options\":{\"ai_mode\":\"fallback\"}}", 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.
}

.NET 8+ 控制台应用。在控制台项目中作为 Program.cs 使用，然后运行 dotnet run。运行环境文档

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\":\"ليلى الخطيب\",\"country\":\"SA\",\"options\":{\"ai_mode\":\"fallback\"}}"
    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+；标准库。保存为 main.go，然后运行 go run main.go。运行环境文档

将结果与其依据一起保存

推断出的关联并不是本人自述的性别。请把原始输入、返回的依据以及本人提供的信息分开保存。未知结果是有效的结果，不应在您的应用中变成一个猜测出来的类别。

字段	使用方式
`data.gender / data.result_status`	只有在 identified 时才使用 male 或 female。结果未知时，请保留 JSON 原生的 null 值。
`data.name / data.match`	检查返回的名字和所选的候选项。子字符串匹配并不能证明该输入属于拥有这个名字的人。
`data.confidence / data.confidence_kind`	置信度为 0–1 之间的值或 null。observed_frequency 来自存储的计数；model_reported 是 AI 给出的值。请针对每种类型分别评估阈值。
`data.source / data.sample_count`	区分 dataset、ai 和 none。AI 结果没有存储的样本数。样本数并不是实测的准确率。
`meta.access.mode`	在账户集成中，请确认值为 api_key。缺失或无法识别的密钥可能会转为使用共享的 IP 试用。
`meta.usage`	读取 charged_credits 和 billing_status。成功完成的未知结果同样计费。响应丢失并不能证明该请求是免费的。

决定何时使用 AI

forceToGenderize 对姓名、电子邮箱地址和用户名都是可选的。启用时，请省略 ai_mode 或使用 fallback；off 和 always 不能与此选项组合，否则会返回 422。起始余额为正即可发起请求，即使最终扣费后余额变为负数。

昵称模式可能在 name: null 的同时返回性别，也可能得到未知结果。无论是普通的 AI 回退还是昵称解读，都不能保证答案正确或返回非 null 的值。

请求选项	行为	每次成功查询消耗的积分
options.ai_mode: off	仅使用数据集。	1，未知结果也是如此
options.ai_mode: fallback	先查询数据集；如果没有返回性别，再使用普通的 AI。这是单个请求的默认值。	总共 1，包括 AI 回退
options.ai_mode: always	直接使用 AI。	2
forceToGenderize: true	先查询数据集，然后允许 AI 解读个人昵称或别名，即使没有真实名字也可以。	数据集得出结果时为 1；使用 AI 时总共为 2

处理姓名列表时保留背景信息

通过 POST /api/v2/gender/batch 发送条目：使用 API 密钥时最多 50 个，使用 IP 试用时最多 10 个。请为每个条目设置唯一的 id，并保留每一行的原始值。每个条目都可以有自己的国家/地区和 AI 选项；不了解国家/地区时请省略它。

单个请求默认使用回退，而批量请求中的条目默认只使用数据集。需要 AI 的条目，请分别设置 options.ai_mode: fallback。即使返回 HTTP 200，也请逐条检查结果，保存未知结果，并在重新发送之前检查错误和计费。每个成功的普通条目消耗 1 个积分；一个包含批量条目的 HTTP 请求并不等于每次预测只消耗一个积分。

了解您发送了什么

实时演示只会在您提交时，才把输入的值发送给 GenderAPI.io。如果调用了 AI，提交的 type、value 和国家/地区背景会被发送给已配置的推断服务。如需仅基于数据集的预测，请在您的集成中使用 options.ai_mode: off，且不要使用 forceToGenderize。

隐私政策、数据处理协议和次级处理方名单说明了已公布的处理条款。结果只是推断出的关联，本人的自述优先。请不要把它作为对个人有重大影响的决策依据。

常见问题

V2 接受带元音符号的阿拉伯姓名吗？

V2 接受 Unicode 姓名输入，包括阿拉伯文字。数据集规范化通常不会去除阿拉伯文元音符号，因此带与不带元音符号的拼写可能得到不同的匹配，或得到未知结果。

此工具能判断说阿拉伯语的人的国籍吗？

不能。SA 是为本演示明确选择的国家/地区背景。文字、名字的关联或返回的国家/地区字段都不能说明国籍或居住地。

是否已发布针对这类姓名的独立准确率评估？

本页没有发布此类评估。输入被接受、显示了存储的频次或返回了置信度，都不是独立的准确率测量。方法说明介绍了现有哪些数据，以及哪些测量尚未发布。

没有预测结果时会消耗积分吗？

成功完成的未知结果同样计费。普通模式（仅使用数据集或使用回退）总共消耗 1 个积分。使用 forceToGenderize 时，结果来自数据集则消耗 1 个积分，使用 AI 则总共消耗 2 个积分，未知结果也是如此。错误适用单独的计费规则；请检查 meta.usage。