# Paramètres de requête API v2

> Référence des champs type, value, country, forceToGenderize et ai_mode de GenderAPI V2, avec les différences entre les paramètres GET et les corps JSON des requêtes POST.

Canonical HTML: https://www.genderapi.io/fr/docs/v2/request-parameters

Last reviewed: 2026-09-25

## Paramètres de prédiction uniques

Les champs facultatifs doivent être omis lorsqu'ils ne sont pas utilisés ; n'envoyez pas null ou des chaînes vides à la place de country ou options. Les booléens JSON doivent être des true ou des false, et non des chaînes. Le texte UTF-8 est pris en charge ; les noms n’ont pas besoin d’être translittérés en ASCII.

GET utilise type, value, country, forceToGenderize et ai_mode directement dans la chaîne de requête, plus key en option. Encodez les valeurs avec l'encodeur de paramètre URL de votre client HTTP ; par exemple @ devient %40. Pour les booléens GET, envoyez true ou false. Les champs inconnus et les valeurs invalides sont rejetés.

| Champ JSON | Type | Règle |
| --- | --- | --- |
| type | string | Requis pour POST : name, email ou username. GET est par défaut name. |
| value | string | Obligatoire. 1 à 254 caractères ; non vide, sans caractères de contrôle. Les valeurs de courrier électronique doivent être une syntaxe de courrier électronique valide. |
| country | string | Code ISO 3166-1 alpha-2 majuscule facultatif, par exemple TR ou US. La recherche spécifique à un pays peut revenir à l'ensemble de données mondial. |
| forceToGenderize | boolean | Facultatif ; la valeur par défaut est false. Tout d’abord, recherchez l’ensemble de données. Si aucun genre ne peut être déterminé, utilisez l’IA pour interpréter le surnom. Pris en charge pour les trois types d’entrée. |
| options.ai_mode | string | off, fallback ou always. La valeur par défaut est fallback pour les demandes uniques et off pour les articles par lots. |
| id | string | Identifiant facultatif avec 1 à 64 caractères dans le corps POST JSON. Il doit être unique au sein d'un lot et est renvoyé avec son résultat de lot. Les requêtes uniques acceptent cet identifiant mais ne l'incluent pas dans la réponse. Les requêtes GET ne le prennent pas en charge. |

## Avant d'envoyer la demande

Envoyer JSON à POST https://api.genderapi.io/api/v2/gender. Utilisez votre clé API existante dans Authorization: Bearer YOUR_API_KEY et Content-Type: application/json. Chaque demande est traitée de manière indépendante.

Choisissez votre langue dans l'exemple de code. Définissez GENDERAPI_API_KEY dans l'environnement de processus avant de l'exécuter. Les clés manquantes ou non reconnues peuvent utiliser l'essai partagé IP, donc confirmez que meta.access.mode est api_key lors de l'intégration d'un compte.

- [Authentification et accès à l'essai](https://www.genderapi.io/fr/docs/v2/authentication)
- [Tous les paramètres de la requête](https://www.genderapi.io/fr/docs/v2/request-parameters)

## Demander des exemples par langue

Cet exemple utilise les champs de requête partagés pour une recherche de nom. Remplacez type et value par une adresse e-mail ou un nom d'utilisateur, ou définissez options.ai_mode et forceToGenderize comme décrit ci-dessus.

Exécutez ces exemples sur votre serveur. Définissez GENDERAPI_API_KEY dans l’environnement de processus sur votre clé API existante. Confirmez que meta.access.mode est api_key : une clé non reconnue peut revenir à l'essai IP.

Chaque demande de prédiction est une nouvelle opération facturable, y compris les nouvelles tentatives. Ces exemples ne réessayent pas automatiquement. Vérifiez l'état de facturation avant d'envoyer une autre demande.

Les réponses HTTP 4xx et 5xx JSON préservent le corps de l'erreur et renvoient un état de sortie différent de zéro. Vérifiez code, action et meta.usage.billing_status avant de réessayer.

**cURL**

cURL 7.76+ dans un shell POSIX. Exécutez dans votre terminal.

```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+ ; récupération intégrée. Enregistrez sous example.mjs et exécutez 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+ ; bibliothèque standard. Enregistrez sous example.py et exécutez 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+ avec l'extension cURL. Enregistrez sous example.php et exécutez 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 standard HTTP. Enregistrez sous GenderApiExample.java et exécutez 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**

Application console .NET 8+. Utilisez comme Program.cs dans un projet de console, puis exécutez 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+ ; bibliothèque standard. Enregistrez sous main.go et exécutez 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)
    }
}
```

## Guides associés

- [Modes IA et forceToGenderize](https://www.genderapi.io/fr/docs/v2/ai-options)
- [Prédictions par lots](https://www.genderapi.io/fr/docs/v2/batch)
- [Crédits et utilisation](https://www.genderapi.io/fr/docs/v2/credits-and-usage)
- [Erreurs et tentatives](https://www.genderapi.io/fr/docs/v2/errors-and-retries)