GenderAPI.io V2 mit Python verwenden

Ein serverseitiges Python-Projekt vorbereiten

Diese Anleitung ruft den Endpunkt von GenderAPI.io V2 https://api.genderapi.io/api/v2/gender mit dem API-Schlüssel im Bearer-Header auf. Verwenden Sie Python 3.10 oder neuer und laden Sie genderapi_v2.py in Ihr Projekt herunter. Das Beispiel nutzt urllib.request und json aus der Python-Standardbibliothek; es benötigt kein pip-Paket.

Setzen Sie GENDERAPI_API_KEY in der Umgebung Ihres Servers. YOUR_API_KEY im folgenden Beispiel ist kein gültiger Schlüssel. Legen Sie echte Zugangsdaten nicht in versionierten Dateien, gemeinsam genutzten Notebooks oder clientseitigen Anwendungen ab. Das Importieren des Moduls oder sein Start ohne Demo-Option sendet keine Anfrage.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• genderapi_v2.py herunterladen →
• Schlüssel mit dem kostenlosen Nutzungsendpunkt prüfen →

Eine ausdrückliche Anfrage nur an den Datensatz senden

Speichern Sie den folgenden Code als single.py neben der heruntergeladenen Datei und führen Sie dann python3 single.py aus. Das Hilfsmodul sendet im JSON type: name, value: Alice und options.ai_mode: off. Die Vorhersage lesen Sie aus data, die Angaben zur Anfrage und zur Abrechnung aus meta.

Ein erfolgreicher Aufruf kostet 1 Credit, auch bei einem unbekannten Ergebnis; der Beispielname garantiert keine Vorhersage. make_item nimmt name, email oder username an und verlangt einen ausdrücklichen KI-Modus. Fügen Sie country nur hinzu, wenn Sie über passenden Kontext verfügen.

Vor dem Senden verlangt das Hilfsmodul einen hexadezimalen API-Schlüssel mit 24 Zeichen. Damit wird das Format des Schlüssels geprüft, nicht seine Existenz. Außerdem lehnt es erfolgreiche Antworten aus dem IP-Testzugang als Abweichung des Zugangsmodus ab; diese Prüfung erfolgt nach Erhalt der Antwort und kann einen bereits verbrauchten Test-Credit nicht rückgängig machen.

from genderapi_v2 import GenderAPIError, make_item, predict

try:
    response = predict(make_item("name", "Alice", ai_mode="off"))
except GenderAPIError as error:
    # Record a reference; do not log the whole error response.
    print("Request failed:", error.request_id)
    raise SystemExit(1)
else:
    result = response["data"]
    print(result["result_status"], result["gender"])
    print(result["confidence"], result["confidence_kind"])
    print(response["meta"]["usage"])

• Alle Felder von Einzelanfragen →

Ergebnis und Belege gemeinsam aufbewahren

Eine abgeleitete Zuordnung ist nicht das Geschlecht, das eine Person selbst angibt. Bewahren Sie die ursprüngliche Eingabe, die zurückgegebenen Belege und alle Angaben der Person selbst getrennt auf. Ein unbekanntes Ergebnis ist ein gültiges Ergebnis; es sollte in Ihrer Anwendung nicht zu einer geratenen Kategorie werden.

• Antwortfelder und unbekannte Ergebnisse →
• Genauigkeit und Konfidenz erklärt →
• Datenquellen und das datierte Datenbankprofil →

Einen gemischten Batch verarbeiten und die ID jeder Zeile beibehalten

GenderAPI.io V2 verarbeitet gemischte Batches über POST https://api.genderapi.io/api/v2/gender/batch: bis zu 50 Einträge mit Kontoschlüssel oder 10 im IP-Testzugang. Diese Beispiele erfordern einen Kontoschlüssel. Geben Sie jedem Eintrag eine stabile, eindeutige id und einen ausdrücklichen KI-Modus. Ein Batch kann Namen, E-Mail-Adressen und Benutzernamen kombinieren, und jeder Eintrag kann einen optionalen Kontext country haben.

Lesen Sie jeden Eintrag in data sowie die Zusammenfassung meta.summary. Eine Antwort mit HTTP 200 kann Fehler einzelner Einträge enthalten; ein Batch, in dem alle Einträge fehlgeschlagen sind, kann eine Problem-Antwort der obersten Ebene mit den Ergebnissen liefern. Erfolgreiche unbekannte Ergebnisse werden in succeeded gezählt. Mit index und id ordnen Sie jedes Ergebnis der richtigen Quellzeile zu.

Teilen Sie die Eingaben bei großen Aufträgen in Gruppen von höchstens 50 Einträgen und senden Sie diese anfangs nacheinander. Speichern Sie jede Antwort und ihre Nutzung, bevor Sie zur nächsten Gruppe übergehen. Halten Sie bei einem Transportfehler, einem Fehler beim Kontozugang oder einer unbestätigten Abrechnung an und klären Sie den Stand der aktuellen Gruppe. Führen Sie paralleles Senden erst ein, nachdem Sie die Grenzen Ihres Kontos geprüft haben; die maximale Batch-Größe garantiert keinen Durchsatz.

from genderapi_v2 import GenderAPIError, make_item, predict_batch

items = [
    make_item("name", "Alice", ai_mode="off", item_id="row-1"),
    make_item("email", "alex@example.com", ai_mode="off", item_id="row-2"),
    make_item("username", "sample_handle", ai_mode="off", item_id="row-3"),
]
try:
    response = predict_batch(items)
except GenderAPIError as error:
    # Retained error.response can include batch results and billing.
    print("Batch needs review:", error.request_id)
    raise SystemExit(1)
else:
    for item in response["data"]:
        if "error" in item:
            print(item["id"], "failed", item["error"]["code"])
        else:
            result = item["data"]
            print(item["id"], result["result_status"], result["gender"])
    print(response["meta"]["summary"])
    print(response["meta"]["usage"])
    if response["meta"]["summary"]["failed"]:
        raise SystemExit(2)

• Batch-Eingaben, Ergebnisse und Abrechnung →

Festlegen, wann KI eingesetzt wird

forceToGenderize ist für Namen, E-Mail-Adressen und Benutzernamen optional. Ist es aktiviert, lassen Sie ai_mode weg oder verwenden Sie fallback; off und always sind damit unvereinbar und liefern 422. Ein positives Anfangsguthaben genügt, um eine Anfrage zu starten, auch wenn die endgültige Abbuchung das Guthaben unter null senkt.

Der Spitznamenmodus kann ein Geschlecht zusammen mit name: null zurückgeben. Er kann auch ein unbekanntes Ergebnis liefern. Weder der gewöhnliche KI-Fallback noch die Spitznamen-Auswertung garantieren eine richtige Antwort oder einen Wert ungleich null.

Das Python-Hilfsmodul verlangt immer ai_mode. Für die Spitznamen-Auswertung verwenden Sie make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Das Modul wandelt force_to_genderize in das JSON-Feld forceToGenderize um.

• KI-Optionen und Spitznamen-Auswertung →
• Credits und Nutzung →

Entscheiden, was nach einem Fehler geschieht

Die Beispiele senden jeden Vorgang nur einmal. Sie wiederholen ihn nie automatisch: Ein erneutes Senden ist ein neuer, kostenpflichtiger Vorgang. Eine Zeitüberschreitung oder ein Verbindungsfehler bedeutet, dass der Client keine vollständige Antwort erhalten hat; das belegt weder, dass der Server die Verarbeitung abgebrochen hat, noch dass keine Credits abgebucht wurden.

Speichern Sie die zurückgegebene request_id und den Abrechnungsstatus zusammen mit dem Datensatz Ihres Auftrags. Das Fehlerobjekt bewahrt die Antwort für eine kontrollierte Analyse auf, kann aber die ursprüngliche Eingabe enthalten: Schreiben Sie weder das gesamte Objekt noch die Antwort noch den API-Schlüssel in gewöhnliche Logs.

• Problem Details und Entscheidungen zu Wiederholungen →
• Credits und Bestätigung der Abrechnung →

Das Netzwerkverhalten dieses Beispiels kennen

Die Zeitüberschreitung von 10 Sekunden in urllib gilt für blockierende Socket-Operationen; sie ist keine garantierte Grenze für die gesamte Dauer der Anfrage. Das Beispiel deaktiviert HTTP-Weiterleitungen, analysiert erfolgreiche JSON-Antworten und bewahrt HTTP-Problem-Antworten auf. Es wiederholt Anfragen nie automatisch.

Lokale Tests verwenden simulierte Transportantworten für Erfolge, unbekannte Ergebnisse, teilweise erfolgreiche Batches, Kontozugang und Fehler. Sie prüfen die Steuerlogik des Beispiels; sie messen weder die Verfügbarkeit der API im Produktivbetrieb noch die Genauigkeit der Inferenz noch Latenzen. Jeder ausdrückliche Demo-Befehl unten sendet eine eigene, kostenpflichtige Anfrage.

python3 genderapi_v2.py --demo single
# Run separately to submit another billable sample batch:
python3 genderapi_v2.py --demo batch

• Python-Dokumentation zu urllib.request →
• Python-Dokumentation zu HTTPError →

Häufig gestellte Fragen