ΤΕΚΜΗΡΙΩΣΗ API V2

Προβλέψεις ονόματος παρτίδας, email και ονόματος χρήστη

Στείλτε έως και 50 προβλέψεις GenderAPI v2 σε μία παρτίδα. Μάθετε επιλογές ανά στοιχείο, διατηρημένα αναγνωριστικά, μερικές αποτυχίες, περιλήψεις αποκρίσεων και λογιστική πίστωσης.

Ονόματα παρτίδων, email και ονόματα χρήστη

Το POST /gender/batch δέχεται έναν πίνακα items που περιέχει 1–50 καταχωρήσεις με πρόσβαση κλειδιού API ή το πολύ 10 καταχωρήσεις με τη δοκιμή IP. Στείλτε ονόματα, διευθύνσεις email, ονόματα χρήστη ή ένα μείγμα από τα τρία. Κάθε καταχώρηση έχει ξεχωριστά πεδία country, forceToGenderize και options. Τα αναγνωριστικά είναι προαιρετικά, αλλά πρέπει να είναι μοναδικά εντός της παρτίδας.

Τα αποτελέσματα ακολουθούν τη σειρά εισαγωγής. Κάθε αποτέλεσμα περιέχει index, charged_credits και ακριβώς ένα από τα data ή error. Εάν παρείχατε ένα id, επιστρέφεται επίσης. Μια απόκριση HTTP 200 μπορεί να περιέχει αποτυχίες για μεμονωμένες καταχωρίσεις, επομένως ελέγξτε κάθε αποτέλεσμα. Το meta.summary περιλαμβάνει τα total, succeeded, identified, unknown και failed. Μια ολοκληρωμένη πρόβλεψη χωρίς γνωστό φύλο εξακολουθεί να μετράει ως επιτυχημένη και κοστίζει πιστώσεις.

Εάν η επικύρωση ή ο σχεδιασμός του αιτήματος αποτύχει, ολόκληρη η παρτίδα απορρίπτεται πριν αφαιρεθούν τυχόν πιστώσεις. Εάν όλες οι καταχωρήσεις αποτύχουν κατά την εκτέλεση, το API επιστρέφει μια απάντηση πρόβλημα που δεν είναι 2xx με έναν πίνακα data και το ψευδώνυμο results παλαιού τύπου. Οι αποτυχημένες καταχωρήσεις κοστίζουν μηδενικές πιστώσεις μετά από επιβεβαιωμένη επιστροφή χρημάτων. Εάν η τιμολόγηση δεν είναι επιβεβαιωμένη, μην υποθέσετε ότι το αναφερόμενο κόστος για κάθε καταχώρηση είναι οριστικό.

Επιλέξτε γλώσσα προγραμματισμού. Ρυθμίστε το κλειδί API, και μετά εκτελέστε το παράδειγμα στον διακομιστή σας.

Κάθε αίτημα πρόβλεψης είναι μια νέα χρεώσιμη λειτουργία, συμπεριλαμβανομένων των επαναλήψεων. Αυτά τα παραδείγματα δεν επαναλαμβάνονται αυτόματα. Ελέγξτε την κατάσταση χρέωσης πριν στείλετε άλλο αίτημα.

Πριν την εκτέλεση: πρόσβαση και διαχείριση σφαλμάτων

Εκτελέστε αυτά τα παραδείγματα στον διακομιστή σας. Ρυθμίστε το GENDERAPI_API_KEY στο περιβάλλον διεργασίας στο υπάρχον κλειδί API. Επιβεβαιώστε ότι το meta.access.mode είναι api_key: ένα μη αναγνωρισμένο κλειδί μπορεί να επιστρέψει στη δοκιμή IP.

Για αποκρίσεις HTTP 4xx και 5xx JSON, τα παραδείγματα διατηρούν το σώμα σφάλματος και εξέρχονται με κατάσταση μη μηδενική. Ελέγξτε τα code, action και meta.usage.billing_status πριν προσπαθήσετε ξανά. Για απόκριση παρτίδας HTTP 200, ελέγξτε επίσης το data ή το error σε κάθε αποτέλεσμα.

Οδηγός σφάλματος και δοκιμάστε ξανά →
cURL
curl --silent --show-error --fail-with-body --max-time 30 \
  --request POST 'https://api.genderapi.io/api/v2/gender/batch' \
  --header "Authorization: Bearer ${GENDERAPI_API_KEY:?Set GENDERAPI_API_KEY}" \
  --header 'Content-Type: application/json' \
  --data '{
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
}'

cURL 7,76+ σε κέλυφος POSIX. Εκτελέστε στο τερματικό σας. Τεκμηρίωση χρόνου εκτέλεσης

JavaScript / Node.js
// 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 = {
  "items": [
    {
      "id": "contact-1",
      "type": "name",
      "value": "Onur",
      "country": "TR"
    },
    {
      "id": "contact-2",
      "type": "email",
      "value": "alice.smith@example.com",
      "options": {
        "ai_mode": "fallback"
      }
    },
    {
      "id": "contact-3",
      "type": "username",
      "value": "prenses",
      "country": "TR",
      "forceToGenderize": true
    }
  ]
};

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

Node.js 22+; ενσωματωμένη ανάκτηση. Αποθηκεύστε ως example.mjs και εκτελέστε το node example.mjs. Τεκμηρίωση χρόνου εκτέλεσης

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("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}")

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/batch",
    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.

Python 3,10+; τυπική βιβλιοθήκη. Αποθηκεύστε ως example.py και εκτελέστε το python3 example.py. Τεκμηρίωση χρόνου εκτέλεσης

PHP
<?php
$apiKey = getenv('GENDERAPI_API_KEY');
if (!$apiKey) {
    throw new RuntimeException('Set GENDERAPI_API_KEY');
}
$body = json_decode('{"items":[{"id":"contact-1","type":"name","value":"Onur","country":"TR"},{"id":"contact-2","type":"email","value":"alice.smith@example.com","options":{"ai_mode":"fallback"}},{"id":"contact-3","type":"username","value":"prenses","country":"TR","forceToGenderize":true}]}', true, 512, JSON_THROW_ON_ERROR);

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

PHP 8+ με την επέκταση cURL. Αποθηκεύστε ως example.php και εκτελέστε το php example.php. Τεκμηρίωση χρόνου εκτέλεσης

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 = "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}";
        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/batch"))
            .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.
    }
}

Java 17+; τυπικό πελάτη HTTP. Αποθηκεύστε ως GenderApiExample.java και εκτελέστε το java GenderApiExample.java. Τεκμηρίωση χρόνου εκτέλεσης

C# / .NET
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/batch");
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
request.Content = new StringContent("{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}", 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.
}

Εφαρμογή κονσόλας .NET 8+. Χρησιμοποιήστε το ως Program.cs σε ένα έργο κονσόλας και, στη συνέχεια, εκτελέστε το dotnet run. Τεκμηρίωση χρόνου εκτέλεσης

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 := "{\"items\":[{\"id\":\"contact-1\",\"type\":\"name\",\"value\":\"Onur\",\"country\":\"TR\"},{\"id\":\"contact-2\",\"type\":\"email\",\"value\":\"alice.smith@example.com\",\"options\":{\"ai_mode\":\"fallback\"}},{\"id\":\"contact-3\",\"type\":\"username\",\"value\":\"prenses\",\"country\":\"TR\",\"forceToGenderize\":true}]}"
    request, err := http.NewRequest("POST", "https://api.genderapi.io/api/v2/gender/batch", 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)
    }
}

Go 1,22+; τυπική βιβλιοθήκη. Αποθηκεύστε ως main.go και εκτελέστε το go run main.go. Τεκμηρίωση χρόνου εκτέλεσης

Διαβάστε μια παρτίδα απάντηση

Αυτό το ανεξάρτητο συνθετικό παράδειγμα περιέχει μια αντιστοίχιση δεδομένων, ένα άγνωστο αποτέλεσμα και μια αποτυχία παρόχου. Παρουσιάζει μια απόκριση HTTP 200 με μερική επιτυχία, όχι την αναμενόμενη έξοδο του αιτήματος δέσμης παραπάνω. Τα δύο επιτυχημένα αντικείμενα κοστίζουν 1 πίστωση το καθένα. το στοιχείο που απέτυχε έχει επιβεβαιωμένη μηδενική χρέωση.

Ενδεικτική απόκριση JSON
{
  "data": [
    {
      "index": 0,
      "id": "known",
      "charged_credits": 1,
      "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"
        }
      }
    },
    {
      "index": 1,
      "id": "missing",
      "charged_credits": 1,
      "data": {
        "input": {
          "type": "name",
          "value": "zzzxxyy",
          "country": null
        },
        "name": null,
        "gender": null,
        "country": null,
        "confidence": null,
        "confidence_kind": null,
        "sample_count": null,
        "source": "none",
        "result_status": "unknown",
        "reason": "not_found",
        "country_source": null,
        "match": {
          "name": null,
          "method": null,
          "scope": null,
          "country": null
        }
      }
    },
    {
      "index": 2,
      "id": "failed",
      "charged_credits": 0,
      "error": {
        "type": "urn:genderapi:problem:ai_upstream_error",
        "title": "ai upstream error",
        "status": 502,
        "detail": "The AI provider could not complete the request.",
        "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
        "code": "ai_upstream_error",
        "request_id": "11111111-1111-4111-8111-111111111111",
        "documentation": "https://api.genderapi.io/api/v2/errors",
        "action": "inspect_billing_before_retry"
      }
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 2,
      "remaining_credits": 6,
      "billing_status": "confirmed",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    },
    "summary": {
      "total": 3,
      "succeeded": 2,
      "identified": 1,
      "unknown": 1,
      "failed": 1
    }
  }
}

Σχεδιάστε δέσμες πιστώσεων και επαναλήψεις

Πραγματοποιήστε έλεγχο ταυτότητας με το υπάρχον κλειδί Bearer API και στείλτε το Content-Type: application/json. Κάθε παρτίδα που υποβάλλεται είναι μια νέα λειτουργία. Εάν επιχειρήσετε ξανά μια μερική αποτυχία, υποβάλετε μόνο τα αποτυχημένα στοιχεία αφού ελέγξετε τη χρέωση. Η εκ νέου αποστολή επιτυχημένων αντικειμένων τα χρεώνει ξανά.

Από προεπιλογή, οι καταχωρίσεις παρτίδας χρησιμοποιούν off και κοστίζουν 1 πίστωση ανά ολοκληρωμένη πρόβλεψη. Η επιλογή fallback κοστίζει επίσης 1 πίστωση συνολικά, συμπεριλαμβανομένης της τεχνητής νοημοσύνης. Η επιλογή always κοστίζει 2 μονάδες. Με το forceToGenderize, ένα φύλο που βρίσκεται στο σύνολο δεδομένων κοστίζει 1 πίστωση. Η χρήση AI κοστίζει 2 μονάδες συνολικά. Ολοκληρωμένες προβλέψεις με άγνωστο φύλο κοστίζουν επίσης πιστώσεις. Ένα αρχικό υπόλοιπο 1 πίστωσης είναι αρκετό για να ξεκινήσει μια παρτίδα. Η τελική αφαίρεση μπορεί να αφήσει το υπόλοιπο αρνητικό.