API de gênero pelo nome – Solicitação individual

Visão geral da solicitação

Envie um nome por solicitação

Envie um objeto JSON com o primeiro nome e autentique-se com um token Bearer. Adicione um código de país quando os padrões regionais de nomes puderem melhorar a estimativa.

MétodoPOST

Tipo de conteúdoapplication/json

AutenticaçãoBearer token

Custo em créditos1 consulta

HDR

Cabeçalhos HTTP obrigatórios

Autorize a solicitação

Content-Typeapplication/json

AuthorizationBearer YOUR_API_KEY

Mantenha a chave de API em variáveis de ambiente no servidor. Consulte o guia de autenticação para proteger suas credenciais.

Corpo JSON da solicitação

Parâmetros

Parâmetro	Tipo	Obrigatoriedade	Descrição
`name`	string	Obrigatório	Primeiro nome a analisar. Use um valor limpo, sem títulos ou prefixos.
`country`	string	Opcional	Código de país ISO 3166-1 alfa-2, como BR ou US, para adicionar contexto regional.
`askToAI`	boolean	Opcional	Quando true, usa a IA como alternativa se o nome não for encontrado no banco de dados.
`forceToGenderize`	boolean	Opcional	Quando true, tenta obter um resultado para apelidos ou entradas que não se parecem com nomes comuns.

Sobre o suporte de IA

askToAI é usado somente quando o banco de dados não retorna resultado. Estimativas forçadas para entradas incomuns podem ser menos confiáveis; portanto, considere a probabilidade um sinal importante.

Exemplos de código

Faça uma solicitação individual

Estes exemplos enviam a mesma solicitação usando autenticação Bearer.

cURL

curl -X POST "https://api.genderapi.io/api" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"name":"Alice","country":"US","askToAI":true}'

JavaScript

const response = await fetch("https://api.genderapi.io/api", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({ name: "Alice", country: "US", askToAI: true })
});

const data = await response.json();

Python

import requests

response = requests.post(
  "https://api.genderapi.io/api",
  headers={"Authorization": "Bearer YOUR_API_KEY"},
  json={"name": "Alice", "country": "US", "askToAI": True}
)
print(response.json())

Resposta 200

Resultado da estimativa

JSON

{
  "status": true,
  "used_credits": 1,
  "remaining_credits": 4999,
  "expires": 1743659200,
  "q": "Alice",
  "name": "Alice",
  "gender": "female",
  "country": "US",
  "total_names": 10234,
  "probability": 98,
  "duration": "4ms"
}

Campos da resposta

Campo	Tipo	Descrição
`status`	boolean	Indica se a solicitação foi concluída com sucesso.
`used_credits`	integer	Créditos consumidos por esta solicitação.
`remaining_credits`	integer	Créditos disponíveis após a solicitação.
`expires`	integer	Data de expiração do pacote em formato de timestamp UNIX.
`q`	string	Nome original enviado na solicitação.
`name`	string	Nome analisado pela GenderAPI.
`gender`	string \| null	Valor estimado: male, female ou null.
`country`	string	Código de país considerado na estimativa.
`total_names`	integer	Quantidade de amostras que sustentam a estimativa.
`probability`	integer	Probabilidade da estimativa em porcentagem.
`duration`	string	Tempo de processamento no servidor.

Envie uma entrada limpa e codificada corretamente

Use um primeiro nome sem títulos ou prefixos. Clientes JSON fazem a codificação automaticamente, mas sempre valide entradas externas antes de criar o corpo da solicitação.

Próximo guia

Analise vários nomes

Solicitação de vários nomesProcesse vários nomes em uma solicitação →AutenticaçãoRevisar a segurança da chave de API →