# genere da un nome con API v2

> Prevedi il genere dal nome o dal nome completo con GenderAPI v2. Visualizza esempi in sette lingue, risposte JSON, contesto nazionale, fallback IA e costi del credito.

Canonical HTML: https://www.genderapi.io/it/docs/v2/gender-from-name

Last reviewed: 2026-09-26

## 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.

- [Autenticazione e accesso di prova](https://www.genderapi.io/it/docs/v2/authentication)
- [Tutti i parametri di richiesta](https://www.genderapi.io/it/docs/v2/request-parameters)

## 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.

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.

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.

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.

**cURL**

cURL 7.76+ in una shell POSIX. Esegui nel tuo terminale.

```bash
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "type": "name",
  "value": "Onur",
  "country": "TR"
}'
```

**JavaScript / Node.js**

Node.js 22+; recupero integrato. Salva come example.mjs ed esegui node example.mjs.

```javascript
// 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 = {
  "type": "name",
  "value": "Onur",
  "country": "TR"
};

const response = await fetch("https://api.genderapi.io/api/v2/gender", {
  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.
}
```

**Python**

Python 3.10+; libreria standard. Salva come example.py ed esegui python3 example.py.

```python
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("{\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}")

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",
    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.
```

**PHP**

PHP 8+ con estensione cURL. Salva come example.php ed esegui php example.php.

```php
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"type":"name","value":"Onur","country":"TR"}', true, 512, JSON_THROW_ON_ERROR);

$ch = curl_init('https://api.genderapi.io/api/v2/gender');
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.
```

**Java**

Java 17+; client HTTP standard. Salva come GenderApiExample.java ed esegui java GenderApiExample.java.

```java
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 = "{\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}";
        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"))
            .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.
    }
}
```

**C# / .NET**

Applicazione console .NET 8+. Utilizzare come Program.cs in un progetto console, quindi eseguire dotnet run.

```csharp
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");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}", 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.
}
```

**Go**

Go 1,22+; libreria standard. Salva come main.go ed esegui go run main.go.

```go
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 := "{\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender", 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)
    }
}
```

## 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.

```json
{
  "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 di risposta e confidenza](https://www.genderapi.io/it/docs/v2/responses)

## 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.

## Guide correlate

- [Modalità IA e forceToGenderize](https://www.genderapi.io/it/docs/v2/ai-options)
- [Previsioni batch](https://www.genderapi.io/it/docs/v2/batch)
- [Crediti e utilizzo](https://www.genderapi.io/it/docs/v2/credits-and-usage)
- [Errori e tentativi](https://www.genderapi.io/it/docs/v2/errors-and-retries)