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

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

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

Базовый URL​

https://api.genderrecognition.com

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

POST /v1/image-gender/api

Заголовки​

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

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

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

Поля ответа​

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

Если лицо и тело принадлежат одному человеку, ответ содержит одну запись face, а не отдельные записи для лица и человека.

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

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

{
  "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 gender prediction failed"
}

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

Примечания​

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