Pular para o conteúdo principal

API de identificação de gênero por imagem

Envie uma imagem para detectar pessoas e rostos e estimar o gênero de cada detecção, acompanhada de uma porcentagem de confiança.

URL base​

https://api.genderrecognition.com

Endpoint​

POST /v1/image-gender/api

Cabeçalhos​

apiKey: YOUR_API_KEY
Content-Type: multipart/form-data

Corpo​

CampoTipoObrigatórioDescrição
filearquivoSimImagem JPEG, PNG, WebP, BMP ou GIF. Tamanho máximo: 10 MB.

Exemplo​

curl -X POST "https://api.genderrecognition.com/v1/image-gender/api" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

Resposta bem-sucedida​

{
  "success": true,
  "detections": [
    {
      "category": "face",
      "gender": "female",
      "probability": 99
    },
    {
      "category": "person",
      "gender": "male",
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

Campos da resposta​

CampoTipoDescrição
successbooleanotrue quando a imagem foi processada com sucesso.
detectionslistaUma entrada para cada rosto detectado ou pessoa sem correspondência, com uma previsão.
detections[].categoryface | personface quando um rosto corresponde a uma pessoa; person quando só há um corpo.
detections[].gendermale | femaleGênero estimado para a detecção.
detections[].probabilityinteiroPorcentagem de confiança de 0 a 100.
remainingRequestsinteiroSolicitações de API restantes após descontar esta solicitação bem-sucedida.

Quando o rosto e o corpo pertencem à mesma pessoa, a resposta contém uma única detecção face, em vez de entradas separadas para o rosto e a pessoa.

Nenhuma detecção​

O processamento pode ser concluído sem encontrar um rosto ou uma pessoa utilizável. Mesmo assim, uma solicitação é descontada:

{
  "success": true,
  "detections": [],
  "remainingRequests": 2999
}

Respostas de erro​

Chave de API ausente — 401 Unauthorized​

{
  "error": "API key is required"
}

Chave de API inválida — 404 Not Found​

{
  "error": "Invalid API key"
}

Erro do serviço de autenticação — 500 Internal Server Error​

{
  "error": "Internal server error"
}

Arquivo ausente — 400 Bad Request​

O campo multipart deve se chamar file.

{
  "error": "No file uploaded"
}

Campo multipart inesperado — 400 Bad Request​

Esta resposta é retornada quando o arquivo enviado usa um campo diferente de file ou quando mais de um arquivo é enviado no campo destinado a um único arquivo.

{
  "error": "Unexpected field"
}

Tipo de arquivo inválido — 400 Bad Request​

{
  "error": "Invalid file type. Allowed formats: JPEG, PNG, WEBP, BMP, GIF"
}

Arquivo muito grande — 400 Bad Request​

{
  "error": "File too large"
}

Não foi possível decodificar a imagem — 400 Bad Request​

{
  "error": "Could not decode image"
}

O serviço de previsão também pode retornar outra mensagem de validação 400 quando a imagem enviada for inválida. A resposta mantém o mesmo formato { "error": "..." }.

Rejeição por tamanho do serviço de previsão — 413 Payload Too Large​

{
  "error": "Uploaded file exceeds the 10MB size limit"
}

Cota excedida — 400 Bad Request​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your free tier limit of 50 requests.",
    "detailedMessage": "Insufficient remaining requests. Required: 1, Available: 0",
    "details": {
      "limit": 50,
      "used": 50,
      "reset_date": "2026-07-01T00:00:00.000Z"
    },
    "suggested_action": "Please upgrade to a premium plan to continue using the API."
  }
}

Os planos pagos usam a mesma estrutura de resposta, com limites, datas de renovação e orientações de upgrade específicos do plano.

Cota alterada durante o processamento — 400 Bad Request​

A cota é verificada antes da previsão e descontada após o processamento bem-sucedido. Se outra solicitação simultânea consumir a cota restante nesse intervalo, a tentativa de desconto poderá retornar:

{
  "error": "Insufficient remaining requests. Required: 1, Available: 0"
}

Falha no processamento — 500 Internal Server Error​

{
  "error": "Image gender prediction failed"
}

Se o serviço externo de previsão retornar um erro interno mais específico, a mensagem poderá aparecer no campo error, mantendo o mesmo formato de resposta.

Observações​

  • Envie exatamente uma imagem no campo multipart chamado file.
  • A solicitação só é descontada depois que o serviço de previsão retorna com sucesso.
  • probability é uma porcentagem inteira, não um valor decimal entre 0 e 1.
  • Uma lista detections vazia indica um resultado bem-sucedido, não um erro.
  • As previsões são estimativas do modelo e não devem ser consideradas uma identidade verificada. attributes.