Bestem køn ud fra et brugernavn eller kaldenavn

Navn	Lasse
Køn	Mand
Sikkerhed	98 %
Kilde	AI-model
Brugte kreditter	2

Navnesignaler og kaldenavnes betydning er to forskellige ting

Brug type: username til et brugernavn eller kaldenavn. Et valgfrit @ i starten fjernes ved matchet med datasættet. Udtrækningen af kandidater tager højde for skilletegn og cifre og kan kontrollere begrænsede delstrenge. Kaldenavnstilstanden matcher stadig hele dele, men tilføjer ikke disse delstrengskandidater. Den valgte lagrede post har det højeste samlede antal blandt de tilgængelige kandidater. Det angiver ikke det egentlige navn på personen bag kontoen.

Den almindelige automatiske AI-fallback leder efter et genkendeligt fornavn. forceToGenderize tillader desuden en sammenhæng via et personligt kaldenavn, når der ikke kan udtrækkes et egentligt navn. Begge veje kan returnere unknown. Et varemærke, en fiktiv figur eller en delt konto repræsenterer ikke nødvendigvis én enkelt person.

Eksempel på input	Fremgangsmåde	Hvad du skal kontrollere
`@alice.smith`	Start med den almindelige fallback, som først slår op i datasættet.	Kontrollér det valgte navn og matchmetoden. Gå ikke ud fra, at den første del er valgt.
`robert89`	Cifre kan fjernes, når kandidater udtrækkes.	Et matchende navn er en sammenhæng, ikke en bekræftet identitet.
`prenses`	Slå forceToGenderize til for at tillade et AI-forsøg ud fra kaldenavnet, når der ikke findes et resultat.	gender kan have en værdi, der ikke er null, mens name er null. AI-værdier er model_reported.
`team_support`	Behandl rollekonti og delte konti som konti, der måske ikke tilhører én enkelt person.	Bevar unknown, og tildel ikke en delt konto en individuel identitet.

Afprøv fortolkning af kaldenavne i din integration

Denne forespørgsel slår fortolkning af kaldenavne til. Datasættet slås op først. Hvis det ikke returnerer et køn, kan AI bruge aliassets betydning. Udelad forceToGenderize for et almindeligt opslag. Enkeltforespørgsler bruger stadig den almindelige automatiske AI-fallback som standard.

I dette eksempel angives landekonteksten TR. Brug en relevant kontekst fra din applikation, og kontrollér data.match.scope. Et angivet land garanterer ikke en landespecifik post. Det angiver hverken nationalitet eller bopæl.

Vælg et programmeringssprog. Konfigurér din API-nøgle, og kør derefter eksemplet på din server.

Hver forespørgsel om en forudsigelse er en ny operation, der koster kreditter, også når den gentages. Eksemplerne prøver ikke automatisk igen. Kontrollér opkrævningsstatus, før du sender en ny forespørgsel.

Før du kører: adgang og fejlhåndtering

Kør eksemplerne på din server. Sæt GENDERAPI_API_KEY i procesmiljøet til din eksisterende API-nøgle. Bekræft, at meta.access.mode er api_key: En nøgle, der ikke genkendes, kan føre til IP-prøveadgangen.

JSON-svar med HTTP 4xx og 5xx bevarer fejlens body og returnerer en exitstatus, der ikke er nul. Kontrollér code, action og meta.usage.billing_status, før du prøver igen.

Guide til fejl og nye forsøg →

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+ i en POSIX-shell. Kør i din terminal. Dokumentation for kørselsmiljøet

// 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+, indbygget fetch. Gem som example.mjs, og kør node example.mjs. Dokumentation for kørselsmiljøet

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+, standardbiblioteket. Gem som example.py, og kør python3 example.py. Dokumentation for kørselsmiljøet

<?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+ med cURL-udvidelsen. Gem som example.php, og kør php example.php. Dokumentation for kørselsmiljøet

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+, standard-HTTP-klienten. Gem som GenderApiExample.java, og kør java GenderApiExample.java. Dokumentation for kørselsmiljøet

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

Konsolapplikation med .NET 8+. Brug som Program.cs i et konsolprojekt, og kør derefter dotnet run. Dokumentation for kørselsmiljøet

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+, standardbiblioteket. Gem som main.go, og kør go run main.go. Dokumentation for kørselsmiljøet

Fuld V2-reference for brugernavne

Gem resultatet sammen med evidensen

En udledt sammenhæng er ikke det køn, en person selv har oplyst. Gem det oprindelige input, den returnerede evidens og det, personen selv har oplyst, hver for sig. Et ukendt resultat er et gyldigt resultat og bør ikke blive til en gættet kategori i din applikation.

Felt	Sådan bruger du det
`data.gender / data.result_status`	Brug kun male eller female, når status er identified. Bevar den native JSON-værdi null, når resultatet er ukendt.
`data.name / data.match`	Kontrollér det returnerede navn og den valgte kandidat. Et match på en delstreng beviser ikke, at inputtet tilhører en person med det navn.
`data.confidence / data.confidence_kind`	Konfidensen ligger på en skala fra 0 til 1 eller er null. observed_frequency bygger på lagrede frekvenser, mens model_reported er en værdi angivet af AI. Vurdér tærskelværdier separat for hver type.
`data.source / data.sample_count`	Skeln mellem dataset, ai og none. AI-resultater har ingen lagret stikprøvestørrelse. En stikprøvestørrelse er ikke en målt nøjagtighed.
`meta.access.mode`	Kontrollér i en integration med konto, at api_key returneres. Manglende eller ukendte nøgler kan i stedet bruge den delte IP-prøveadgang.
`meta.usage`	Læs charged_credits og billing_status. Et gennemført ukendt resultat koster kreditter. Et mistet svar beviser ikke, at forespørgslen var gratis.

Beslut, hvornår AI skal bruges

forceToGenderize er valgfrit for navne, e-mailadresser og brugernavne. Når det er slået til, skal du udelade ai_mode eller bruge fallback. off og always kan ikke kombineres med denne indstilling og returnerer 422. En positiv startsaldo er nok til at starte en forespørgsel, også selvom den endelige opkrævning gør saldoen negativ.

Kaldenavnstilstanden kan returnere et køn sammen med name: null. Den kan også give et ukendt resultat. Hverken den almindelige automatiske AI-fallback eller fortolkningen af kaldenavne garanterer et korrekt svar eller en værdi, der ikke er null.

Indstilling i forespørgslen	Adfærd	Kreditter for en gennemført forespørgsel
options.ai_mode: off	Bruger kun datasættet.	1, også for et ukendt resultat
options.ai_mode: fallback	Slår først op i datasættet og bruger derefter almindelig AI, hvis der ikke returneres et køn. Det er standarden for enkeltforespørgsler.	1 i alt, inklusive automatisk AI-fallback
options.ai_mode: always	Bruger AI direkte.	2
forceToGenderize: true	Slår først op i datasættet og lader derefter AI fortolke et personligt kaldenavn eller alias, også uden et egentligt fornavn.	1 for et resultat fra datasættet, 2 i alt, hvis AI bruges

Bevar resultatet for hvert brugernavn, når du behandler en liste

Brug POST /api/v2/gender/batch til lister med brugernavne eller blandede lister med navne, e-mailadresser og brugernavne. Grænsen er 50 elementer med en API-nøgle eller 10 med IP-prøveadgangen. Hvert element har sine egne indstillinger for land og AI, og valgfrie id'er skal være unikke inden for batchen.

Som standard bruger en batch kun datasættet. Slå fallback til pr. element, hvis du vil bruge almindelig AI, eller angiv forceToGenderize pr. element for at fortolke kaldenavne. Kontrollér data eller error i hvert resultat, og brug id eller index til at knytte resultatet til den oprindelige række. Gennemførte ukendte elementer koster kreditter.

Vid, hvad du sender

Live-demoen sender kun den indtastede værdi til GenderAPI.io, når du selv sender den. Hvis AI bruges, videregives type, value og den sendte landekontekst til den tjeneste, der er konfigureret til forudsigelser. Hvis du kun vil have en forudsigelse fra datasættet, skal du i din integration angive options.ai_mode: off uden forceToGenderize.

Privatlivspolitikken, databehandleraftalen og listen over underdatabehandlere beskriver de offentliggjorte vilkår for behandlingen. Et resultat er en udledt sammenhæng, og det, en person selv oplyser, har forrang. Brug det ikke som grundlag for beslutninger, der har betydelige konsekvenser for en person.

Ofte stillede spørgsmål

Skal et brugernavn indeholde et egentligt fornavn?

Den almindelige AI-forudsigelse kræver et brugbart fornavn. Med forceToGenderize kan API'et desuden forsøge en sammenhæng via et kaldenavn, når opslaget i datasættet ikke giver et resultat. Denne tilstand kræver ikke et egentligt fornavn og kan returnere name: null.

Garanterer forceToGenderize et køn?

Nej. Den tillader fortolkning af kaldenavne, men det endelige resultat kan stadig være ukendt. Bevar den native JSON-værdi null, og kontrollér result_status og reason.

Kontrollerer API'et profilen på sociale medier?

Dette endpoint fortolker den sendte værdi. Det henter ikke kontoens profil, opslag eller billeder for at finde ud af, hvem der ejer den.

Kan jeg også bruge forceToGenderize til navne eller e-mailadresser?

Ja. Det er valgfrit for input af typen name, email og username. Datasættet bruges først og derefter, hvis der ikke findes et resultat, AI med fortolkning af kaldenavne: 1 kredit for et resultat fra datasættet eller 2 i alt, hvis AI bruges.