API DOCUMENTATIE V2

Geslacht van een gebruikersnaam met API v2

Voorspel op basis van gebruikersnamen en bijnamen met GenderAPI v2. Leer forceToGenderize, dataset-first lookup, AI-antwoordvelden en het tarief met 1 of 2 credits.

Voordat u het verzoek verzendt

Verzend JSON naar POST https://api.genderapi.io/api/v2/gender. Gebruik uw bestaande API-sleutel in Authorization: Bearer YOUR_API_KEY en Content-Type: application/json. Elke aanvraag wordt onafhankelijk verwerkt.

Kies uw taal in het codevoorbeeld. Stel GENDERAPI_API_KEY in de procesomgeving in voordat u het uitvoert. Ontbrekende of niet-herkende sleutels kunnen de gedeelde IP-proefversie gebruiken, dus bevestig dat meta.access.mode api_key is wanneer u een account integreert.

Geslacht van een gebruikersnaam of bijnaam

Gebruik type: username voor een gebruikersnaam of bijnaam. Stel forceToGenderize in op true om het geslacht af te leiden uit de betekenis van een alias zoals prenses, zelfs als er geen echte voornaam kan worden afgeleid. De dataset wordt eerst gecontroleerd. Een bijnaamvoorspelling kan een geslacht retourneren, zelfs als name: null.

Kies een programmeertaal. Stel uw API-sleutel in, voer vervolgens het voorbeeld uit op uw server.

Elk voorspellingsverzoek is een nieuwe factureerbare bewerking, inclusief nieuwe pogingen. Deze voorbeelden proberen niet automatisch opnieuw. Controleer de factureringsstatus voordat u een nieuw verzoek verzendt.

Voordat u begint: toegang en foutafhandeling

Voer deze voorbeelden uit op uw server. Stel GENDERAPI_API_KEY in de procesomgeving in op uw bestaande API-sleutel. Bevestig dat meta.access.mode api_key is: een niet-herkende sleutel kan terugvallen op de IP-proefversie.

HTTP 4xx en 5xx JSON-antwoorden behouden de fouttekst en retourneren een afsluitstatus die niet nul is. Controleer code, action en meta.usage.billing_status voordat u het opnieuw probeert.

Gids voor fouten en opnieuw proberen →
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+ in een POSIX-shell. Voer uw terminal in. Runtime-documentatie

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+; ingebouwde ophaalfunctie. Opslaan als example.mjs en voer node example.mjs uit. Runtime-documentatie

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+; standaard bibliotheek. Opslaan als example.py en voer python3 example.py uit. Runtime-documentatie

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+ met de cURL-extensie. Opslaan als example.php en voer php example.php uit. Runtime-documentatie

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+; standaard HTTP-client. Opslaan als GenderApiExample.java en voer java GenderApiExample.java uit. Runtime-documentatie

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

.NET 8+ console-applicatie. Gebruik als Program.cs in een consoleproject en voer vervolgens dotnet run uit. Runtime-documentatie

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+; standaard bibliotheek. Opslaan als main.go en voer go run main.go uit. Runtime-documentatie

Voorbeeld antwoord

Deze synthetische respons illustreert de JSON-vorm, niet de gemeten nauwkeurigheid of een gegarandeerd live resultaat. Het toont IP-proeftoegang; een geverifieerde bewerking rapporteert meta.access.mode: api_key en null alleen proefquotumvelden. Lees gegevens voor de gevolgtrekking en meta.usage voor het factureringsresultaat van de bewerking.

Illustratieve JSON-reactie
{
  "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
    }
  }
}

Lees een voorspelling van een bijnaam

In dit voorbeeld wordt forceToGenderize: true gebruikt. Als de dataset een geslacht identificeert, bedragen de kosten 1 credit. Anders interpreteert AI de alias en kost een ingevuld verzoek in totaal 2 credits, zelfs als het geslacht onbekend blijft. Laat ai_mode weg of stel dit in op fallback. Als u off of always samen met forceToGenderize gebruikt, retourneert HTTP 422.

In de bijnaammodus is een geslachtsvoorspelling met name: null toegestaan. Het betekent dat er geen echte voornaam is geëxtraheerd, en niet dat het parseren is mislukt. Als AI een geslacht retourneert, worden sample_count: null en confidence_kind: model_reported geretourneerd. De score is geen gekalibreerde waarschijnlijkheid en verifieert de persoonlijke identiteit niet.

Zonder forceToGenderize wordt bij het opzoeken van een enkele gebruikersnaam nog steeds standaard de gewone AI fallback gebruikt voor een totaal van 1 credit, maar hiervoor is een bruikbare echte voornaam vereist. Gebruik options.ai_mode: off voor verwerking van alleen gegevenssets.

Gerelateerde handleidingen