# API v2-Anforderungsparameter

> Referenz für die GenderAPI-V2-Felder type, value, country, forceToGenderize und ai_mode sowie die Unterschiede zwischen GET-Abfragen und POST-JSON.

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

Last reviewed: 2026-09-25

## Einzelne Vorhersageparameter

Optionale Felder sollten weggelassen werden, wenn sie nicht verwendet werden. Senden Sie nicht null oder leere Zeichenfolgen anstelle von country oder options. JSON Boolesche Werte müssen true oder false sein, keine Zeichenfolgen. UTF-8-Text wird unterstützt; Namen müssen nicht in ASCII transkribiert werden.

GET verwendet type, value, country, forceToGenderize und ai_mode direkt in der Abfragezeichenfolge sowie optional key. Kodieren Sie Werte mit dem URL-Parameter-Encoder Ihres HTTP-Clients; Beispielsweise wird @ zu %40. Für boolesche Werte GET senden Sie true oder false. Unbekannte Felder und ungültige Werte werden abgelehnt.

| JSON-Feld | Typ | Regel |
| --- | --- | --- |
| type | string | Erforderlich für POST: name, email oder username. GET ist standardmäßig name. |
| value | string | Erforderlich. 1–254 Zeichen; Nicht leer, ohne Steuerzeichen. E-Mail-Werte müssen eine gültige E-Mail-Syntax sein. |
| country | string | Optionaler ISO 3166-1 alpha-2-Code in Großbuchstaben, zum Beispiel TR oder US. Die länderspezifische Suche kann auf den globalen Datensatz zurückgreifen. |
| forceToGenderize | boolean | Optional; Der Standardwert ist false. Durchsuchen Sie zunächst den Datensatz. Wenn kein Geschlecht ermittelt werden kann, verwenden Sie KI zur Interpretation des Spitznamens. Wird für alle drei Eingabetypen unterstützt. |
| options.ai_mode | string | off, fallback oder always. Der Standardwert ist fallback für Einzelanforderungen und off für Batch-Elemente. |
| id | string | Optionaler Bezeichner mit 1–64 Zeichen im POST-JSON-Text. Es muss innerhalb eines Batches eindeutig sein und wird mit seinem Batch-Ergebnis zurückgegeben. Einzelne Anfragen akzeptieren diese Kennung, nehmen sie jedoch nicht in die Antwort auf. GET-Abfragen unterstützen dies nicht. |

## Vor dem Absenden der Anfrage

Senden Sie JSON an POST https://api.genderapi.io/api/v2/gender.. Verwenden Sie Ihren vorhandenen API-Schlüssel in Authorization: Bearer YOUR_API_KEY und Content-Type: application/json. Jede Anfrage wird eigenständig bearbeitet.

Wählen Sie Ihre Sprache im Codebeispiel. Legen Sie GENDERAPI_API_KEY in der Prozessumgebung fest, bevor Sie es ausführen. Fehlende oder nicht erkannte Schlüssel können die freigegebene IP-Testversion verwenden. Stellen Sie daher sicher, dass meta.access.mode api_key ist, wenn Sie ein Konto integrieren.

- [Authentifizierung und Testzugang](https://www.genderapi.io/de/docs/v2/authentication)
- [Alle Anforderungsparameter](https://www.genderapi.io/de/docs/v2/request-parameters)

## Fordern Sie Beispiele nach Sprache an

In diesem Beispiel werden die gemeinsam genutzten Anforderungsfelder für eine Namenssuche verwendet. Ändern Sie type und value für eine E-Mail-Adresse oder einen Benutzernamen oder legen Sie options.ai_mode und forceToGenderize wie oben beschrieben fest.

Führen Sie diese Beispiele auf Ihrem Server aus. Setzen Sie GENDERAPI_API_KEY in der Prozessumgebung auf Ihren vorhandenen API-Schlüssel. Bestätigen Sie, dass meta.access.mode api_key ist: Ein nicht erkannter Schlüssel kann auf die IP-Testversion zurückgreifen.

Jede Vorhersageanfrage ist ein neuer kostenpflichtiger Vorgang, einschließlich Wiederholungsversuchen. Bei diesen Beispielen wird der Versuch nicht automatisch wiederholt. Überprüfen Sie den Rechnungsstatus, bevor Sie eine weitere Anfrage senden.

HTTP 4xx und 5xx JSON-Antworten behalten den Fehlertext bei und geben einen Exit-Status ungleich Null zurück. Überprüfen Sie code, action und meta.usage.billing_status, bevor Sie es erneut versuchen.

**cURL**

cURL 7.76+ in einer POSIX-Shell. Führen Sie es in Ihrem Terminal aus.

```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+; Integrierter Abruf. Speichern Sie es als example.mjs und führen Sie node example.mjs aus.

```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+; Standardbibliothek. Speichern Sie es als example.py und führen Sie python3 example.py aus.

```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+ mit der cURL-Erweiterung. Speichern Sie es als example.php und führen Sie php example.php aus.

```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+; Standard-HTTP-Client. Speichern Sie es als GenderApiExample.java und führen Sie java GenderApiExample.java aus.

```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**

.NET 8+ Konsolenanwendung. Als Program.cs in einem Konsolenprojekt verwenden und dann dotnet run ausführen.

```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+; Standardbibliothek. Speichern Sie es als main.go und führen Sie go run main.go aus.

```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)
    }
}
```

## Verwandte Leitfäden

- [KI-Modi und forceToGenderize](https://www.genderapi.io/de/docs/v2/ai-options)
- [Batch-Vorhersagen](https://www.genderapi.io/de/docs/v2/batch)
- [Credits und Nutzung](https://www.genderapi.io/de/docs/v2/credits-and-usage)
- [Fehler und Wiederholungsversuche](https://www.genderapi.io/de/docs/v2/errors-and-retries)