Nombres, correos y usuarios por lotes
| Parámetro | Tipo | Obligatorio | Valor predeterminado | Descripción |
|---|---|---|---|---|
items | array<object> | Sí | — | Entre 1 y 50 elementos; como máximo 10 en la prueba por IP. Se conserva el orden de entrada. |
items[].type | string | Sí | — | Categoría de entrada: name, email o username. |
items[].value | string | Sí | — | 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. |
items[].country | string | No | — | 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. |
items[].forceToGenderize | boolean | No | false | Consulta primero el conjunto de datos y después la IA para apodos si no hay resultado. Compatible con name, email y username. |
items[].options | object | No | — | Objeto con las opciones de IA de cada entrada. |
items[].options.ai_mode | string | No | off | Valores permitidos: off, fallback, always. Con forceToGenderize: true, omite este campo o utiliza fallback. |
items[].id | string | No | — | 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 individuales aceptan este identificador pero no lo incluyen en la respuesta. Las consultas GET no lo admiten. |
GenderAPI.io V2 acepta nombres, correos y usuarios juntos en POST https://api.genderapi.io/api/v2/gender/batch. Envía un array items con entre 1 y 50 registros con clave de API, o hasta 10 en la prueba por IP. Cada registro utiliza type y value, y admite tus propios country, forceToGenderize y options. Los id son opcionales y deben ser únicos en el lote.
Los resultados conservan el orden de entrada. Cada uno contiene index, charged_credits y exactamente uno de data o error. Si enviaste un id, también se devuelve. HTTP 200 puede incluir errores por registro: revísalos todos. meta.summary contiene total, succeeded, identified, unknown y failed. Un resultado completado sin predicción se considera correcto y tiene coste.
Si la validación o la planificación de la solicitud falla, se rechaza todo el lote antes de deducir los créditos. Si todas las entradas fallan durante la ejecución, la API devuelve una respuesta de problema que no es 2xx con una matriz data y el alias heredado results. Las entradas fallidas cuestan cero créditos después de un reembolso confirmado. Si la facturación no está confirmada, no presupongas que el costo informado para cada entrada es definitivo.
Elige un lenguaje de programación. Configura tu clave API, luego ejecuta el ejemplo en tu servidor.
Cada solicitud de predicción es una nueva operación facturable, incluidos los reintentos. Estos ejemplos no se reintentan automáticamente. Comprueba el estado de facturación antes de enviar otra solicitud.
Antes de ejecutar: acceso y manejo de errores
Ejecuta estos ejemplos en tu servidor. Configura GENDERAPI_API_KEY en el entorno de proceso con tu clave API existente. Confirma que meta.access.mode es api_key: una clave no reconocida puede recurrir a la prueba IP.
Para las respuestas JSON HTTP 4xx y 5xx, los ejemplos conservan el cuerpo del error y salen con un estado distinto de cero. Comprueba code, action y meta.usage.billing_status antes de volver a intentarlo. Para una respuesta por lotes HTTP 200, revisa también data o error en cada resultado.
Guía de errores y reintentos →cURL 7.76+ en un shell POSIX. Ejecuta en tu terminal. Documentación del entorno de ejecución
Node.js 22+; fetch integrado. Guarda como example.mjs y ejecuta node example.mjs. Documentación del entorno de ejecución
Python 3.10+; biblioteca estándar. Guarda como example.py y ejecuta python3 example.py. Documentación del entorno de ejecución
PHP 8+ con la extensión cURL. Guarda como example.php y ejecuta php example.php. Documentación del entorno de ejecución
Java 17+; cliente estándar HTTP. Guarda como GenderApiExample.java y ejecuta java GenderApiExample.java. Documentación del entorno de ejecución
Aplicación de consola .NET 8+. Úsalo como Program.cs en un proyecto de consola, luego ejecuta dotnet run. Documentación del entorno de ejecución
Go 1.22+; biblioteca estándar. Guarda como main.go y ejecuta go run main.go. Documentación del entorno de ejecución
Leer una respuesta por lotes
Este ejemplo combina dos resultados reales capturados el 1 de octubre de 2026, una coincidencia de conjunto de datos y un resultado desconocido, con una falla del proveedor ilustrativa. Muestra una respuesta HTTP 200 de éxito parcial, no el resultado esperado de la solicitud por lotes anterior. Los dos elementos exitosos cuestan 1 crédito cada uno; el elemento fallido tiene un cargo cero confirmado.
{
"data": [
{
"index": 0,
"id": "known",
"charged_credits": 1,
"data": {
"input": {
"type": "name",
"value": "Carmen",
"country": "ES"
},
"name": "carmen",
"gender": "female",
"country": "ES",
"confidence": 0.9978779840848806,
"confidence_kind": "observed_frequency",
"sample_count": 1885,
"source": "dataset",
"result_status": "identified",
"reason": null,
"country_source": "dataset",
"match": {
"name": "carmen",
"method": "normalized",
"scope": "country",
"country": "ES"
}
}
},
{
"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
}
}
}Campos de los resultados por lotes
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
data | array<object> | No | […] | Resultados ordenados. Cada elemento contiene una predicción o un error; revíselos todos. |
data[].index | integer | No | 0 | Posición en el array items enviado, empezando por cero. |
data[].id | string | No | "contact-1" | Su identificador de entrada; solo aparece si lo proporcionó. |
data[].charged_credits | integer | No | 1 | Cobro neto del elemento tras reembolsos confirmados. No lo considere definitivo si el cobro global no está confirmado. |
data[].data | object | No | {…} | Presente en elementos correctos, incluidos resultados desconocidos. Usa los campos de predicción de la guía de respuestas. |
data[].error | object | No | {…} | Presente en elementos fallidos en lugar de data. Usa los campos Problem Details de la guía de errores. |
Campos del resumen del lote
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
meta.summary.total | integer | No | 3 | Número total de elementos del lote. |
meta.summary.succeeded | integer | No | 2 | Elementos correctos, incluidas predicciones desconocidas. |
meta.summary.identified | integer | No | 1 | Elementos correctos con género distinto de null. |
meta.summary.unknown | integer | No | 1 | Elementos correctos con género null; estos resultados se cobran. |
meta.summary.failed | integer | No | 1 | Elementos fallidos. total = succeeded + failed; succeeded = identified + unknown. |
Acceso, facturación y metadatos de la solicitud
| Campo | Tipo | ¿Admite null? | Ejemplo | Descripción |
|---|---|---|---|---|
meta.request_id | string | No | "550e8400-e29b-41d4-a716-446655440000" | Identificador único de este intento HTTP; también se envía en X-Request-ID. |
meta.duration_ms | integer | No | 42 | Tiempo de procesamiento de la solicitud en milisegundos. |
meta.access.mode | string | No | "api_key" | api_key, ip_trial o unauthenticated. Comprueba api_key para cualquier integración de cuenta, gratuita o de pago. |
meta.access.reason | string | Sí | null | Motivo del acceso de prueba: api_key_missing, api_key_invalid o api_key_not_found; null en otros casos. |
meta.usage.charged_credits | integer | Sí | 1 | Créditos netos cobrados. Cero antes del cobro o tras un reembolso completo confirmado; null si el cobro no está confirmado. |
meta.usage.remaining_credits | integer | Sí | 99 | Saldo al finalizar la operación. Puede ser negativo; null si no está disponible o el cobro no está confirmado. |
meta.usage.billing_status | string | No | "confirmed" | not_charged, confirmed o unconfirmed. Compruébelo antes de reintentar una predicción fallida. |
meta.usage.resets_at | string | Sí | "2026-09-27T12:00:00.000Z" | Reinicio de la prueba por IP en UTC (ISO 8601); null para cuentas con clave API o si se desconoce. |
meta.usage.limit | integer | Sí | 10 | Créditos de la prueba por IP; null para cuentas con clave API. |
meta.usage.period_seconds | integer | Sí | 86400 | Duración de la prueba por IP en segundos; null para cuentas con clave API. |
Planificar créditos y reintentos por lotes
Autentícate con tu clave actual mediante Bearer y envía Content-Type: application/json. Cada lote es una operación nueva. Si repites un lote parcialmente fallido, envía solo los registros fallidos después de comprobar el cobro; los registros completados se cobrarían de nuevo.
De forma predeterminada, las entradas por lotes utilizan off y cuestan 1 crédito por predicción completa. Seleccionar fallback también cuesta 1 crédito en total, incluida la IA. Seleccionar always cuesta 2 créditos. Con forceToGenderize, un género encontrado en el conjunto de datos cuesta 1 crédito; Usar IA cuesta 2 créditos en total. Las predicciones completadas con un género desconocido también cuestan créditos. Un saldo inicial de 1 crédito es suficiente para comenzar un lote. La deducción final podrá dejar el saldo negativo.
Procesa una lista y conserva la correspondencia de cada registro
El endpoint de lotes acepta listas de nombres, listas de correos o entradas mixtas. Divide el trabajo en grupos de hasta 50 registros con clave de API, o 10 en la prueba por IP. Conserva la posición de cada fila en tu lista original y asigna un id único dentro de cada lote. El index devuelto empieza en cero y corresponde al lote enviado, no a la lista completa.
| Paso | Qué guardar o comprobar | Por qué importa |
|---|---|---|
| 1. Prepara cada lote | Conserva la fila de origen y el id; configura country y las opciones de IA por registro. | Distintas personas pueden tener el mismo nombre. |
| 2. Lee toda la respuesta | Guarda meta.request_id y relaciona cada entrada de data[] mediante id o index. | HTTP 200 puede incluir tanto predicciones completadas como errores por registro. |
| 3. Guarda los resultados completados | Conserva las predicciones identified y unknown, los valores JSON null y los campos que explican su origen. | unknown es un resultado completado con coste, no un registro fallido que debas repetir automáticamente. |
| 4. Revisa los errores y los créditos | Comprueba cada error y meta.usage.billing_status antes de enviar otra solicitud. | Con el cobro confirmado, repite solo los registros fallidos cuyo error permita reintentar. Los registros completados se cobrarían de nuevo. |
| 5. Detén los reintentos inciertos | Conserva el identificador de solicitud si el cobro está unconfirmed o un fallo de red impide conocer el resultado. | No reenvíes todo el lote sin comprobarlo: sigue primero las guías de errores y cobro. |
Elige el modo de inferencia para cada registro
Este ejemplo ejecutable utiliza tres configuraciones: solo conjunto de datos para un nombre completo, fallback estándar para un correo y análisis de alias para un usuario. Son entradas de ejemplo; no garantizan obtener una predicción para los tres registros. Elige un lenguaje en las pestañas del código y configura GENDERAPI_API_KEY antes de ejecutarlo.
A diferencia de las consultas individuales, los registros de un lote sin forceToGenderize usan IA off de forma predeterminada. Envía fallback explícitamente para recurrir a la IA cuando sea necesario. off y fallback estándar cuestan 1 crédito por registro completado; always omite el conjunto de datos y cuesta 2. forceToGenderize cuesta 1 si el conjunto de datos ofrece una predicción, o 2 en total si se usa IA. Los resultados unknown completados también se cobran. No combines forceToGenderize con off ni always.
Elige un lenguaje de programación. Configura tu clave API, luego ejecuta el ejemplo en tu servidor.
Cada solicitud de predicción es una nueva operación facturable, incluidos los reintentos. Estos ejemplos no se reintentan automáticamente. Comprueba el estado de facturación antes de enviar otra solicitud.
Antes de ejecutar: acceso y manejo de errores
Ejecuta estos ejemplos en tu servidor. Configura GENDERAPI_API_KEY en el entorno de proceso con tu clave API existente. Confirma que meta.access.mode es api_key: una clave no reconocida puede recurrir a la prueba IP.
Para las respuestas JSON HTTP 4xx y 5xx, los ejemplos conservan el cuerpo del error y salen con un estado distinto de cero. Comprueba code, action y meta.usage.billing_status antes de volver a intentarlo. Para una respuesta por lotes HTTP 200, revisa también data o error en cada resultado.
Guía de errores y reintentos →cURL 7.76+ en un shell POSIX. Ejecuta en tu terminal. Documentación del entorno de ejecución
Node.js 22+; fetch integrado. Guarda como example.mjs y ejecuta node example.mjs. Documentación del entorno de ejecución
Python 3.10+; biblioteca estándar. Guarda como example.py y ejecuta python3 example.py. Documentación del entorno de ejecución
PHP 8+ con la extensión cURL. Guarda como example.php y ejecuta php example.php. Documentación del entorno de ejecución
Java 17+; cliente estándar HTTP. Guarda como GenderApiExample.java y ejecuta java GenderApiExample.java. Documentación del entorno de ejecución
Aplicación de consola .NET 8+. Úsalo como Program.cs en un proyecto de consola, luego ejecuta dotnet run. Documentación del entorno de ejecución
Go 1.22+; biblioteca estándar. Guarda como main.go y ejecuta go run main.go. Documentación del entorno de ejecución