GenderAPI.io V2: partie imion, adresów e-mail i nazw użytkowników

Partie imion, adresów e-mail i nazw użytkowników

Parametr	Typ	Wymagany	Wartość domyślna	Opis
`items`	`array<object>`	Tak	`—`	Od 1 do 50 elementów do prognozy; maksymalnie 10 w próbie dla adresu IP. Wyniki zachowują kolejność wejściową.
`items[].type`	`string`	Tak	`—`	Kategoria danych wejściowych: name, email lub username.
`items[].value`	`string`	Tak	`—`	Wymagane. 1–254 znaki; wartość niepusta, bez znaków sterujących. Wartość typu email musi mieć poprawną składnię adresu e-mail.
`items[].country`	`string`	Nie	`—`	Opcjonalny kod ISO 3166-1 alpha-2 zapisany wielkimi literami, na przykład TR lub US. Wyszukiwanie dla konkretnego kraju może przejść na globalny zbiór danych.
`items[].forceToGenderize`	`boolean`	Nie	`false`	Najpierw sprawdza zbiór danych, a przy braku wyniku używa AI uwzględniającej pseudonimy. Obsługiwane dla name, email i username.
`items[].options`	`object`	Nie	`—`	Obiekt z opcjami AI dla danego wejścia.
`items[].options.ai_mode`	`string`	Nie	`off`	Dozwolone wartości: off, fallback, always. Przy forceToGenderize: true pomiń pole lub użyj fallback.
`items[].id`	`string`	Nie	`—`	Opcjonalny identyfikator o długości 1–64 znaków w treści JSON zapytania POST. Zwracany obok każdego wyniku partii; musi być unikalny w obrębie partii. Akceptowany, ale niezwracany w pojedynczych prognozach. Nieobsługiwany w zapytaniach GET.

GenderAPI.io V2 przyjmuje w jednej partii elementy z imionami, adresami e-mail i nazwami użytkowników pod adresem POST https://api.genderapi.io/api/v2/gender/batch. Wyślij tablicę items zawierającą od 1 do 50 elementów przy dostępie z kluczem API lub maksymalnie 10 w ramach próby dla adresu IP. Możesz wysłać same imiona, same adresy e-mail, same nazwy użytkowników albo połączyć wszystkie trzy typy. Każdy element używa type i value i może mieć własne country, forceToGenderize i options. Pola id są opcjonalne i muszą być unikalne w obrębie partii.

Wyniki zachowują kolejność wejściową i zawierają index, Twoje opcjonalne id, charged_credits oraz dokładnie jedno z pól data lub error. Odpowiedź HTTP 200 może zawierać niepowodzenia poszczególnych elementów, więc sprawdzaj każdy element. meta.summary podaje total, succeeded, identified, unknown i failed. Nieznana prognoza (unknown) to udany element, który podlega opłacie.

Błąd walidacji lub planowania zapytania powoduje odrzucenie partii przed pobraniem kredytów. Jeśli wszystkie wykonane elementy zakończą się niepowodzeniem, API zwraca odpowiedź Problem ze statusem spoza zakresu 2xx, z tablicą data i starszym aliasem results. Nieudane elementy nic nie kosztują po potwierdzonym zwrocie. Jeśli rozliczenie jest niepotwierdzone, nie zakładaj, że opłaty za elementy są ostateczne.

Wybierz język programowania. Skonfiguruj klucz API, następnie uruchom przykład na swoim serwerze.

Każde zapytanie o prognozę, łącznie z ponownymi próbami, jest nową płatną operacją. Te przykłady nie ponawiają zapytań automatycznie. Przed wysłaniem kolejnego zapytania sprawdź status rozliczenia.

Zanim uruchomisz: dostęp i obsługa błędów

Uruchamiaj te przykłady na swoim serwerze. Ustaw w środowisku procesu zmienną GENDERAPI_API_KEY na swój istniejący klucz API. Upewnij się, że meta.access.mode ma wartość api_key: nierozpoznany klucz może spowodować przejście na próbę dla adresu IP.

W przypadku odpowiedzi JSON z kodem HTTP 4xx i 5xx przykłady zachowują treść błędu i zwracają niezerowy kod wyjścia. Przed ponowną próbą sprawdź code, action i meta.usage.billing_status. W odpowiedziach dla partii z kodem HTTP 200 sprawdź też data lub error w każdym elemencie.

Przewodnik po błędach i ponawianiu zapytań →

curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Agnieszka",
      "country": "PL"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7.76+ w powłoce POSIX. Uruchom w terminalu. Dokumentacja środowiska uruchomieniowego

// 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 = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Agnieszka",
      "country": "PL"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

const response = await fetch("https://api.genderapi.io/api/v2/gender/batch", {
  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+; wbudowany fetch. Zapisz jako example.mjs i uruchom node example.mjs. Dokumentacja środowiska uruchomieniowego

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("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Agnieszka\",\"country\":\"PL\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"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/batch",
    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+; biblioteka standardowa. Zapisz jako example.py i uruchom python3 example.py. Dokumentacja środowiska uruchomieniowego

<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"contact-1","type":"name","value":"Agnieszka","country":"PL"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender/batch');
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+ z rozszerzeniem cURL. Zapisz jako example.php i uruchom php example.php. Dokumentacja środowiska uruchomieniowego

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 = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Agnieszka\",\"country\":\"PL\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"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/batch"))
            .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+; standardowy klient HTTP. Zapisz jako GenderApiExample.java i uruchom java GenderApiExample.java. Dokumentacja środowiska uruchomieniowego

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/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Agnieszka\",\"country\":\"PL\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"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.
}

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

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 := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Agnieszka\",\"country\":\"PL\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", 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+; biblioteka standardowa. Zapisz jako main.go i uruchom go run main.go. Dokumentacja środowiska uruchomieniowego

Odczytaj odpowiedź dla partii

Ten przykład łączy dwa prawdziwe wyniki pobrane 1 października 2026 r., dopasowanie w zbiorze danych i wynik nieznany, z poglądowym błędem dostawcy. Pokazuje odpowiedź HTTP 200 z częściowym powodzeniem, a nie oczekiwany wynik powyższego zapytania zbiorczego. Dwa udane elementy kosztują po 1 kredycie; za nieudany element potwierdzono zerową opłatę.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Agnieszka",
          "country": "PL"
        },
        "name": "agnieszka",
        "gender": "female",
        "country": "PL",
        "confidence": 0.9976498237367802,
        "confidence_kind": "observed_frequency",
        "sample_count": 851,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "agnieszka",
          "method": "normalized",
          "scope": "country",
          "country": "PL"
        }
      }
    },
    {
      "index": 1,
      "id": "missing",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "zzzxxyy",
          "country": null
        },
        "name": null,
        "gender": null,
        "country": null,
        "confidence": null,
        "confidence_kind": null,
        "sample_count": null,
        "source": "none",
        "result_status": "unknown",
        "reason": "not_found",
        "country_source": null,
        "match": {
          "name": null,
          "method": null,
          "scope": null,
          "country": null
        }
      }
    },
    {
      "index": 2,
      "id": "failed",
      "charged_credits": 0,
      "error": {
        "type": "urn:genderapi:problem:ai_upstream_error",
        "title": "ai upstream error",
        "status": 502,
        "detail": "The AI provider could not complete the request.",
        "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
        "code": "ai_upstream_error",
        "request_id": "11111111-1111-4111-8111-111111111111",
        "documentation": "https://api.genderapi.io/api/v2/errors",
        "action": "inspect_billing_before_retry"
      }
    }
  ],
  "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": 6,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    },
    "summary": {
      "total": 3,
      "succeeded": 2,
      "identified": 1,
      "unknown": 1,
      "failed": 1
    }
  }
}

Pola wyników partii

Pole	Typ	Dopuszcza null	Przykład	Opis
`data`	`array<object>`	Nie	`[…]`	Uporządkowane wyniki. Każdy element zawiera prognozę lub błąd; sprawdź każdy element.
`data[].index`	`integer`	Nie	`0`	Pozycja w przesłanej tablicy items, liczona od zera.
`data[].id`	`string`	Nie	`"contact-1"`	Twój identyfikator wejścia; obecny tylko wtedy, gdy go podano.
`data[].charged_credits`	`integer`	Nie	`1`	Opłata netto za element po potwierdzonych zwrotach. Nie uznawaj jej za ostateczną, jeśli rozliczenie całej partii nie jest potwierdzone.
`data[].data`	`object`	Nie	`{…}`	Obecne dla udanego elementu, także z wynikiem nieznanym. Zawiera pola prognozy opisane w przewodniku po odpowiedziach.
`data[].error`	`object`	Nie	`{…}`	Obecne zamiast data dla nieudanego elementu. Zawiera pola Problem Details opisane w przewodniku po błędach.

Pola podsumowania partii

Pole	Typ	Dopuszcza null	Przykład	Opis
`meta.summary.total`	`integer`	Nie	`3`	Łączna liczba elementów w partii.
`meta.summary.succeeded`	`integer`	Nie	`2`	Udane elementy, łącznie z nieznanymi prognozami.
`meta.summary.identified`	`integer`	Nie	`1`	Udane elementy z płcią inną niż null.
`meta.summary.unknown`	`integer`	Nie	`1`	Udane elementy z płcią null; te wyniki podlegają opłacie.
`meta.summary.failed`	`integer`	Nie	`1`	Nieudane elementy. total = succeeded + failed; succeeded = identified + unknown.

Metadane dostępu, rozliczenia i zapytania

Pole	Typ	Dopuszcza null	Przykład	Opis
`meta.request_id`	`string`	Nie	`"550e8400-e29b-41d4-a716-446655440000"`	Unikalny identyfikator tej próby HTTP; wysyłany także w X-Request-ID.
`meta.duration_ms`	`integer`	Nie	`42`	Czas przetwarzania zapytania w milisekundach.
`meta.access.mode`	`string`	Nie	`"api_key"`	api_key, ip_trial lub unauthenticated. Korzystając z płatnego konta, sprawdź api_key.
`meta.access.reason`	`string`	Tak	`null`	Powód przejścia na próbę: api_key_missing, api_key_invalid lub api_key_not_found; w pozostałych przypadkach null.
`meta.usage.charged_credits`	`integer`	Tak	`1`	Liczba pobranych kredytów netto. Zero przed pobraniem lub po potwierdzonym pełnym zwrocie; null, gdy rozliczenie jest niepotwierdzone.
`meta.usage.remaining_credits`	`integer`	Tak	`99`	Saldo po zakończeniu operacji. Może być ujemne; null, gdy saldo jest niedostępne lub rozliczenie jest niepotwierdzone.
`meta.usage.billing_status`	`string`	Nie	`"confirmed"`	not_charged, confirmed lub unconfirmed. Sprawdź to pole przed ponowieniem nieudanej prognozy.
`meta.usage.resets_at`	`string`	Tak	`"2026-09-27T12:00:00.000Z"`	Czas odnowienia próby dla adresu IP w UTC (ISO 8601); null dla kont z kluczem API lub gdy nie jest znany.
`meta.usage.limit`	`integer`	Tak	`10`	Limit kredytów próby dla adresu IP; null dla kont z kluczem API.
`meta.usage.period_seconds`	`integer`	Tak	`86400`	Okres próby dla adresu IP w sekundach; null dla kont z kluczem API.

Zaplanuj kredyty i ponowne próby dla partii

Uwierzytelnij się istniejącym kluczem API w nagłówku Bearer i wyślij Content-Type: application/json. Każda przesłana partia to nowa operacja. Ponawiając partię z częściowym niepowodzeniem, najpierw sprawdź rozliczenie, a potem prześlij tylko nieudane elementy; ponowne wysłanie udanych elementów spowoduje ponowne naliczenie opłaty.

Elementy partii domyślnie mają AI wyłączoną (off) i kosztują 1 kredyt za każdy udany element. Jawnie ustawiony fallback również kosztuje łącznie 1 kredyt, wraz z AI. always kosztuje 2 kredyty. forceToGenderize kosztuje 1 kredyt za wynik rozstrzygnięty w zbiorze danych lub 2, jeśli użyto AI. Udane wyniki nieznane są płatne. Do rozpoczęcia partii wystarczy dodatnie saldo początkowe, choćby 1 kredyt; końcowa opłata może sprawić, że saldo będzie ujemne.

Przetwarzanie listy kontaktów bez gubienia żadnego wiersza

Endpoint zapytań zbiorczych obsługuje listy samych imion, listy samych adresów e-mail oraz dane mieszane. Dziel zadanie z kluczem API na partie po maksymalnie 50 elementów; próba dla adresu IP dopuszcza najwyżej 10 elementów w zapytaniu. Zapisuj własną pozycję w zadaniu i nadaj każdemu elementowi id unikalne w obrębie partii. Zwracany index liczony jest od zera w obrębie wysłanej partii, a nie całej listy kontaktów.

Krok	Co zapisać lub sprawdzić	Dlaczego to ważne
1. Przygotuj każdą partię	Zachowaj wiersz źródłowy i id elementu; ustaw country i opcje AI dla każdego elementu.	Nie zakładaj, że imię jest unikalne wśród kontaktów.
2. Odczytaj całą odpowiedź	Zapisz meta.request_id i przypisz każdy wpis data[] na podstawie id lub index.	HTTP 200 może zawierać zarówno udane prognozy, jak i błędy poszczególnych elementów.
3. Zapisz udane wyniki	Zachowaj prognozy identified i unknown, łącznie z wartościami null w JSON i polami z informacjami o dopasowaniu.	Wynik unknown jest zakończonym, płatnym wynikiem, a nie nieudanym wierszem do automatycznego ponowienia.
4. Uzgodnij błędy i kredyty	Sprawdź każdy error i meta.usage.billing_status, zanim zdecydujesz o kolejnym zapytaniu.	Gdy rozliczenie jest potwierdzone, ponawiaj tylko nieudane elementy, których błąd uzasadnia ponowną próbę. Za udane elementy kredyty zostałyby naliczone ponownie.
5. Wstrzymaj niepewne ponowienia	Zachowaj identyfikator zapytania, gdy rozliczenie ma status unconfirmed lub awaria sieci pozostawia wynik nieznanym.	Nie wysyłaj ponownie całej partii na ślepo; najpierw postępuj zgodnie ze wskazówkami dotyczącymi błędów i rozliczeń.

Wybierz tryb inferencji dla każdego kontaktu

To gotowe do uruchomienia zapytanie stosuje trzy różne reguły: tylko zbiór danych dla imienia i nazwiska, standardowe przejście na AI dla adresu e-mail oraz przejście uwzględniające pseudonimy dla nazwy użytkownika. To przykładowe dane wejściowe, a nie obietnica, że wszystkie trzy kontakty otrzymają płeć. Wybierz język programowania nad kodem i ustaw GENDERAPI_API_KEY przed uruchomieniem.

Bez forceToGenderize elementy partii domyślnie mają AI wyłączoną (off), inaczej niż pojedyncze wyszukiwania. Aby włączyć standardowe przejście na AI, ustaw jawnie fallback. Zarówno off, jak i standardowy fallback kosztują 1 kredyt za każdy udany element; always pomija zbiór danych i kosztuje 2. forceToGenderize kosztuje 1 kredyt za wynik rozstrzygnięty w zbiorze danych albo łącznie 2, jeśli użyta zostanie AI. Za udane wyniki unknown kredyty również są naliczane. Nie łącz forceToGenderize z off ani always.