# Parámetros de solicitud API v2

> Referencia de los campos type, value, country, forceToGenderize y ai_mode de GenderAPI V2, con las diferencias entre consultas GET y cuerpos JSON de POST.

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

Last reviewed: 2026-09-25

## Parámetros de predicción únicos

Los campos opcionales deben omitirse cuando no se utilicen; no envíe null ni cadenas vacías en lugar de country o options. Los booleanos JSON deben ser true o false, no cadenas. Se admite texto UTF-8; No es necesario transliterar los nombres a ASCII.

GET utiliza type, value, country, forceToGenderize y ai_mode directamente en la cadena de consulta, además de key opcional. Codifique valores con el codificador de parámetros URL de su cliente HTTP; por ejemplo @ se convierte en %40. Para valores booleanos GET, envíe true o false. Se rechazan los campos desconocidos y los valores no válidos.

| Campo JSON | Tipo | Regla |
| --- | --- | --- |
| type | string | Requerido para POST: name, email o username. GET tiene como valor predeterminado name. |
| value | string | Requerido. 1–254 caracteres; no en blanco, sin caracteres de control. Los valores de correo electrónico deben tener una sintaxis de correo electrónico válida. |
| country | string | Código ISO 3166-1 alpha-2 en mayúsculas opcional, por ejemplo TR o US. La búsqueda específica de un país puede recurrir al conjunto de datos global. |
| forceToGenderize | boolean | Opcional; el valor predeterminado es false. Primero, busque el conjunto de datos. Si no se puede determinar el género, utilice IA para interpretar el apodo. Compatible con los tres tipos de entrada. |
| options.ai_mode | string | off, fallback o always. El valor predeterminado es fallback para solicitudes individuales y off para elementos por lotes. |
| id | string | Identificador opcional con entre 1 y 64 caracteres en el cuerpo POST JSON. Debe ser único dentro de un lote y se devuelve con el resultado del lote. Las solicitudes únicas aceptan este identificador pero no lo incluyen en la respuesta. Las consultas GET no lo admiten. |

## Antes de enviar la solicitud

Enviar JSON a POST https://api.genderapi.io/api/v2/gender. Utilice su clave API existente en Authorization: Bearer YOUR_API_KEY y Content-Type: application/json. Cada solicitud se procesa de forma independiente.

Elija su idioma en el ejemplo de código. Configure GENDERAPI_API_KEY en el entorno del proceso antes de ejecutarlo. Las claves faltantes o no reconocidas pueden usar la versión de prueba compartida de IP, así que confirme que meta.access.mode es api_key al integrar una cuenta.

- [Autenticación y acceso de prueba](https://www.genderapi.io/es/docs/v2/authentication)
- [Todos los parámetros de solicitud](https://www.genderapi.io/es/docs/v2/request-parameters)

## Solicitar ejemplos por idioma

Este ejemplo utiliza los campos de solicitud compartidos para una búsqueda de nombres. Cambie type y value por un correo electrónico o nombre de usuario, o configure options.ai_mode y forceToGenderize como se describe anteriormente.

Ejecute estos ejemplos en su servidor. Configure GENDERAPI_API_KEY en el entorno de proceso con su clave API existente. Confirme que meta.access.mode es api_key: una clave no reconocida puede recurrir a la prueba IP.

Cada solicitud de predicción es una nueva operación facturable, incluidos los reintentos. Estos ejemplos no se reintentan automáticamente. Verifique el estado de facturación antes de enviar otra solicitud.

Las respuestas HTTP 4xx y 5xx JSON conservan el cuerpo del error y devuelven un estado de salida distinto de cero. Verifique code, action y meta.usage.billing_status antes de volver a intentarlo.

**cURL**

cURL 7.76+ en un shell POSIX. Ejecuta en tu 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+; búsqueda incorporada. Guarde como example.mjs y ejecute 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+; biblioteca estándar. Guarde como example.py y ejecute 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 la extensión cURL. Guarde como example.php y ejecute 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+; cliente estándar HTTP. Guarde como GenderApiExample.java y ejecute 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**

Aplicación de consola .NET 8+. Úselo como Program.cs en un proyecto de consola, luego ejecute 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+; biblioteca estándar. Guarde como main.go y ejecute 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)
    }
}
```

## Guías relacionadas

- [Modos IA y forceToGenderize](https://www.genderapi.io/es/docs/v2/ai-options)
- [Predicciones por lotes](https://www.genderapi.io/es/docs/v2/batch)
- [Créditos y uso](https://www.genderapi.io/es/docs/v2/credits-and-usage)
- [Errores y reintentos](https://www.genderapi.io/es/docs/v2/errors-and-retries)