Prima di inviare la richiesta
Invia JSON a POST https://api.genderapi.io/api/v2/gender. Utilizza la chiave API esistente in Authorization: Bearer YOUR_API_KEY e Content-Type: application/json. Ogni richiesta viene elaborata in modo indipendente.
Scegli la tua lingua nell'esempio di codice. Impostare GENDERAPI_API_KEY nell'ambiente del processo prima di eseguirlo. Le chiavi mancanti o non riconosciute possono utilizzare la versione di prova IP condivisa, quindi conferma che meta.access.mode è api_key quando integri un account.
Genere da un nome
| Parametro | Tipo | Obbligatorio | Valore predefinito | Descrizione |
|---|---|---|---|---|
type | string | Sì | — | Categoria di input: name, email o username. |
value | string | Sì | — | Obbligatorio. 1–254 caratteri; non vuoto, senza caratteri di controllo. I valori email devono avere una sintassi email valida. |
country | string | No | — | Codice ISO 3166-1 alpha-2 maiuscolo opzionale, ad esempio TR o US. La ricerca specifica per paese può ricorrere al set di dati globale. |
forceToGenderize | boolean | No | false | Consulta prima il dataset, poi l’IA per soprannomi se il risultato non è risolto. Supporta name, email e username. |
options | object | No | — | Oggetto contenente le opzioni IA di ciascun input. |
options.ai_mode | string | No | fallback | Valori ammessi: off, fallback, always. Con forceToGenderize: true, ometti il campo o usa fallback. |
id | string | No | — | Identificatore facoltativo con 1-64 caratteri nel corpo POST JSON. Deve essere univoco all'interno di un batch e viene restituito con il risultato del batch. Le richieste singole accettano questo identificatore ma non lo includono nella risposta. Le query GET non lo supportano. |
Utilizza type: name per inviare un nome o un nome completo. Una risposta riuscita può contenere gender: null. Le richieste singole cercano prima il set di dati. Se non è possibile determinare il genere, utilizzano l'intelligenza artificiale per impostazione predefinita.
Scegli un linguaggio di programmazione. Configura la tua chiave API, quindi esegui l'esempio sul tuo server.
Ogni richiesta di previsione è una nuova operazione fatturabile, inclusi i nuovi tentativi. Questi esempi non riprovano automaticamente. Controlla lo stato della fatturazione prima di inviare un'altra richiesta.
Prima di eseguire: accesso e gestione degli errori
Esegui questi esempi sul tuo server. Impostare GENDERAPI_API_KEY nell'ambiente di processo sulla chiave API esistente. Conferma che meta.access.mode è api_key: una chiave non riconosciuta può ricadere nella versione di prova IP.
HTTP Le risposte 4xx e 5xx JSON preservano il corpo dell'errore e restituiscono uno stato di uscita diverso da zero. Controllare code, action e meta.usage.billing_status prima di riprovare.
Guida all'errore e al nuovo tentativo →cURL 7.76+ in una shell POSIX. Esegui nel tuo terminale. Documentazione di runtime
Node.js 22+; recupero integrato. Salva come example.mjs ed esegui node example.mjs. Documentazione di runtime
Python 3.10+; libreria standard. Salva come example.py ed esegui python3 example.py. Documentazione di runtime
PHP 8+ con estensione cURL. Salva come example.php ed esegui php example.php. Documentazione di runtime
Java 17+; client HTTP standard. Salva come GenderApiExample.java ed esegui java GenderApiExample.java. Documentazione di runtime
Applicazione console .NET 8+. Utilizzare come Program.cs in un progetto console, quindi eseguire dotnet run. Documentazione di runtime
Go 1,22+; libreria standard. Salva come main.go ed esegui go run main.go. Documentazione di runtime
Esempio di risposta
Questa risposta sintetica illustra la forma dello JSON, non la precisione misurata o un risultato live garantito. Mostra l'accesso di prova IP; un'operazione autenticata riporta i campi quota di sola prova meta.access.mode: api_key e null. Leggere i dati per l'inferenza e meta.usage per l'esito della fatturazione dell'operazione.
{
"data": {
"input": {
"type": "name",
"value": "Onur",
"country": "TR"
},
"name": "onur",
"gender": "male",
"country": "TR",
"confidence": 0.9,
"confidence_kind": "observed_frequency",
"sample_count": 100,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "onur",
"method": "normalized",
"scope": "country",
"country": "TR"
}
},
"meta": {
"request_id": "11111111-1111-4111-8111-111111111111",
"duration_ms": 12,
"access": {
"mode": "ip_trial",
"reason": "api_key_missing"
},
"usage": {
"charged_credits": 1,
"remaining_credits": 9,
"billing_status": "confirmed",
"resets_at": "2026-09-26T12:00:00.000Z",
"limit": 10,
"period_seconds": 86400
}
}
}Campi della risposta di previsione
| Campo | Tipo | Ammette null? | Esempio | Descrizione |
|---|---|---|---|---|
data.input | object | No | {"type":"name","value":"Onur","country":"TR"} | Tipo di input, valore e paese. forceToGenderize è incluso quando true. |
data.name | string | Sì | "onur" | Nome abbinato o estratto; null quando nessuno è disponibile. |
data.gender | string | Sì | "male" | male, female o JSON null. Questa è una previsione, non una prova dell'identità di una persona. |
data.result_status | string | No | "identified" | identified se viene restituito un genere; altrimenti unknown. |
data.reason | string | Sì | null | null per i risultati identified. Motivi dei risultati sconosciuti: not_found, no_name_candidate, ambiguous o insufficient_evidence. |
data.confidence | number | Sì | 0.95 | Punteggio 0–1 o null. Il genere null ha la confidenza null. |
data.confidence_kind | string | Sì | "observed_frequency" | observed_frequency: il conteggio del genere dominante diviso per il conteggio totale nel set di dati selezionato. model_reported: un punteggio IA, non una probabilità calibrata. Il valore è null quando non disponibile. |
data.sample_count | integer | Sì | 1200 | Dimensioni del campione del set di dati o null. L'intelligenza artificiale non inventa un conteggio dei campioni. |
data.source | string | No | "dataset" | dataset, ai o none. |
data.country | string | Sì | "TR" | Associazione paese dal set di dati o ai_association o null. Non stabilisce nazionalità, residenza o etnia. |
data.country_source | string | Sì | "dataset" | Origine dell’associazione al paese: dataset, ai_association o null. |
data.match | object | No | {"name":"onur","method":"normalized","scope":"country","country":"TR"} | Nome corrispondente nel set di dati, metodo (normalized, token, substring o model_inference), ambito (country o global) e paese associato. Le informazioni non disponibili sono null. |
Accesso, addebiti e metadati della richiesta
| Campo | Tipo | Ammette null? | Esempio | Descrizione |
|---|---|---|---|---|
meta.request_id | string | No | "550e8400-e29b-41d4-a716-446655440000" | Identificatore univoco di questo tentativo HTTP; inviato anche in X-Request-ID. |
meta.duration_ms | integer | No | 42 | Tempo di elaborazione della richiesta in millisecondi. |
meta.access.mode | string | No | "api_key" | api_key, ip_trial o unauthenticated. Verifica api_key quando usi un account a pagamento. |
meta.access.reason | string | Sì | null | Motivo del passaggio alla prova: api_key_missing, api_key_invalid o api_key_not_found; altrimenti null. |
meta.usage.charged_credits | integer | Sì | 1 | Crediti netti addebitati. Zero prima dell’addebito o dopo un rimborso completo confermato; null se l’addebito non è confermato. |
meta.usage.remaining_credits | integer | Sì | 99 | Saldo al termine dell’operazione. Può essere negativo; null se non disponibile o se l’addebito non è confermato. |
meta.usage.billing_status | string | No | "confirmed" | not_charged, confirmed o unconfirmed. Controlla prima di ripetere una previsione non riuscita. |
meta.usage.resets_at | string | Sì | "2026-09-27T12:00:00.000Z" | Ripristino della prova per IP in UTC (ISO 8601); null per gli account con chiave API o se sconosciuto. |
meta.usage.limit | integer | Sì | 10 | Crediti disponibili nella prova per IP; null per gli account con chiave API. |
meta.usage.period_seconds | integer | Sì | 86400 | Durata della prova per IP in secondi; null per gli account con chiave API. |
Contesto del paese e nomi sconosciuti
Fornisci il paese solo quando disponi di un contesto pertinente. Lo API può selezionare una riga del set di dati specifica del paese o ricorrere a una riga globale. data.match.scope mostra quale è stato selezionato; il paese rimpatriato non stabilisce dove vive la persona.
Per impostazione predefinita, una singola richiesta utilizza l'intelligenza artificiale quando il set di dati non può determinare un genere, per un totale di 1 credito. Per utilizzare solo il set di dati, inviare options: {"ai_mode": "off"}. Una richiesta completata costa comunque crediti se restituisce gender: null. Una ricerca per nome completo può corrispondere a una parte del nome. data.match registra il candidato scelto e il metodo di corrispondenza.
Per un nickname fornito come nome, forceToGenderize: true consente l'inferenza IA senza un vero nome. Un genere identificato nel dataset costa 1 credito. Se è necessaria l'IA, il costo totale è di 2 crediti. Qualsiasi saldo iniziale positivo è sufficiente; il saldo finale potrebbe essere negativo.