Довідник API Media Examiner

Це переклад для зручності. Контракт API визначає англомовна версія довідника; у разі розбіжностей чинною є вона.

Media Examiner виявляє оголеність, відкриті інтимні частини тіла та сексуальні дії й водночас оцінює вік на вигляд і стадію розвитку — усе через один API для аналізу зображень. Одне зображення — один виклик: не потрібно поєднувати загальний класифікатор контенту для дорослих з окремим сервісом оцінювання віку.

Машинозчитуваний контракт опубліковано як документ OpenAPI 3.1 (англ.), тож клієнт можна згенерувати, а не писати вручну. Що роблять моделі й де їх застосовують, описано в огляді можливості. Якщо вам потрібен лише вік, окремий API оцінювання віку і далі доступний.

Вік на вигляд — це оцінка, а не перевірка. Вік на вигляд і стадія розвитку, які повертає сервіс, — це візуальні оцінки. Вони не підтверджують особу й не встановлюють юридичного віку людини. Рішення з високим ризиком і рішення в межових випадках мають передбачати належну перевірку людиною.

Швидкий старт

Хмарний сервіс доступний за адресою https://api.mes.rigr.ai. Надішліть зображення як дані форми multipart і ввімкніть оцінювання віку за допомогою estimate_age=true.

curl -X POST https://api.mes.rigr.ai/classify \
  -H "X-API-KEY: YOUR_KEY" \
  -F "[email protected]" \
  -F "model=VisualyzeV2" \
  -F "estimate_age=true"

Автентифікація

Кожен запит потребує ключа API. Сервіс приймає дві рівнозначні форми заголовка — використовуйте ту, що зручніша для вашого клієнта:

X-API-KEY: your_api_key_here
Authorization: Bearer your_api_key_here

Ключі видає Rigr AI — напишіть нам щодо пробного ключа.

Ендпоінти

Поля запиту

/classify і /predict приймають однакові поля multipart/form-data:

POST /classify

Повна інтегрована відповідь — класифікація на рівні зображення, результат виявлення інтимної частини тіла, результат виявлення сексуальних дій і обличчя з віком на вигляд та його невизначеністю:

{
  "classification": {
    "key": "rigr-penetrative",
    "display_name": "Penetrative sexual activity",
    "severity": 5
  },
  "flags": ["Self-Generated"],
  "detections": [
    {
      "class_name": "Male Receive Oral",
      "score": 0.87,
      "bbox": { "x": 0.12, "y": 0.45, "w": 0.31, "h": 0.62 },
      "ucs_sexual_content": "Penetrative Sexual Activity",
      "ucs_flags": ["Self-Generated"]
    },
    {
      "class_name": "Pubescent Breast",
      "score": 0.71,
      "bbox": { "x": 0.44, "y": 0.30, "w": 0.12, "h": 0.11 },
      "ucs_sexual_content": "Exploitative",
      "ucs_flags": []
    },
    {
      "class_name": "Pubescent Female Face",
      "score": 0.92,
      "bbox": { "x": 0.50, "y": 0.17, "w": 0.09, "h": 0.18 },
      "ucs_sexual_content": null,
      "ucs_flags": [],
      "age": 14.8,
      "age_uncertainty": 2.1,
      "original_class_name": "Prepubescent Female Face"
    }
  ],
  "filename": "image.jpg",
  "model": "VisualyzeV2",
  "sha256": "d2ff9e6b..."
}

Обмежувальні рамки в /classify і /predict нормалізовані: x/y/w/h з початком координат у верхньому лівому куті — це об’єкт, а не пара кутових точок, а значення задано частками кадру, а не в пікселях. Щоб намалювати рамки, помножте значення на ширину й висоту кадру. Виняток — /detect-age: він повертає [x_min, y_min, x_max, y_max] у пікселях, бо повторює схему окремого сервісу оцінювання віку.

Шкала серйозності

Рівень серйозності — це найвищий рівень, на який указує будь-який окремий результат виявлення на зображенні.

Шкала має рівні 0, 2, 3, 4, 5 — класифікатор ніколи не повертає 1. Рівень 1 існує в ширшій шкалі перегляду як висновок аналітика (відверті матеріали з дорослими, які під час перегляду визнано нешкідливими); жодна модель його не присвоює. Ураховуйте це в операторах switch. Це шкала первинного сортування, а не встановлена законом: категорії й пороги залежать від юрисдикції, тож зіставте її з правилами, за якими працює ваша команда, а не вважайте будь-який окремий рівень універсальною межею для ухвалення рішення.

Контекстні позначки

Позначки не залежать від рівня серйозності — вони описують характер матеріалу, а не те, наскільки він відвертий. Сервіс повертає чотири значення: Self-Generated, Sadomasochism, CG Elements і Bodily Fluids.

Вік на вигляд і стадія розвитку

Якщо задано estimate_age=true, окрема модель оцінювання віку за обличчям у тому самому проході обробляє кожне виявлене обличчя. Кожен результат виявлення обличчя отримує поля age і age_uncertainty. Модель віку точніша за власні мітки вікових груп детектора, тож там, де вони розходяться, class_name замінюється, а початкова мітка детектора зберігається в original_class_name.

У age_uncertainty і полягає сенс калібрування: це поле дає змогу маршрутизувати, а не вгадувати. Щодо вузького інтервалу, що лежить далеко від вашого порогу, рішення можна ухвалити автоматично; широкий інтервал, що охоплює поріг, слід передати на розгляд людині. Якщо вважати точкову оцінку остаточним висновком і відкидати невизначеність, втрачається саме той сигнал, який найбільше потрібен у межових випадках.

POST /detect-age

Виявляє обличчя й оцінює їхній вік; нічого іншого не повертає. Схема збігається зі схемою окремого сервісу оцінювання віку Rigr, тож клієнтові, уже створеному для того сервісу, для переходу достатньо змінити URL.

{
  "error": null,
  "results": [
    {
      "idx": 0,
      "error": null,
      "results": [
        { "idx": 0, "age": 14.8, "uncertainty": 2.1,
          "bbox": [320, 85, 378, 171], "score": 0.9234,
          "source": "Pubescent Female Face" }
      ]
    }
  ]
}

results містить по одному запису на кадр; для статичного зображення це один запис з індексом 0. Для цього ендпоінта виявлення облич за замовчуванням використовує поріг score, що дорівнює 0.6, а не 0.25: якість виражається через невизначеність для кожного обличчя, а не через відкидання облич на етапі виявлення.

POST /estimate-age

Надішліть вирізане зображення обличчя в полі file; виявлення об’єктів не виконується.

{ "age": 14.8, "uncertainty": 2.1, "age_bracket": "Pubescent" }

Вимоги до зображень

Час обробки анімованих файлів зростає приблизно лінійно з кількістю кадрів, тож довгий GIF може оброблятися десятки секунд. Розраховуйте тайм-аути клієнта за кількістю кадрів, а не за розміром файлу, і додавайте мережеву затримку та запас часу.

Обмеження частоти запитів

Стандартна квота — 120 запитів за 60 секунд на один ключ API. Кожна відповідь містить x-rate-limit-remaining, а відповідь 429 — ще й retry_after_seconds. Повторюйте спроби з експоненційною затримкою: 1 с, 2 с, 4 с і так далі до 30 с. Якщо вам потрібен більший запас, зв’яжіться з нами: квота залежить від тарифного плану й не є жорстким обмеженням сервісу.

Обробка помилок

Розгортання

Хмарний сервіс. Найшвидший спосіб випробувати Media Examiner — https://api.mes.rigr.ai; налаштовувати інфраструктуру не потрібно.

Контейнер та ізольоване середовище (air-gapped). Media Examiner постачається як контейнер із тим самим REST API, а також з інтерфейсом gRPC для потокового завантаження, тож змінюється лише хост. Саме так його розгортають там, де матеріали не можуть залишати будівлю. Зв’яжіться з нами, щоб отримати доступ до реєстру й рекомендації щодо розгортання.

Як отримати доступ

Написати нам щодо пробного ключа Завантажити документ OpenAPI

Також доступні: огляд можливості класифікації CSAM, сторінка рішення для команд з безпеки контенту (trust & safety) про робочі процеси модерації та спрямування матеріалів на перевірку людиною, а також довідник API окремого сервісу оцінювання віку.