Centro de ayuda de GenderAPI.io V2
Preguntas frecuentes
Respuestas sobre las consultas V2, la confianza, los resultados sin predicción, los créditos, la privacidad y tu cuenta. Consulta la referencia V1 si mantienes una integración de la versión anterior.
Resultados y confianza
Comprende las predicciones y sus límites
Contexto de país, puntuaciones de confianza y resultados desconocidos en V2.
¿Una predicción de GenderAPI identifica el género de una persona?
No. GenderAPI estima el género a partir de indicios relacionados con nombres o, si se activa esa opción, con alias. Una predicción no es un dato personal verificado. Conserva la incertidumbre, respeta la identidad declarada por cada persona y no utilices la estimación como único criterio para decisiones de gran impacto.
¿Cómo influye el país en el resultado?
Un código de país ISO opcional en mayúsculas aporta contexto regional a la consulta. Envíalo solo si lo conoces y es pertinente. Un mismo nombre puede tener usos diferentes según la región; el país devuelto indica una asociación del nombre, no demuestra la nacionalidad ni la residencia de la persona.
¿Qué significa la puntuación de confianza de V2?
confidence contiene un valor entre 0 y 1, o null si no está disponible. Interprétalo junto con confidence_kind: observed_frequency es el recuento de la categoría dominante dividido entre el total del conjunto de datos; model_reported es una puntuación declarada por la IA. No son probabilidades calibradas sobre una persona ni una medida de la precisión del producto. Define tus umbrales de revisión con datos representativos.
¿Qué significa gender: null y tiene coste?
Un resultado V2 procesado correctamente con gender: null indica que la información disponible no permitió obtener una predicción. Es el valor null nativo de JSON, no la cadena "null". Un resultado completado sin predicción se cobra según la tarifa seleccionada. Consérvalo como desconocido; un fallo del proveedor o de la solicitud es un error distinto.
¿Puedo enviar nombres en distintos sistemas de escritura?
Sí. Envía nombres Unicode con sus caracteres y acentos originales. La cobertura y la confianza varían según el nombre, la región y la información disponible. Prueba una muestra representativa de los sistemas de escritura y países con los que trabaja tu aplicación.
API e IA
Elige el tipo de consulta y las opciones de IA
Entradas de V2, lotes, comportamiento de la IA y límites de uso.
¿Puedo analizar nombres, correos y usuarios en un mismo lote?
Sí. POST /api/v2/gender/batch admite hasta 50 registros con clave de API o 10 en la prueba por IP. Cada registro tiene sus propios type, value, country opcional y ajustes de IA. Por defecto, la IA está desactivada en los lotes. Revisa cada resultado: un lote puede devolver HTTP 200 con errores en algunos registros. Se cobran los registros procesados correctamente, incluidos los resultados sin predicción.
¿Cómo funciona una consulta por correo electrónico?
Utiliza type: email con una dirección válida. La API busca pistas de nombre en la parte anterior a @; el dominio no determina la identidad ni el país de una persona. Los buzones compartidos y las direcciones sin pistas reconocibles pueden devolver un resultado desconocido. En consultas individuales, se recurre a la IA de forma predeterminada si el conjunto de datos no ofrece una predicción.
¿Cómo funciona una consulta por nombre de usuario?
Utiliza type: username. La consulta estándar busca un nombre reconocible en el identificador o nombre mostrado. Los alias abstractos pueden devolver un resultado desconocido. Activa forceToGenderize para analizar alias con IA cuando el conjunto de datos no resuelva la consulta; esta opción puede obtener una predicción sin extraer un nombre real.
¿Cuándo utiliza IA V2?
Las consultas individuales usan por defecto options.ai_mode: fallback: primero consultan el conjunto de datos y, si no hay predicción, recurren a la IA por 1 crédito en total. off consulta solo el conjunto de datos por 1 crédito; always utiliza directamente IA por 2 créditos. En los lotes, el valor predeterminado es off y la IA se puede activar por registro. Ningún modo garantiza un resultado distinto de null.
¿Para qué sirve forceToGenderize?
Esta opción funciona con nombres, correos electrónicos y nombres de usuario, también en cada registro de un lote. Una predicción del conjunto de datos cuesta 1 crédito. Si no se obtiene, se utiliza IA para interpretar alias por 2 créditos en total, incluso si la operación se completa sin predicción. No es necesario que la entrada contenga un nombre real. Omite ai_mode o utiliza fallback; combinar esta opción con off o always devuelve 422.
¿Cómo se descuentan los créditos en V2?
Consulta meta.usage.charged_credits para conocer el cargo neto de la operación y billing_status para comprobar su confirmación. Las consultas estándar al conjunto de datos y con fallback cuestan 1 crédito por registro completado; always y el análisis de alias mediante IA cuestan 2. La validación de teléfono completada cuesta 1, incluso con resultado no válido. Basta con un saldo inicial positivo, por lo que el cargo final puede dejarlo en negativo. Los fallos de predicción se reembolsan; si el cobro no está confirmado, solicita una revisión a soporte.
¿V2 tiene límites de solicitudes?
Sí. Los valores predeterminados actuales incluyen 120 solicitudes por minuto y cuenta, 600 por minuto e IP y 2 operaciones simultáneas por cuenta. También se aplica la capacidad compartida del servicio. El cuerpo de las solicitudes POST está limitado a 64 KiB; los lotes admiten 50 registros con clave o 10 en la prueba por IP. Respeta HTTP 429 y Retry-After: estos límites no garantizan que todas las solicitudes se acepten hasta alcanzar ese máximo.
¿Puedo repetir una solicitud fallida o que haya agotado el tiempo de espera?
Cada solicitud de predicción es una operación nueva y se cobra normalmente. Un tiempo de espera agotado o una respuesta perdida no demuestran que no haya habido un cargo. Comprueba billing_status antes de repetirla; si el cobro no está confirmado, contacta con soporte e incluye request_id. En un lote parcialmente fallido, repite solo los registros fallidos una vez confirmado el cobro. Ante HTTP 429, sigue Retry-After.
¿Dónde están los ejemplos de código y las herramientas de V2?
Las guías V2 incluyen ejemplos en cURL, JavaScript, Python, PHP, Java, C# y Go. Swagger y Postman utilizan el mismo contrato V2. Elige el tipo de entrada y guarda la clave de API en la configuración del servidor.
¿Puedo seguir utilizando V1?
Sí. Las integraciones V1 existentes conservan sus endpoints y formatos de respuesta. V1 y V2 comparten la clave de API y el saldo, pero sus campos de solicitud, respuestas y errores son diferentes. Utiliza la referencia V1 para mantener una integración existente y la guía de migración cuando decidas actualizarla.
Privacidad y archivos
Comprende cómo se tratan los datos
Dónde consultar la información vigente sobre procesamiento, conservación y eliminación.
¿Se almacenan las consultas realizadas a GenderAPI?
La Política de Privacidad explica qué registros de consultas, operación y seguridad pueden conservarse, para qué se procesan y cómo funciona su eliminación. Revisa esos detalles para tu integración y evita enviar datos personales innecesarios.
¿Se almacenan las direcciones de correo utilizadas en las consultas?
Consulta la Política de Privacidad para conocer el tratamiento actual de las direcciones de correo y los registros técnicos relacionados. Una dirección puede ser un dato personal: envía solo lo necesario para la consulta y evita incluir direcciones completas en tus registros de diagnóstico.
¿Cuánto tiempo se conservan los archivos Excel o CSV subidos?
La Política de Privacidad describe la conservación, eliminación y gestión de copias de seguridad de los archivos subidos. Exporta los resultados que necesites y utiliza las opciones de eliminación del espacio de trabajo cuando ya no necesites el archivo. Contacta con soporte si tu organización tiene requisitos específicos de conservación.
¿Los proveedores de servicios pueden procesar consultas o archivos subidos?
La Política de Privacidad y la información sobre subencargados del tratamiento describen el procesamiento por proveedores y las medidas de protección aplicables. Revisa esos recursos y los acuerdos de tu cuenta al evaluar dónde se procesan tus datos.
Política de Privacidad →Subencargados del tratamiento →Información sobre el RGPD →
Cuenta y soporte
Conecta tu clave y gestiona tu cuenta
Acceso gratuito, autenticación, consulta de saldo y soporte.
¿Puedo probar GenderAPI gratis?
Sí. Una cuenta gratuita incluye 200 créditos diarios. Por separado, la prueba V2 sin clave ofrece 10 créditos por IP pública durante 24 horas, compartidos con V1 y otras personas que utilicen esa IP. En ambos casos se aplican las tarifas habituales; el número de créditos no siempre coincide con el número de solicitudes HTTP.
¿Cómo me autentico y protejo mi clave de API?
Utiliza Authorization: Bearer YOUR_API_KEY desde código de servidor de confianza; las solicitudes POST también requieren Content-Type: application/json. No incluyas la clave real en código de navegador, repositorios públicos ni registros. Las claves ausentes, mal formadas o desconocidas pueden utilizar la prueba por IP, por lo que debes comprobar que meta.access.mode sea api_key. Las claves conocidas desactivadas, caducadas o restringidas no pasan a la prueba.
¿Cómo consulto los créditos restantes?
Envía GET /api/v2/usage con tu clave Bearer. Esta consulta de saldo es gratuita y devuelve data.remaining_credits. Sin clave, consulta el saldo de la prueba por IP. V1 y V2 comparten el saldo de la cuenta; el valor remaining_credits de una predicción refleja el saldo al terminar esa operación.
¿Dónde puedo gestionar o cancelar una suscripción?
Inicia sesión en la aplicación de GenderAPI para gestionar la suscripción asociada a tu clave de API. Utiliza los controles actuales de la cuenta para consultar el plan y las opciones de cancelación.
¿Dónde puedo actualizar los datos de facturación?
Gestiona la configuración de facturación y pagos desde la aplicación de GenderAPI, tras iniciar sesión en la cuenta de la clave de API o suscripción correspondiente.
¿Cómo notifico un resultado incorrecto o solicito ayuda para integrar la API?
Envía a soporte la versión de la API, el endpoint, request_id y un ejemplo mínimo que permita reproducir el problema. Incluye el código de error si está disponible, pero elimina la clave de API y los datos personales sensibles.
Base de conocimientos técnica
Guías de implementación y uso responsable
Respuestas sobre resultados, privacidad y operaciones de V2, con enlaces a las guías y una versión en Markdown de cada respuesta.
Resultados, confianza y uso responsable
Una predicción V2 sin resolver utiliza el valor null nativo de JSON para gender, no la cadena "null". El nombre puede ser ambiguo o la información disponible insuficiente; consulta result_status y reason cuando esté presente. Conserva el resultado desconocido en lugar de forzar una categoría. Una operación completada sin predicción se cobra según la tarifa seleccionada. Los errores de solicitud o del proveedor son fallos distintos, con información de cobro en meta.usage.
Leer la respuesta completa →¿Cómo se evalúa la precisión de GenderAPI?Una evaluación útil indica la población de prueba, la fecha, el método de muestreo, la proporción de resultados desconocidos y los resultados por región y sistema de escritura. La página de metodología actual describe un protocolo de evaluación, no un porcentaje de precisión medido. Los campos confidence y confidence_kind de V2 explican el fundamento de cada resultado; no sustituyen una evaluación con datos representativos.
Leer la respuesta completa →Fuentes de datos, privacidad y cumplimiento
La página de procedencia de datos describe el marco para documentar las categorías de fuentes, los criterios de selección, las licencias y las limitaciones geográficas o de escritura. Actualmente no publica un catálogo de fuentes revisado. Consúltala y contacta con soporte para aclarar los requisitos de tu integración; no presupongas fuentes, tamaños de conjuntos de datos ni cifras de cobertura que no estén documentados.
Leer la respuesta completa →¿Con qué frecuencia se actualizan los datos de nombres?La página actual de procedencia de datos no establece un único calendario de actualización para todos los registros o reglas de procesamiento. Si la antigüedad de los datos afecta a tu caso de uso, consulta a soporte sobre el conjunto de datos o flujo concreto y evalúa resultados representativos. La fecha de revisión de una página no demuestra que todos los registros se hayan actualizado ese día.
Leer la respuesta completa →¿Dónde consulto la información sobre el RGPD y el acuerdo de tratamiento de datos?La Política de Privacidad, la información sobre el RGPD, el Acuerdo de Tratamiento de Datos y el registro de subencargados describen las condiciones y medidas de protección publicadas. Revisa los documentos vigentes y los acuerdos aplicables a tu cuenta. Contacta con GenderAPI para cuestiones de tu organización sobre roles de tratamiento, transferencias o solicitudes de derechos; una respuesta general no sustituye el acuerdo aplicable.
Leer la respuesta completa →Operaciones de API, errores y facturación
Utiliza Authorization: Bearer YOUR_API_KEY desde código de servidor de confianza. Las solicitudes POST de V2 también requieren Content-Type: application/json. GET /api/v2/gender admite además el parámetro key en la URL, aunque usar la cabecera evita exponer la credencial en URLs del navegador. Las claves ausentes, mal formadas o desconocidas pueden utilizar la prueba compartida por IP; comprueba que meta.access.mode sea api_key en una integración de cuenta. Las claves conocidas desactivadas, caducadas o restringidas no pasan a la prueba.
Leer la respuesta completa →¿Cómo gestiono los límites de solicitudes y los reintentos?V2 aplica límites de frecuencia y de solicitudes simultáneas; respeta HTTP 429 y Retry-After. Cada predicción repetida es una nueva operación con el coste habitual. No repitas automáticamente una solicitud si se agotó el tiempo de espera, se perdió la respuesta o el cobro no está confirmado. Revisa antes code, action y meta.usage.billing_status; ante billing_reconciliation_required, contacta con soporte e incluye request_id. Utiliza reintentos limitados con esperas progresivas solo cuando el cobro esté confirmado y la acción documentada permita un nuevo intento.
Leer la respuesta completa →¿Cómo interpreto los errores de V2?Los errores V2 utilizan estados HTTP de error y Problem Details conforme a RFC 9457, con campos code y action estables. Interpreta esos campos en lugar de comparar el texto de detail y conserva request_id para soporte. Un resultado completado sin predicción es distinto de un error. Un lote puede contener errores por registro aunque devuelva HTTP 200. Un proxy puede devolver un error que no sea JSON; una respuesta perdida o ilegible no demuestra que no se haya realizado un cargo.
Leer la respuesta completa →¿Cómo consulto los créditos restantes?Envía GET /api/v2/usage con tu clave Bearer desde código de servidor de confianza. Es gratuito y devuelve data.remaining_credits; sin clave, consulta la prueba compartida por IP. V1 y V2 utilizan el mismo saldo de cuenta. meta.usage de una predicción indica el cargo y el saldo al finalizar esa operación, que puede cambiar con solicitudes simultáneas. No incluyas credenciales en los registros ni interpretes una consulta de saldo como prueba de que una solicitud cuya respuesta se perdió no tuvo coste.
Leer la respuesta completa →¿Cómo paso de V1 a V2 sin romper mi integración?Utiliza V2 para nuevas integraciones y conserva las rutas documentadas de tus clientes V1 hasta que decidas migrarlos. Ambas versiones comparten claves de API y créditos, pero sus campos de solicitud, estructuras de respuesta y errores son diferentes. Sigue la guía de migración, prueba resultados con predicción, desconocidos y errores, y actualiza el código que interpreta las respuestas antes de cambiar los endpoints. La referencia V1 sigue disponible.
Leer la respuesta completa →¿Cómo compruebo los fallos y la disponibilidad del servicio?Si una solicitud falla, utiliza el código de error para distinguir un fallo del servicio de problemas de entrada, acceso a la cuenta, créditos agotados o límites de solicitudes. Supervisa el éxito y la latencia de las solicitudes de tu integración. Contacta con soporte e incluye request_id ante un fallo sin explicación o un cobro incierto. Las afirmaciones de disponibilidad deben apoyarse en mediciones; esta respuesta no establece un porcentaje garantizado de disponibilidad.
Leer la respuesta completa →¿Aún necesitas ayuda?
Envíanos un ejemplo reproducible
Incluye el endpoint, los parámetros y el error devuelto, pero no compartas tu clave API de producción ni información personal sensible.