Pular para o conteúdo principal

API de estimativa de idade por imagem

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

URL base​

https://api.genderrecognition.com

Endpoint​

POST /v1/image-gender/api/age

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/age" \
  -H "apiKey: YOUR_API_KEY" \
  -F "file=@people.jpg"

Resposta bem-sucedida​

{
  "success": true,
  "detections": [
    {
      "age": 27.4,
      "probability": 99
    },
    {
      "age": 41.2,
      "probability": 94
    }
  ],
  "remainingRequests": 2999
}

Campos da resposta​

CampoTipoDescrição
successbooleanotrue quando a imagem foi processada com sucesso.
detectionslistaUma entrada para cada rosto detectado com uma estimativa de idade.
detections[].agenúmeroIdade estimada para a detecção. Pode conter casas decimais.
detections[].probabilityinteiroPorcentagem de confiança de 0 a 100. Consulte a observação abaixo.
remainingRequestsinteiroSolicitações de API restantes após descontar esta solicitação bem-sucedida.

probability representa a confiança do modelo na classificação de gênero daquela detecção e é reutilizada como valor de confiança na resposta. O modelo não produz uma pontuação de confiança separada para a estimativa de idade. Um valor alto de probability indica a certeza do modelo sobre o gênero da pessoa, não sobre a precisão de age.

A resposta inclui apenas detecções para as quais o modelo classificou o gênero com confiança. Um rosto com previsão de gênero ambígua ou sem correspondência é omitido de detections, mesmo que a pessoa ou o rosto tenha sido detectado visualmente. Por isso, detections pode conter menos itens do que o número de rostos na imagem.

Nenhuma detecção​

O processamento pode ser concluído sem encontrar um rosto com uma previsão confiá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 age 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.
  • age pode ser um valor decimal; probability é uma porcentagem inteira, não um valor decimal entre 0 e 1.
  • probability indica a confiança da classificação de gênero, não da estimativa de idade; não há uma pontuação específica de confiança para idade.
  • 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.