Перейти к основному содержимому

API определения возраста по изображению

Загрузите изображение, чтобы обнаружить людей и лица и оценить возраст с указанием процента уверенности для каждого обнаруженного объекта.

Базовый URL​

https://api.genderrecognition.com

Конечная точка​

POST /v1/image-gender/api/age

Заголовки​

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

Тело запроса​

ПолеТипОбязательноОписание
fileфайлДаИзображение JPEG, PNG, WebP, BMP или GIF. Максимальный размер: 10 МБ.

Пример​

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

Успешный ответ​

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

Поля ответа​

ПолеТипОписание
successbooleantrue, если обработка изображения прошла успешно.
detectionsarrayОтдельная запись для каждого обнаруженного лица с прогнозом возраста.
detections[].agenumberПрогноз возраста для объекта. Может быть дробным числом.
detections[].probabilityintegerУверенность в процентах от 0 до 100. См. примечание ниже.
remainingRequestsintegerКоличество запросов API после списания за этот успешный запрос.

probability отражает уверенность модели в классификации пола для этого объекта и используется как показатель уверенности в ответе. Отдельную оценку уверенности именно для возраста модель не выдаёт. Высокое значение probability означает, что модель уверена в определении пола человека, но не в точности значения age.

В ответ включаются только объекты, для которых модель уверенно определила пол. Лицо с неоднозначным прогнозом пола или без соответствия не включается в detections, даже если человек или лицо были визуально обнаружены, поэтому число элементов detections может быть меньше числа лиц на изображении.

Объекты не обнаружены​

Обработка может завершиться успешно, даже если не найдено лицо с достаточно уверенным прогнозом. При этом всё равно расходуется один запрос:

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

Ответы с ошибками​

Отсутствует ключ API — 401 Unauthorized​

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

Недействительный ключ API — 404 Not Found​

{
  "error": "Invalid API key"
}

Ошибка службы аутентификации — 500 Internal Server Error​

{
  "error": "Internal server error"
}

Отсутствует файл — 400 Bad Request​

Имя поля multipart должно быть file.

{
  "error": "No file uploaded"
}

Неожиданное поле multipart — 400 Bad Request​

Этот ответ возвращается, если для файла указано имя поля, отличное от file, либо если в поле для одного файла передано несколько файлов.

{
  "error": "Unexpected field"
}

Недопустимый формат файла — 400 Bad Request​

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

Файл слишком велик — 400 Bad Request​

{
  "error": "File too large"
}

Не удалось декодировать изображение — 400 Bad Request​

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

Служба прогнозирования также может вернуть другое сообщение проверки с кодом 400, если загруженное изображение некорректно. Формат ответа остаётся { "error": "..." }.

Служба прогнозирования отклонила файл из-за размера — 413 Payload Too Large​

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

Квота исчерпана — 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."
  }
}

Для платных планов используется та же структура ответа с ограничениями и датами сброса, характерными для плана, а также рекомендациями по переходу на другой план.

Квота изменилась во время обработки — 400 Bad Request​

Квота проверяется до прогноза и списывается после успешной обработки. Если другой параллельный запрос израсходует остаток квоты между этими операциями, списание может вернуть ошибку:

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

Ошибка обработки — 500 Internal Server Error​

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

Если служба прогнозирования вернёт более подробную внутреннюю ошибку, её сообщение может быть указано в поле error с той же структурой ответа.

Примечания​

  • Передавайте ровно одно изображение в multipart-поле file.
  • Запрос списывается только после успешного ответа службы прогнозирования.
  • Значение age может быть дробным; probability указывается целым числом в процентах, а не десятичным числом от 0 до 1.
  • probability отражает уверенность классификации пола, а не точность оценки возраста; отдельная оценка уверенности для возраста не предоставляется.
  • Пустой массив detections означает успешный результат, а не ошибку.
  • Прогнозы являются оценками модели, а не подтверждёнными характеристиками личности.