GenderAPI.io V2: Namen, E-Mail-Adressen und Benutzernamen im Batch

Namen, E-Mail-Adressen und Benutzernamen im Batch

Parameter	Typ	Erforderlich	Standardwert	Beschreibung
`items`	`array<object>`	Ja	`—`	1 bis 50 Vorhersage-Einträge; höchstens 10 im IP-Testzugang. Die Ergebnisse behalten die Eingabereihenfolge bei.
`items[].type`	`string`	Ja	`—`	Eingabekategorie: name, email oder username.
`items[].value`	`string`	Ja	`—`	Erforderlich. 1–254 Zeichen; nicht leer und ohne Steuerzeichen. E-Mail-Werte müssen eine gültige E-Mail-Syntax haben.
`items[].country`	`string`	Nein	`—`	Optionaler ISO-3166-1-Alpha-2-Code in Großbuchstaben, zum Beispiel TR oder US. Eine länderspezifische Abfrage kann auf den globalen Datensatz zurückgreifen.
`items[].forceToGenderize`	`boolean`	Nein	`false`	Zuerst den Datensatz prüfen, bei fehlendem Ergebnis KI mit Spitznamen-Auswertung. Unterstützt für name, email und username.
`items[].options`	`object`	Nein	`—`	Objekt für die KI-Optionen der jeweiligen Eingabe.
`items[].options.ai_mode`	`string`	Nein	`off`	Erlaubte Werte: off, fallback, always. Bei forceToGenderize: true dieses Feld weglassen oder fallback verwenden.
`items[].id`	`string`	Nein	`—`	Optionale Kennung mit 1–64 Zeichen im POST-JSON. Wird neben dem jeweiligen Batch-Ergebnis zurückgegeben und muss innerhalb eines Batches eindeutig sein. Bei Einzelvorhersagen akzeptiert, aber nicht zurückgegeben. In GET-Queries nicht unterstützt.

GenderAPI.io V2 nimmt Namen, E-Mail-Adressen und Benutzernamen gemeinsam unter POST https://api.genderapi.io/api/v2/gender/batch entgegen. Senden Sie ein items-Array mit 1–50 Einträgen bei Zugang mit API-Schlüssel oder höchstens 10 im IP-Testzugang. Jeder Eintrag verwendet type und value und kann eigene Werte für country, forceToGenderize und options haben. IDs sind optional und müssen innerhalb des Batches eindeutig sein.

Die Ergebnisse behalten die Eingabereihenfolge bei und enthalten index, Ihre optionale id, charged_credits und genau eines der Felder data oder error. HTTP 200 kann Fehler einzelner Einträge enthalten; prüfen Sie daher jeden Eintrag. meta.summary meldet total, succeeded, identified, unknown und failed. Eine unbekannte Vorhersage ist ein erfolgreicher, kostenpflichtiger Eintrag.

Schlägt die Validierung oder Planung der Anfrage fehl, wird der Batch vor der Abbuchung abgelehnt. Schlagen alle ausgeführten Einträge fehl, liefert die API eine Problem-Antwort mit einem Status außerhalb von 2xx, einem data-Array und dem Legacy-Alias results. Fehlgeschlagene Einträge kosten nach bestätigter Erstattung nichts. Ist die Abrechnung unbestätigt, gehen Sie nicht davon aus, dass die Kosten der Einträge endgültig sind.

Wählen Sie eine Programmiersprache. Richten Sie Ihren API-Schlüssel ein, und führen Sie dann das Beispiel auf Ihrem Server aus.

Jede Vorhersageanfrage ist ein neuer kostenpflichtiger Vorgang, auch bei Wiederholungen. Diese Beispiele wiederholen Anfragen nicht automatisch. Prüfen Sie den Abrechnungsstatus, bevor Sie eine weitere Anfrage senden.

Vor der Ausführung: Zugang und Fehlerbehandlung

Führen Sie diese Beispiele auf Ihrem Server aus. Setzen Sie GENDERAPI_API_KEY in der Prozessumgebung auf Ihren vorhandenen API-Schlüssel. Prüfen Sie, ob meta.access.mode den Wert api_key hat: Ein nicht erkannter Schlüssel kann in den IP-Testzugang wechseln.

Bei HTTP-4xx- und -5xx-Antworten im JSON-Format bleibt der Fehlerinhalt erhalten, und das Beispiel endet mit einem Exit-Status ungleich null. Prüfen Sie code, action und meta.usage.billing_status, bevor Sie die Anfrage wiederholen. Prüfen Sie bei Batch-Antworten mit HTTP 200 außerdem data oder error jedes Eintrags.

Anleitung zu Fehlern und Wiederholungen →

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": "Johannes",
      "country": "DE"
    },
    {
      "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+ in einer POSIX-Shell. Im Terminal ausführen. Dokumentation der Laufzeitumgebung

// 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": "Johannes",
      "country": "DE"
    },
    {
      "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+; integriertes fetch. Als example.mjs speichern und node example.mjs ausführen. Dokumentation der Laufzeitumgebung

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\":\"Johannes\",\"country\":\"DE\"},{\"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+; Standardbibliothek. Als example.py speichern und python3 example.py ausführen. Dokumentation der Laufzeitumgebung

<?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":"Johannes","country":"DE"},{"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+ mit der cURL-Erweiterung. Als example.php speichern und php example.php ausführen. Dokumentation der Laufzeitumgebung

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\":\"Johannes\",\"country\":\"DE\"},{\"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+; Standard-HTTP-Client. Als GenderApiExample.java speichern und java GenderApiExample.java ausführen. Dokumentation der Laufzeitumgebung

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\":\"Johannes\",\"country\":\"DE\"},{\"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.
}

Konsolenanwendung mit .NET 8+. Als Program.cs in einem Konsolenprojekt verwenden und dann dotnet run ausführen. Dokumentation der Laufzeitumgebung

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\":\"Johannes\",\"country\":\"DE\"},{\"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+; Standardbibliothek. Als main.go speichern und go run main.go ausführen. Dokumentation der Laufzeitumgebung

Eine Batch-Antwort lesen

Dieses Beispiel kombiniert zwei echte Ergebnisse, die am 1. Oktober 2026 abgerufen wurden, einen Treffer im Datensatz und ein unbekanntes Ergebnis, mit einem veranschaulichenden Anbieterfehler. Es zeigt eine teilweise erfolgreiche Antwort mit HTTP 200, nicht die erwartete Ausgabe der obigen Batch-Anfrage. Die beiden erfolgreichen Einträge kosten je 1 Credit; für den fehlgeschlagenen Eintrag ist eine Abbuchung von null bestätigt.

{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "Johannes",
          "country": "DE"
        },
        "name": "johannes",
        "gender": "male",
        "country": "DE",
        "confidence": 0.9974193548387097,
        "confidence_kind": "observed_frequency",
        "sample_count": 775,
        "source": "dataset",
        "result_status": "identified",
        "reason": null,
        "country_source": "dataset",
        "match": {
          "name": "johannes",
          "method": "normalized",
          "scope": "country",
          "country": "DE"
        }
      }
    },
    {
      "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
    }
  }
}

Felder der Batch-Ergebnisse

Feld	Typ	Kann null sein	Beispiel	Beschreibung
`data`	`array<object>`	Nein	`[…]`	Geordnete Ergebnisse. Jeder Eintrag enthält eine Vorhersage oder einen Fehler; prüfen Sie alle Einträge.
`data[].index`	`integer`	Nein	`0`	Position im gesendeten items-Array, beginnend bei null.
`data[].id`	`string`	Nein	`"contact-1"`	Ihre Eingabekennung; nur vorhanden, wenn sie mitgesendet wurde.
`data[].charged_credits`	`integer`	Nein	`1`	Netto-Credits des Eintrags nach bestätigten Erstattungen. Nicht als endgültig behandeln, wenn die Gesamtabrechnung unbestätigt ist.
`data[].data`	`object`	Nein	`{…}`	Bei erfolgreichen Einträgen vorhanden, auch bei unbekannten Ergebnissen. Verwendet die Vorhersagefelder aus der Anleitung zu Antworten.
`data[].error`	`object`	Nein	`{…}`	Bei fehlgeschlagenen Einträgen anstelle von data vorhanden. Verwendet die Problem-Details-Felder aus der Anleitung zu Fehlern.

Felder der Batch-Zusammenfassung

Feld	Typ	Kann null sein	Beispiel	Beschreibung
`meta.summary.total`	`integer`	Nein	`3`	Gesamtzahl der Einträge im Batch.
`meta.summary.succeeded`	`integer`	Nein	`2`	Erfolgreiche Einträge einschließlich unbekannter Vorhersagen.
`meta.summary.identified`	`integer`	Nein	`1`	Erfolgreiche Einträge mit einem Geschlecht ungleich null.
`meta.summary.unknown`	`integer`	Nein	`1`	Erfolgreiche Einträge mit gender null; diese Ergebnisse sind kostenpflichtig.
`meta.summary.failed`	`integer`	Nein	`1`	Fehlgeschlagene Einträge. total = succeeded + failed; succeeded = identified + unknown.

Zugang, Abrechnung und Anfragemetadaten

Feld	Typ	Kann null sein	Beispiel	Beschreibung
`meta.request_id`	`string`	Nein	`"550e8400-e29b-41d4-a716-446655440000"`	Eindeutige Kennung dieses HTTP-Versuchs; auch in X-Request-ID enthalten.
`meta.duration_ms`	`integer`	Nein	`42`	Bearbeitungszeit der Anfrage in Millisekunden.
`meta.access.mode`	`string`	Nein	`"api_key"`	api_key, ip_trial oder unauthenticated. Prüfen Sie bei einem bezahlten Konto, ob api_key gemeldet wird.
`meta.access.reason`	`string`	Ja	`null`	Grund für den Wechsel in den Testzugang: api_key_missing, api_key_invalid oder api_key_not_found; sonst null.
`meta.usage.charged_credits`	`integer`	Ja	`1`	Netto abgebuchte Credits. 0 vor der Abbuchung oder nach einer bestätigten vollständigen Erstattung; null bei unbestätigter Abrechnung.
`meta.usage.remaining_credits`	`integer`	Ja	`99`	Guthaben beim Abschluss des Vorgangs. Kann negativ sein; null, wenn nicht verfügbar oder die Abrechnung unbestätigt ist.
`meta.usage.billing_status`	`string`	Nein	`"confirmed"`	not_charged, confirmed oder unconfirmed. Prüfen Sie dies, bevor Sie eine fehlgeschlagene Vorhersage wiederholen.
`meta.usage.resets_at`	`string`	Ja	`"2026-09-27T12:00:00.000Z"`	Zeitpunkt des Zurücksetzens des IP-Testzugangs in UTC (ISO 8601); null bei Konten mit API-Schlüssel oder wenn unbekannt.
`meta.usage.limit`	`integer`	Ja	`10`	Kontingent des IP-Testzugangs; null bei Konten mit API-Schlüssel.
`meta.usage.period_seconds`	`integer`	Ja	`86400`	Zeitfenster des IP-Testzugangs in Sekunden; null bei Konten mit API-Schlüssel.

Credits und Wiederholungen für Batches planen

Authentifizieren Sie sich mit Ihrem vorhandenen API-Schlüssel im Bearer-Header und senden Sie Content-Type: application/json. Jeder gesendete Batch ist ein neuer Vorgang. Wenn Sie nach einem Teilfehler wiederholen, senden Sie nach Prüfung der Abrechnung nur die fehlgeschlagenen Einträge; erneut gesendete erfolgreiche Einträge werden noch einmal berechnet.

Batch-Einträge haben KI standardmäßig auf off und kosten 1 Credit pro erfolgreichem Eintrag. Ein explizites fallback kostet ebenfalls insgesamt 1 Credit, einschließlich KI. always kostet 2 Credits. forceToGenderize kostet 1 Credit für ein im Datensatz aufgelöstes Ergebnis oder 2 Credits, wenn KI eingesetzt wird. Erfolgreiche unbekannte Ergebnisse werden berechnet. Ein positives Anfangsguthaben von 1 Credit genügt, um den Batch zu starten; die endgültige Abbuchung kann ein negatives Guthaben hinterlassen.

Eine Kontaktliste verarbeiten, ohne eine Zeile zu verlieren

Der Batch-Endpunkt verarbeitet reine Namenslisten, reine E-Mail-Listen und gemischte Eingaben. Teilen Sie einen Auftrag mit API-Schlüssel in Batches von höchstens 50 Einträgen auf; der IP-Testzugang erlaubt höchstens 10 pro Anfrage. Speichern Sie Ihre eigene Position im Auftrag und geben Sie jedem Eintrag eine innerhalb seines Batches eindeutige id. Der zurückgegebene index zählt ab null innerhalb des gesendeten Batches, nicht innerhalb der gesamten Kontaktliste.

Schritt	Was Sie speichern oder prüfen	Warum es wichtig ist
1. Jeden Batch vorbereiten	Behalten Sie Ihre Quellzeile und die id des Eintrags; legen Sie country und die KI-Optionen pro Eintrag fest.	Verlassen Sie sich nicht darauf, dass ein Name unter allen Kontakten eindeutig ist.
2. Die gesamte Antwort lesen	Speichern Sie meta.request_id und ordnen Sie jeden Eintrag in data[] über id oder index zu.	HTTP 200 kann sowohl erfolgreiche Vorhersagen als auch Fehler einzelner Einträge enthalten.
3. Erfolgreiche Ergebnisse speichern	Behalten Sie identifizierte und unbekannte Vorhersagen, einschließlich JSON-null-Werten und der Belegfelder.	Ein unbekanntes Ergebnis ist abgeschlossen und kostenpflichtig; es ist keine fehlgeschlagene Zeile für eine automatische Wiederholung.
4. Fehler und Credits abgleichen	Prüfen Sie jeden error und meta.usage.billing_status, bevor Sie über eine weitere Anfrage entscheiden.	Ist die Abrechnung bestätigt, wiederholen Sie nur fehlgeschlagene Einträge, deren Fehler eine Wiederholung rechtfertigt. Erfolgreiche Einträge würden erneut berechnet.
5. Unsichere Wiederholungen zurückstellen	Bewahren Sie die Anfrage-ID auf, wenn die Abrechnung unbestätigt ist oder ein Netzwerkfehler den Ausgang offenlässt.	Senden Sie nicht blind den gesamten Batch erneut; folgen Sie zuerst den Hinweisen zu Fehlern und Abrechnung.

Für jeden Kontakt einen Vorhersagemodus wählen

Diese ausführbare Anfrage verwendet drei verschiedene Regeln: nur Datensatz für einen vollständigen Namen, gewöhnlichen KI-Fallback für eine E-Mail-Adresse und KI-Fallback mit Spitznamen-Auswertung für einen Benutzernamen. Es handelt sich um Beispieleingaben, nicht um das Versprechen, dass alle drei Kontakte ein Geschlecht erhalten. Wählen Sie über dem Code eine Programmiersprache und setzen Sie GENDERAPI_API_KEY, bevor Sie das Beispiel ausführen.

Ohne forceToGenderize haben Batch-Einträge KI standardmäßig auf off, anders als Einzelabfragen. Setzen Sie fallback ausdrücklich, wenn Sie den gewöhnlichen KI-Fallback nutzen möchten. Sowohl off als auch der gewöhnliche fallback kosten 1 Credit pro erfolgreichem Eintrag; always überspringt den Datensatz und kostet 2. forceToGenderize kostet 1 Credit für ein im Datensatz aufgelöstes Ergebnis oder insgesamt 2, wenn KI eingesetzt wird. Auch erfolgreiche unbekannte Ergebnisse werden berechnet. Kombinieren Sie forceToGenderize nicht mit off oder always.