API 文档 V2

使用 API V2 根据姓名判断性别

使用 GenderAPI.io V2 根据名字或全名预测性别。查看七种编程语言的示例、JSON 响应、国家/地区背景、AI 回退和积分费用。

发送请求之前

将 JSON 发送到 POST https://api.genderapi.io/api/v2/gender。请在 Authorization: Bearer YOUR_API_KEY 中使用您现有的 API 密钥,并发送 Content-Type: application/json。每个请求都会被独立处理。

在代码示例中选择编程语言。运行前,请在进程环境中设置 GENDERAPI_API_KEY。缺失或无法识别的密钥可能会使用共享的 IP 试用,因此集成账户时请确认 meta.access.mode 为 api_key。

根据姓名判断性别

参数类型必填默认值说明
typestring是—输入类别:name、email 或 username。
valuestring是—必填。1–254 个字符;不能为空白,不能包含控制字符。email 类型的值必须符合有效的电子邮箱地址语法。
countrystring否—可选,大写的 ISO 3166-1 alpha-2 代码,例如 TR 或 US。按国家/地区查询时,可能会回退到全球数据集。
forceToGenderizeboolean否false先查询数据集,无法确定时再使用可识别昵称的 AI。支持 name、email 和 username。
optionsobject否—存放每项输入的 AI 选项的对象。
options.ai_modestring否fallback允许的值:off、fallback、always。使用 forceToGenderize: true 时,请省略此字段或使用 fallback。
idstring否—POST JSON 中可选的 1–64 个字符的标识符。会随每个批量结果一起返回;在同一批量请求中必须唯一。单个预测也接受此字段,但不会在响应中返回。GET 查询不支持。

对名字或全名使用 type: name。成功的响应中仍可能包含 gender: null。单个请求会先查询数据集;无法确定性别时,默认会调用 AI。

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

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

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

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

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

错误与重试指南 →
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": "name",
  "value": "Wei",
  "country": "CN"
}'

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

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": "name",
  "value": "Wei",
  "country": "CN"
};

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。运行环境文档

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\":\"Wei\",\"country\":\"CN\"}")

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
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Wei","country":"CN"}', 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。运行环境文档

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\":\"Wei\",\"country\":\"CN\"}";
        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。运行环境文档

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\":\"name\",\"value\":\"Wei\",\"country\":\"CN\"}", 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。运行环境文档

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\":\"Wei\",\"country\":\"CN\"}"
    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。运行环境文档

响应示例

这是 2026年10月1日使用 API 密钥获取的真实响应,仅替换了账户余额。它并不是准确性的衡量标准,实时请求可能返回不同的结果。使用 API 密钥的请求会返回 meta.access.mode: api_key,且仅适用于试用的额度字段为 null;IP 试用请求会返回 ip_trial。推断结果请读取 data,该操作的计费结果请读取 meta.usage。

说明性 JSON 响应
{
  "data": {
    "input": {
      "type": "name",
      "value": "Wei",
      "country": "CN"
    },
    "name": "wei",
    "gender": "male",
    "country": "CN",
    "confidence": 0.8647342995169082,
    "confidence_kind": "observed_frequency",
    "sample_count": 207,
    "source": "dataset",
    "result_status": "identified",
    "reason": null,
    "country_source": "dataset",
    "match": {
      "name": "wei",
      "method": "normalized",
      "scope": "country",
      "country": "CN"
    }
  },
  "meta": {
    "request_id": "53943fbf-f490-4c0d-902e-b5dac9822b66",
    "duration_ms": 10,
    "access": {
      "mode": "api_key",
      "reason": null
    },
    "usage": {
      "charged_credits": 1,
      "remaining_credits": 49999,
      "billing_status": "confirmed",
      "resets_at": null,
      "limit": null,
      "period_seconds": null
    }
  }
}

预测响应字段

字段类型可为 null示例说明
data.inputobject否{"type":"name","value":"Wei","country":"CN"}输入类型、值和国家/地区。forceToGenderize 为 true 时会包含该字段。
data.namestring是"wei"匹配到或提取出的名字;没有时为 null。
data.genderstring是"male"male、female 或 JSON null。这是一种推断,而不是经过验证的个人身份。
data.result_statusstring否"identified"返回性别时为 identified,否则为 unknown。
data.reasonstring是nullidentified 结果为 null。未知原因:not_found、no_name_candidate、ambiguous 或 insufficient_evidence。
data.confidencenumber是0.950–1 之间的值或 null。性别为 null 时,置信度也为 null。
data.confidence_kindstring是"observed_frequency"observed_frequency:主导性别的数据集计数 / 总计数。model_reported:AI 给出的值,不是经过校准的概率。不可用时为 null。
data.sample_countinteger是1200数据集样本数或 null。AI 不会编造样本数。
data.sourcestring否"dataset"dataset、ai 或 none。
data.countrystring是"CN"来自 dataset 或 ai_association 的国家/地区关联,或为 null。它不能说明国籍、居住地或族裔。
data.country_sourcestring是"dataset"国家/地区关联的来源:dataset、ai_association 或 null。
data.matchobject否{"name":"wei","method":"normalized","scope":"country","country":"CN"}匹配到的数据集姓名、匹配方式(normalized、token、substring 或 model_inference)、country/global 范围以及匹配的国家/地区。无法提供的依据为 null。

访问、计费与请求元数据

字段类型可为 null示例说明
meta.request_idstring否"550e8400-e29b-41d4-a716-446655440000"本次 HTTP 尝试的唯一标识符,也会通过 X-Request-ID 返回。
meta.duration_msinteger否42请求处理时间(毫秒)。
meta.access.modestring否"api_key"api_key、ip_trial 或 unauthenticated。使用付费账户时,请确认值为 api_key。
meta.access.reasonstring是null转为试用的原因:api_key_missing、api_key_invalid 或 api_key_not_found;其他情况为 null。
meta.usage.charged_creditsinteger是1净扣除的积分。扣费前或全额退款确认后为零;计费未确认时为 null。
meta.usage.remaining_creditsinteger是99操作完成时的余额。可能为负数;不可用或计费未确认时为 null。
meta.usage.billing_statusstring否"confirmed"not_charged、confirmed 或 unconfirmed。重试失败的预测前请检查此字段。
meta.usage.resets_atstring是"2026-09-27T12:00:00.000Z"IP 试用的重置时间,UTC(ISO 8601);API 密钥账户或时间未知时为 null。
meta.usage.limitinteger是10IP 试用额度;API 密钥账户为 null。
meta.usage.period_secondsinteger是86400IP 试用周期(秒);API 密钥账户为 null。

国家/地区背景与未知姓名

只有在掌握相关背景时才提供 country。API 可能选择特定国家/地区的数据行,也可能回退到全球数据行。data.match.scope 显示实际选用的是哪一种;返回的国家/地区并不能说明此人居住在哪里。

单个请求默认使用 AI 回退,总共消耗 1 个积分。若只使用数据集,请发送 options: {"ai_mode": "off"}。无法确定的输入可能返回 gender: null,只要操作成功完成,仍会计费。全名可能通过其中某个组成部分匹配;data.match 会记录所选候选项和匹配方式。

对于类似昵称的 name 值,forceToGenderize: true 允许在没有真实名字的情况下进行推断:数据集得出结果时消耗 1 个积分;否则使用可识别昵称的 AI,总共消耗 2 个积分。起始余额为正即可发起请求,扣费后的余额可能为负数。

查询全名时,不要假定第一个词会被选中

请发送原始的 Unicode 姓名。数据集匹配会进行 NFKC 规范化、转为小写并提取姓名组成部分;您无需把姓名转换为 ASCII。在可用的候选记录中,API 会选择存储总计数最大的那一条。该候选项可能是姓名中靠后的某个部分,因此不要假定被选中的是第一个词或名字。

此请求仅使用数据集,便于检查所选用的依据。请读取 data.input.value 了解提交的全名,读取 data.match.name 了解用于查询的候选项,读取 data.match.method 了解匹配方式。此示例并不承诺返回某个特定性别,也不承诺选中某个特定部分。数据集候选项必须长于两个字符,较短的输入可能无法得出结果。如果额外的推断适合您的应用,请使用普通的 AI 回退。

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

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

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

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

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

错误与重试指南 →
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": "name",
  "value": "Ayşe Yılmaz",
  "country": "TR",
  "options": {
    "ai_mode": "off"
  }
}'

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

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": "name",
  "value": "Ayşe Yılmaz",
  "country": "TR",
  "options": {
    "ai_mode": "off"
  }
};

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。运行环境文档

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}")

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
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Ayşe Yılmaz","country":"TR","options":{"ai_mode":"off"}}', 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。运行环境文档

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}";
        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。运行环境文档

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\":\"name\",\"value\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}", 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。运行环境文档

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\":\"Ayşe Yılmaz\",\"country\":\"TR\",\"options\":{\"ai_mode\":\"off\"}}"
    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。运行环境文档

检查实际起作用的国家/地区背景

只有在掌握相关背景时才使用 ISO 国家/地区代码;不要根据预测结果反推一个国家/地区。对于每个候选项,现有的国家/地区数据行优先于其全球数据行。如果没有国家/地区数据行,该候选项可以使用全球数据行。计数持平的国家/地区数据行不会被其全球数据行取代:如果所选数据行计数持平,数据集结果为 unknown,已启用的 AI 回退随后可能运行。

响应中的依据含义应用中的处理
match.scope: country; match.country: TR所选的数据集候选项使用了请求中指定国家/地区的数据行。将所选候选项和国家/地区范围与预测一起保存。
match.scope: global; match.country: null即使请求提供了国家/地区,所选候选项使用的仍是全球数据行。不要把该结果标记为特定国家/地区的匹配。
country_source: dataset 或 ai_association说明 data.country 的来源,而不是数据集查询的范围,也不是此人的国籍。请将其与 match.country 分开读取;这两个字段都不能证明居住地或国籍。
source: ai; match.scope: null最终响应由 AI 生成,因此该响应中没有选用任何数据集数据行。遵循 AI 置信度的相关指引,并保留未知结果。

相关指南