# API v2-Authentifizierung und kostenlose Testversion

> Authentifizieren Sie GenderAPI v2 mit Ihrem vorhandenen API-Schlüssel. Lernen Sie Bearer-Header, GET-Abfrageschlüssel, IP-Testzugriff und JSON-Anfragen kennen.

Canonical HTML: https://www.genderapi.io/de/docs/v2/authentication

Last reviewed: 2026-09-25

## Authentifizierung und die kostenlose Testversion

Senden Sie Authorization: Bearer YOUR_API_KEY von Ihrem Server. Ersetzen Sie YOUR_API_KEY durch Ihren vorhandenen GenderAPI-Schlüssel. Beide Versionen teilen sich Ihr Guthaben; Es ist kein separates v2-Abonnement oder Schlüssel erforderlich.

Alle POST-Anfragen erfordern Content-Type: application/json. Verwenden Sie Ihren vorhandenen Schlüssel Bearer API. Jede Anfrage wird unabhängig bearbeitet; Bei wiederholten Anfragen erfolgt die normale Abrechnung.

Nur GET /gender akzeptiert auch den Schlüsselabfrageparameter. Bevorzugen Sie den Authorization-Header für Integrationen, da URLs im Browserverlauf und in Protokollen gespeichert werden können. Fügen Sie keine privaten Schlüssel in den Frontend-Code ein.

Wenn ein API-Schlüssel fehlt, ein ungültiges Format hat oder nicht erkannt wird, verwendet die Anfrage die mit v1 geteilte IP-Testversion. Dies gilt nicht für erkannte Schlüssel, die deaktiviert, abgelaufen oder eingeschränkt sind. Überprüfen Sie den Zugriffsmodus in meta.access.mode: api_key, ip_trial oder unauthenticated. Der Testgrund ist api_key_missing, api_key_invalid oder api_key_not_found. Ein ungültiger Schlüssel kann daher immer noch eine erfolgreiche Testantwort erhalten. Überprüfen Sie den Zugriffsmodus in der Produktion.

Testguthaben werden nach einem Zeitraum von 24 Stunden zurückgesetzt, nicht unbedingt um Mitternacht. Verwenden Sie /usage, um resets_at zu lesen. Personen, die hinter demselben öffentlichen IP stehen, teilen sich diese Zulage.

- [Melden Sie sich bei Ihrem GenderAPI-Konto an](https://app.genderapi.io/user/login)
- [Erstellen Sie ein Konto](https://app.genderapi.io/user/register)

## Richten Sie Ihren API-Schlüssel ein

Kopieren Sie Ihren API-Schlüssel von Ihrem GenderAPI-Konto. Ersetzen Sie YOUR_API_KEY unten durch diesen Schlüssel und führen Sie dann das ausgewählte Beispiel in derselben Terminalsitzung aus. Diese Befehle legen eine Umgebungsvariable nur für diese Sitzung fest; Der veröffentlichte Platzhalter ist kein Arbeitsschlüssel.

Konfigurieren Sie für eine Anwendung oder Bereitstellung GENDERAPI_API_KEY als serverseitiges Geheimnis. Die Beispiele laden nicht automatisch eine .env-Datei. Halten Sie den Schlüssel von Browserpaketen, Quellcodeverwaltung und öffentlichen URLs fern.

**macOS/Linux-Terminal**

```bash
export GENDERAPI_API_KEY='YOUR_API_KEY'
```

**Windows PowerShell**

```powershell
$env:GENDERAPI_API_KEY = 'YOUR_API_KEY'
```

## Überprüfen Sie den Zugriff, ohne Credits auszugeben

Rufen Sie GET /usage mit dem Bearer-Header auf. Ein gültiger Kontoschlüssel erzeugt meta.access.mode: api_key. Wenn das Ergebnis ip_trial lautet, überprüfen Sie den kopierten Schlüssel, bevor Sie Vorhersagen ausführen. Diese Anfrage ist kostenlos, auch für ein Konto ohne Restguthaben.

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.

Diese Bilanzablesung kostet keine Credits. Es wird weiterhin auf die Anforderungsratenbegrenzungen angerechnet.

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 GET 'https://api.genderapi.io/api/v2/usage' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}"
```

**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 response = await fetch("https://api.genderapi.io/api/v2/usage", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
  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")

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/usage",
    method="GET",
    headers={
        "Authorization": "Bearer " + api_key,
    },
)
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');
}

$ch = curl_init('https://api.genderapi.io/api/v2/usage');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_FOLLOWLOCATION => false,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
    ],
]);
$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");
        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/usage"))
            .timeout(Duration.ofSeconds(30))
            .header("Authorization", "Bearer " + apiKey)
            .GET()
            .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.Get, "https://api.genderapi.io/api/v2/usage");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);

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")
    request, err := http.NewRequest("GET", "https://api.genderapi.io/api/v2/usage", nil)
    if err != nil { return err }
    request.Header.Set("Authorization", "Bearer " + apiKey)
    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)
    }
}
```

## Nächste Schritte

- [Machen Sie eine Namensvorhersage](https://www.genderapi.io/de/docs/v2/gender-from-name)
- [Lesen Sie Ihr Guthaben ab](https://www.genderapi.io/de/docs/v2/credits-and-usage)
- [Anfragen sicher wiederholen](https://www.genderapi.io/de/docs/v2/errors-and-retries#retries)