Usare GenderAPI.io V2 con Python

Preparare un progetto Python lato server

Questa guida chiama l'endpoint di GenderAPI.io V2 https://api.genderapi.io/api/v2/gender con la chiave API nell'intestazione Bearer. Usa Python 3.10 o versioni successive e scarica genderapi_v2.py nel tuo progetto. L'esempio usa urllib.request e json della libreria standard di Python; non richiede alcun pacchetto pip.

Imposta GENDERAPI_API_KEY nell'ambiente del server. YOUR_API_KEY nell'esempio seguente non è una chiave valida. Non inserire credenziali reali in file sotto controllo di versione, notebook condivisi o applicazioni lato client. Importare il modulo o eseguirlo senza opzioni demo non invia alcuna richiesta.

python3 --version
export GENDERAPI_API_KEY="YOUR_API_KEY"

• Scarica genderapi_v2.py →
• Verificare la chiave con l'endpoint gratuito di utilizzo →

Inviare una richiesta esplicita basata solo sul set di dati

Salva il codice seguente come single.py accanto al file scaricato ed esegui python3 single.py. Il modulo di supporto invia type: name, value: Alice e options.ai_mode: off in JSON. La previsione si legge in data, mentre le informazioni sulla richiesta e sull'addebito si trovano in meta.

Una chiamata riuscita costa 1 credito, anche in caso di risultato sconosciuto; il nome di esempio non garantisce una previsione. make_item accetta name, email o username e richiede una modalità IA esplicita. Aggiungi country solo quando disponi di un contesto pertinente.

Prima di inviare qualsiasi cosa, il modulo di supporto richiede una chiave API esadecimale di 24 caratteri. Questo verifica il formato della chiave, non la sua esistenza. Il modulo rifiuta inoltre le risposte riuscite della prova IP come modalità di accesso inattesa; il controllo avviene dopo la ricezione della risposta e non può annullare un credito di prova già consumato.

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"])

• Tutti i campi delle richieste singole →

Salvare il risultato insieme alle evidenze

Un'associazione dedotta non è il genere dichiarato da una persona. Salva separatamente l'input originale, le evidenze restituite e ciò che la persona ha dichiarato. Un risultato sconosciuto è un risultato valido e non dovrebbe diventare una categoria indovinata nella tua applicazione.

• Campi della risposta e risultati sconosciuti →
• Accuratezza e confidenza spiegate →
• Fonti dei dati e profilo datato del database →

Elaborare un batch misto e conservare l'id di ogni riga

GenderAPI.io V2 elabora batch misti tramite POST https://api.genderapi.io/api/v2/gender/batch: fino a 50 elementi con una chiave dell'account o 10 con la prova IP. Questi esempi richiedono una chiave dell'account. Assegna a ogni elemento un id stabile e univoco e una modalità IA esplicita. Un batch può combinare nomi, indirizzi email e nomi utente, e ogni elemento può avere un contesto country facoltativo.

Leggi ogni elemento in data e il riepilogo in meta.summary. Una risposta HTTP 200 può contenere errori di singoli elementi; un batch in cui tutti gli elementi non sono riusciti può restituire una risposta Problem di primo livello con i risultati. I risultati sconosciuti riusciti vengono contati in succeeded. Con index e id colleghi ogni risultato alla riga di origine corretta.

Per i lavori più grandi suddividi l'input in gruppi di al massimo 50 elementi e inviali inizialmente uno alla volta. Salva ogni risposta e il relativo utilizzo prima di passare al gruppo successivo. Fermati in caso di errore di trasporto, di errore di accesso all'account o di addebito non confermato e chiarisci la situazione del gruppo corrente. Introduci invii paralleli solo dopo aver verificato i limiti del tuo account; la dimensione massima del batch non garantisce una determinata capacità di elaborazione.

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)

• Input, risultati e addebito dei batch →

Decidere quando usare l'IA

forceToGenderize è facoltativo per nomi, indirizzi email e nomi utente. Quando è attivo, ometti ai_mode o usa fallback; off e always non possono essere combinati con questa opzione e restituiscono 422. Un saldo iniziale positivo basta per avviare una richiesta, anche se l'addebito finale rende il saldo negativo.

La modalità nickname può restituire un genere insieme a name: null. Può anche dare un risultato sconosciuto. Né il normale fallback IA né l'interpretazione dei nickname garantiscono una risposta corretta o un valore diverso da null.

Il modulo di supporto per Python richiede sempre ai_mode. Per l'interpretazione dei nickname usa make_item('username', 'prenses', ai_mode='fallback', force_to_genderize=True). Il modulo converte force_to_genderize nel campo JSON forceToGenderize.

• Opzioni IA e interpretazione dei nickname →
• Crediti e utilizzo →

Decidere che cosa fare dopo un errore

Gli esempi inviano ogni operazione una sola volta. Non la ripetono mai automaticamente: un nuovo invio è una nuova operazione soggetta ad addebito. Un timeout o un errore di connessione significa che il client non ha ricevuto una risposta completa; non dimostra che il server abbia interrotto l'elaborazione né che non siano stati addebitati crediti.

Salva il request_id restituito e lo stato dell'addebito insieme al record del tuo lavoro. L'oggetto di errore conserva la risposta per un'analisi controllata, ma può contenere l'input originale: non scrivere nei log ordinari né l'intero oggetto né la risposta né la chiave API.

• Problem Details e decisioni sui nuovi tentativi →
• Crediti e conferma dell'addebito →

Conoscere il comportamento di rete dell'esempio

Il timeout di 10 secondi di urllib si applica alle operazioni bloccanti sui socket; non è un limite garantito alla durata totale della richiesta. L'esempio disattiva i reindirizzamenti HTTP, analizza le risposte JSON riuscite e conserva le risposte Problem HTTP. Non ripete mai automaticamente le richieste.

I test locali usano risposte di trasporto simulate per chiamate riuscite, risultati sconosciuti, batch parzialmente riusciti, accesso all'account ed errori. Verificano la logica di controllo dell'esempio; non misurano la disponibilità dell'API in produzione, l'accuratezza dell'inferenza o i tempi di risposta. Ogni comando demo esplicito riportato di seguito invia una propria richiesta soggetta ad addebito.

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

• Documentazione Python su urllib.request →
• Documentazione Python su HTTPError →

Domande frequenti