API DOKUMENTATIO V2

Sukupuoli käyttäjänimestä API v2:lla

Ennusta käyttäjänimien ja lempinimien perusteella GenderAPI v2:lla. Opi forceToGenderize, dataset-first-haku, tekoälyn vastauskentät ja 1 tai 2 pisteen tariffi.

Ennen pyynnön lähettämistä

Lähetä JSON numeroon POST https://api.genderapi.io/api/v2/gender. Käytä olemassa olevaa API-avainta malleissa Authorization: Bearer YOUR_API_KEY ja Content-Type: application/json. Jokainen pyyntö käsitellään itsenäisesti.

Valitse kieli koodiesimerkistä. Aseta GENDERAPI_API_KEY prosessiympäristöön ennen sen suorittamista. Puuttuvat tai tunnistamattomat avaimet voivat käyttää jaettua IP-kokeilua, joten varmista, että meta.access.mode on api_key, kun integroit tiliä.

Sukupuoli käyttäjänimestä tai lempinimestä

Käytä type: username käyttäjänimenä tai lempinimenä. Aseta forceToGenderize arvoksi true, jos haluat päätellä sukupuolen aliaksen, kuten prenses, merkityksestä, vaikka oikeaa etunimeä ei voida poimia. Tietojoukko tarkistetaan ensin. Lempinimen ennuste voi palauttaa sukupuolen, vaikka name: null.

Valitse ohjelmointikieli. Määritä API-avain, suorita sitten esimerkki palvelimellasi.

Jokainen ennustepyyntö on uusi laskutettava toiminto, mukaan lukien uudelleenyritykset. Nämä esimerkit eivät yritä automaattisesti uudelleen. Tarkista laskutuksen tila ennen uuden pyynnön lähettämistä.

Ennen kuin suoritat: pääsy ja virheiden käsittely

Suorita nämä esimerkit palvelimellasi. Aseta GENDERAPI_API_KEY prosessiympäristössä olemassa olevaan API-avaimeen. Varmista, että meta.access.mode on api_key: tunnistamaton avain voi pudota takaisin IP-kokeeseen.

HTTP 4xx- ja 5xx JSON -vastaukset säilyttävät virheen rungon ja palauttavat nollasta poikkeavan poistumistilan. Tarkista code, action ja meta.usage.billing_status ennen kuin yrität uudelleen.

Virhe- ja uudelleenyritysopas →
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+ POSIX-kuoressa. Suorita terminaalissasi. Ajonaikainen dokumentaatio

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+; sisäänrakennettu haku. Tallenna nimellä example.mjs ja suorita node example.mjs. Ajonaikainen dokumentaatio

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+; tavallinen kirjasto. Tallenna nimellä example.py ja suorita python3 example.py. Ajonaikainen dokumentaatio

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+ cURL-laajennuksella. Tallenna nimellä example.php ja suorita php example.php. Ajonaikainen dokumentaatio

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+; tavallinen HTTP-asiakas. Tallenna nimellä GenderApiExample.java ja suorita java GenderApiExample.java. Ajonaikainen dokumentaatio

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+ -konsolisovellus. Käytä konsoliprojektissa nimellä Program.cs ja suorita sitten dotnet run. Ajonaikainen dokumentaatio

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+; tavallinen kirjasto. Tallenna nimellä main.go ja suorita go run main.go. Ajonaikainen dokumentaatio

Esimerkkivastauksesta

Tämä synteettinen vaste kuvaa JSON-muotoa, ei mitattua tarkkuutta tai taattua live-tulosta. Se näyttää IP-kokeilukäytön; todennettu toiminta raportoi meta.access.mode: api_key ja null vain kokeiluversion kiintiökentät. Lue tiedot päättelyä varten ja meta.usage saadaksesi toiminnan laskutustuloksen.

Havainnollinen JSON-vastaus
{
  "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
    }
  }
}

Lue lempinimiennustus

Esimerkki käyttää asetusta forceToGenderize: true. Jos tietoaineisto tunnistaa sukupuolen, hinta on 1 krediitti. Muussa tapauksessa tekoäly tulkitsee lempinimen ja onnistuneesti käsitelty pyyntö maksaa yhteensä 2 krediittiä, vaikka sukupuoli jäisi tuntemattomaksi. Jätä ai_mode pois tai valitse fallback. off tai always yhdessä forceToGenderize-asetuksen kanssa palauttaa HTTP 422 -virheen.

Lempinimitilassa sukupuolen ennustaminen name: null:lla on sallittu. Se tarkoittaa, että oikeaa etunimeä ei purettu, ei sitä, että jäsentäminen epäonnistui. Jos tekoäly palauttaa sukupuolen, palautetaan sample_count: null ja confidence_kind: model_reported. Pisteet ei ole kalibroitu todennäköisyys, eikä se vahvista henkilöllisyyttä.

Ilman forceToGenderize:tä yksittäisen käyttäjänimen haun oletusarvo on tavallinen tekoäly fallback 1 pisteen kokonaismäärällä, mutta se vaatii käyttökelpoisen oikean etunimen. Käytä options.ai_mode: off vain tietojoukon käsittelyyn.

Aiheeseen liittyviä oppaita