# Płeć z nazwy użytkownika o numerze API v2

> Przewiduj na podstawie nazw użytkowników i pseudonimów za pomocą GenderAPI v2. Dowiedz się o forceToGenderize, wyszukiwaniu pierwszego zestawu danych, polach odpowiedzi AI i taryfie 1 lub 2 kredytów.

Canonical HTML: https://www.genderapi.io/pl/docs/v2/gender-from-username

Last reviewed: 2026-09-25

## Przed wysłaniem zapytania

Wyślij JSON do POST https://api.genderapi.io/api/v2/gender. Użyj istniejącego klucza API w Authorization: Bearer YOUR_API_KEY i Content-Type: application/json. Każde żądanie jest przetwarzane niezależnie.

Wybierz język w przykładowym kodzie. Przed uruchomieniem ustaw GENDERAPI_API_KEY w środowisku procesowym. Brakujące lub nierozpoznane klucze mogą skorzystać z udostępnionej wersji próbnej IP, więc podczas integracji konta potwierdź, że meta.access.mode to api_key.

- [Uwierzytelnianie i dostęp próbny](https://www.genderapi.io/pl/docs/v2/authentication)
- [Wszystkie parametry żądania](https://www.genderapi.io/pl/docs/v2/request-parameters)

## Płeć na podstawie nazwy użytkownika lub pseudonimu

Użyj type: username jako nazwy użytkownika lub pseudonimu. Ustaw forceToGenderize na true, aby wywnioskować płeć na podstawie znaczenia aliasu, takiego jak prenses, nawet jeśli nie można wyodrębnić prawdziwego imienia. Najpierw sprawdzany jest zbiór danych. Podpowiedź pseudonimu może zwrócić płeć nawet wtedy, gdy name: null.

Uruchom te przykłady na swoim serwerze. Ustaw GENDERAPI_API_KEY w środowisku procesowym na istniejący klucz API. Potwierdź, że meta.access.mode to api_key: nierozpoznany klucz może wrócić do wersji próbnej IP.

Każde żądanie prognozy jest nową płatną operacją, włączając ponowne próby. W tych przykładach nie następuje automatycznie ponowna próba. Sprawdź status płatności przed wysłaniem kolejnej prośby.

Odpowiedzi HTTP 4xx i 5xx JSON zachowują treść błędu i zwracają niezerowy status wyjścia. Przed ponowną próbą sprawdź code, action i meta.usage.billing_status.

**cURL**

cURL 7.76+ w powłoce POSIX. Uruchom w swoim terminalu.

```bash
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
}'
```

**JavaScript / Node.js**

Node.js 22+; wbudowane pobieranie. Zapisz jako example.mjs i uruchom node example.mjs.

```javascript
// 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.
}
```

**Python**

Python 3.10+; biblioteka standardowa. Zapisz jako example.py i uruchom python3 example.py.

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

**PHP**

PHP 8+ z rozszerzeniem cURL. Zapisz jako example.php i uruchom php example.php.

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

**Java**

Java 17+; standardowy klient HTTP. Zapisz jako GenderApiExample.java i uruchom java GenderApiExample.java.

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

**C# / .NET**

Aplikacja konsolowa .NET 8+. Użyj jako Program.cs w projekcie konsolowym, a następnie uruchom dotnet run.

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

**Go**

Go 1.22+; biblioteka standardowa. Zapisz jako main.go i uruchom go run main.go.

```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)
    }
}
```

## Przykładowa odpowiedź

Ta syntetyczna odpowiedź ilustruje kształt JSON, a nie zmierzoną dokładność lub gwarantowany wynik na żywo. Pokazuje dostęp próbny IP; uwierzytelniona operacja zgłasza meta.access.mode: api_key i null pola przydziałów tylko w wersji próbnej. Odczytaj dane w celu wnioskowania i meta.usage w celu uzyskania wyniku rozliczeń operacji.

```json
{
  "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
    }
  }
}
```

- [Pola reakcji i pewność](https://www.genderapi.io/pl/docs/v2/responses)

## Przeczytaj prognozę pseudonimu

W tym przykładzie zastosowano forceToGenderize: true. Jeśli zbiór danych identyfikuje płeć, koszt wynosi 1 kredyt. W przeciwnym razie sztuczna inteligencja interpretuje pseudonim, a wypełniona prośba kosztuje w sumie 2 kredyty, nawet jeśli płeć pozostaje nieznana. Pomiń ai_mode lub ustaw go na fallback. Użycie off lub always razem z forceToGenderize zwraca HTTP 422.

W trybie pseudonimu dozwolone jest przewidywanie płci za pomocą name: null. Oznacza to, że nie wyodrębniono żadnego prawdziwego imienia, a nie, że analiza nie powiodła się. Jeśli AI zwróci płeć, zwracane są sample_count: null i confidence_kind: model_reported. Wynik nie jest skalibrowanym prawdopodobieństwem i nie weryfikuje tożsamości osobistej.

Bez forceToGenderize, wyszukiwanie pojedynczej nazwy użytkownika nadal domyślnie będzie oznaczać zwykłe AI fallback za 1 kredyt, ale wymaga użycia prawdziwego imienia. Użyj options.ai_mode: off do przetwarzania wyłącznie zestawu danych.

## Powiązane poradniki

- [Tryby AI i forceToGenderize](https://www.genderapi.io/pl/docs/v2/ai-options)
- [Przewidywania wsadowe](https://www.genderapi.io/pl/docs/v2/batch)
- [Kredyty i wykorzystanie](https://www.genderapi.io/pl/docs/v2/credits-and-usage)
- [Błędy i ponowne próby](https://www.genderapi.io/pl/docs/v2/errors-and-retries)