> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Оценка возраста API: проверка возраста по селфи > Didit: AI-оценка возраста с пассивной проверкой живости без документов. POST /v3/age-estimation/, ответ за 2s, оплата за использование. ## OpenAPI ````yaml ru/openapi-25.json POST /v3/age-estimation/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: >- API верификации личности. Аутентификация выполняется с помощью заголовка x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/age-estimation/: post: tags: - Standalone APIs summary: Оценка возраста (возраст по лицу + пассивная проверка живости) description: >- Оцените возраст человека по одной фотографии лица и запустите пассивную проверку живости в рамках одного вызова — возвращает спрогнозированный моделью `age_estimation` (в годах), `score` проверки живости (0–100) и `status` со значением `Approved`/`Declined`. Возраст **прогнозируется моделью по лицу, а не верифицируется по документу** — используйте его для ограничений по возрасту и проверок с минимальными препятствиями, но не в качестве юридического подтверждения возраста. **Как это работает.** Изображение анализируется на наличие лиц (установите `rotate_image=true`, если снимки могут быть повернуты набок или перевернуты); для каждого обнаруженного лица оценивается возраст, а `age_estimation` определяется по самому крупному лицу в кадре. Параллельно модель пассивной проверки живости оценивает, изображен ли на фотографии живой человек (без необходимости выполнять действия пользователем), и выявляет атаки предъявления (фотографии фотографий, экраны, маски). Для достижения наилучших результатов отправляйте изображение с одним четким, хорошо освещенным лицом анфас. **Логика принятия решений.** Любое предупреждение приводит к отклонению: `status` получает значение `Approved` только в том случае, если массив `warnings` пуст. Если `score` проверки живости не превышает значение `face_liveness_score_decline_threshold` (по умолчанию `30`), добавляется `LOW_LIVENESS_SCORE`; при обнаружении атаки добавляется `LIVENESS_FACE_ATTACK`; если модель проверки живости не нашла лицо, добавляется `NO_FACE_DETECTED`; если возраст лица невозможно оценить, добавляется `AGE_NOT_DETECTED` (`age_estimation` равен `null`); если оценочный возраст ниже `age_estimation_decline_threshold` (по умолчанию `18`), добавляется `AGE_BELOW_MINIMUM`. Для пограничных значений возраста вблизи вашего порога рекомендуется предусмотреть резервную верификацию по документам — погрешность модели возрастает для лиц, чей возраст близок к лимиту. **Биллинг.** Каждый ответ `200` расходует один кредит API «Оценка возраста» (списывается из кредитов вашего тарифа или баланса пополнения). Если баланс организации не может покрыть вызов, endpoint возвращает `403` с ошибкой недостаточного количества кредитов еще до обработки изображения. **Сохранение сессии (`save_api_request`, по умолчанию `true`).** Если указано `true`, вызов сохраняется как сессия типа API: она отображается в Business Console, возвращаемый `request_id` представляет собой реальный id сессии, который вы можете передать в `GET /v3/session/{sessionId}/decision/` (результат доступен там в `liveness_checks[]` с `features: ["AGE_ESTIMATION"]`), кроп лица и эталонное изображение сохраняются, эмбеддинг лица добавляется в индекс лиц вашего приложения (используемый для поиска по лицу и обнаружения дубликатов), а также отправляется webhook `status.updated`. Если указано `false`, ничего не сохраняется, а `request_id` представляет собой одноразовый UUID корреляции, который нельзя запросить позже. **Песочница.** API-ключи песочницы пропускают всю обработку и биллинг: после валидации запроса (некорректный ввод по-прежнему возвращает `400`) endpoint возвращает статический тестовый payload со статусом `Approved` (`age_estimation: 30`, без предупреждений), сессия не сохраняется, и кредиты не расходуются. **Аутентификация.** Передавайте API-ключ вашего приложения в заголовке `x-api-key`. При отсутствии или недействительности учетных данных возвращается `403` (`{"detail": "You do not have permission to perform this action."}`) — этот API никогда не возвращает `401`. **Лимит запросов.** Общий лимит на запись составляет 300 запросов/мин на один API-ключ для всех endpoint'ов POST/PATCH/DELETE; при его превышении возвращается `429`. operationId: post_v3age-estimation parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - user_image properties: user_image: type: string format: binary description: >- Фотография лица для анализа (например, селфи). Отправьте одну фотографию анфас с четко различимым и хорошо освещенным лицом субъекта. Допустимые расширения: `tiff`, `jpg`, `jpeg`, `png`, `webp` (кроме PDF). Максимальный размер загрузки: **5 MB** (файлы большего размера отклоняются с кодом `400`). Изображения автоматически сжимаются примерно до ~0.3 MB перед обработкой, поэтому сверхвысокое разрешение не повышает точность. face_liveness_score_decline_threshold: type: number format: float default: 30 minimum: 0 maximum: 100 description: >- Порог проверки живости (0–100). Оценка `score` проверки живости **на уровне или ниже** этого значения добавляет предупреждение `LOW_LIVENESS_SCORE` и отклоняет сессию. Увеличьте его для более строгой защиты от спуфинга; значения вне диапазона 0–100 возвращают `400`. example: 30 age_estimation_decline_threshold: type: integer default: 18 minimum: 0 maximum: 100 description: >- Минимально допустимый оценочный возраст в годах. Оценочный возраст **ниже** этого значения добавляет предупреждение `AGE_BELOW_MINIMUM` и отклоняет сессию. Укажите `0`, чтобы отключить проверку возраста (в этом случае вызов выполняет только проверку живости + оценку возраста без принятия решения на основе возраста). example: 18 rotate_image: type: boolean default: false description: >- Когда `true`, сервис поворачивает входное изображение с шагом 90 градусов (0, 90, 180, 270) и использует ориентацию, обеспечивающую наилучшее обнаружение лица — полезно для мобильных снимков с отсутствующей ориентацией EXIF. Увеличивает задержку, поэтому включайте только в том случае, если вы не можете гарантировать правильную ориентацию изображений. example: false save_api_request: type: boolean default: true description: >- Если `true` (по умолчанию), сохраняет вызов как сессию типа API — видимую в Business Console, доступную через `GET /v3/session/{sessionId}/decision/` по возвращенному `request_id`, анонсируемую через webhook `status.updated`, с добавлением обнаруженного лица в индекс лиц вашего приложения. Если `false`, ничего не сохраняется, а `request_id` является временным UUID только для сопоставления ответа. example: true vendor_data: type: string description: >- Необязательная непрозрачная строка (ваш внутренний идентификатор пользователя, email, UUID…), сохраняемая в сессии и возвращаемая в ответе. Используйте её для сопоставления вызовов API с вашими собственными записями и для последующей фильтрации сессий. example: user-123 metadata: type: object additionalProperties: true description: >- Необязательный объект JSON, сохраняемый вместе с сессией (когда `save_api_request=true`) и возвращаемый обратно в ответе. В multipart-запросах отправляйте его как строковое поле в формате JSON (например, `metadata={"flow":"age-gate"}`) — он парсится в объект. example: flow: age-gate example: user_image: (binary JPEG/PNG of the selfie) face_liveness_score_decline_threshold: 30 age_estimation_decline_threshold: 18 rotate_image: false save_api_request: true vendor_data: user-123 metadata: flow: age-gate responses: '200': description: >- Оценка возраста и пассивная проверка живости завершены. Поле `age_estimation.age_estimation` содержит предсказанный моделью возраст в годах для самого крупного обнаруженного лица (`null`, если лиц не обнаружено); `age_estimation.score` является оценкой пассивной проверки живости (0–100); `status` имеет значение `Approved`, только если `warnings` пуст. Снимок несовершеннолетнего пользователя или попытка спуфинга по-прежнему возвращают `200` со статусом `status: "Declined"`: проверяйте тело ответа, а не только HTTP-код. При `save_api_request=true` значение `request_id` является сохраненным id сессии. content: application/json: examples: Approved: summary: Живое лицо совершеннолетнего — обе проверки пройдены value: request_id: 0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1 age_estimation: status: Approved method: PASSIVE score: 97.5 user_image: entities: - age: 27.33 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 27.33 warnings: [] vendor_data: user-123 metadata: flow: age-gate created_at: '2026-06-12T02:24:11.512941+00:00' Declined - age below threshold: summary: Оценочный возраст ниже `age_estimation_decline_threshold` value: request_id: 9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2 age_estimation: status: Declined method: PASSIVE score: 95 user_image: entities: - age: 16.5 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: female best_angle: 0 age_estimation: 16.5 warnings: - risk: AGE_BELOW_MINIMUM feature: LIVENESS additional_data: null log_type: error short_description: Age below minimum long_description: >- The age of the face is below the minimum age threshold for the application. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:26:40.118332+00:00' Declined - liveness too low: summary: >- Оценка проверки живости на уровне или ниже порога отклонения (возможен спуфинг) value: request_id: 5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77 age_estimation: status: Declined method: PASSIVE score: 5 user_image: entities: - age: 25 bbox: - 40 - 40 - 100 - 100 confidence: 0.7177750468254089 gender: male best_angle: 0 age_estimation: 25 warnings: - risk: LOW_LIVENESS_SCORE feature: LIVENESS additional_data: null log_type: error short_description: Low liveness score long_description: >- The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:02.901547+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- Идентификатор сохраненной сессии при `save_api_request=true` (доступен для использования с `GET /v3/session/{sessionId}/decision/`); в противном случае это временный корреляционный UUID. age_estimation: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved`, если не возникло никаких предупреждений; в противном случае `Declined` (каждое предупреждение, формируемое этим endpoint, приводит к отклонению). method: type: string enum: - PASSIVE description: >- Метод проверки живости. Всегда `PASSIVE` для этого endpoint (одно изображение, без задания пользователю). score: type: number format: float nullable: true minimum: 0 maximum: 100 description: >- Оценка пассивной проверки живости от 0 до 100 — уверенность модели в том, что на фотографии живой человек. Сравнивается с `face_liveness_score_decline_threshold`; при значении на уровне порога или ниже вызов отклоняется с `LOW_LIVENESS_SCORE`. Принимает значение `null`, если модель проверки живости не возвращает оценку уверенности — вызов всё равно отклоняется с `LOW_LIVENESS_SCORE`, поскольку для сравнения с порогом null считается равным 0. example: 97.5 user_image: type: object description: >- Результаты обнаружения лица для проанализированного изображения. properties: entities: type: array description: >- Одна запись на каждое обнаруженное лицо. Пусто, если лицо не найдено (в этом случае `age_estimation` имеет значение `null` и добавляется предупреждение `AGE_NOT_DETECTED`). items: type: object properties: age: type: number format: float description: >- Возраст этого лица в годах, оцененный моделью. example: 27.33 bbox: type: array items: type: integer minItems: 4 maxItems: 4 description: >- Ограничивающий прямоугольник обнаруженного лица в координатах пикселей `[x_min, y_min, x_max, y_max]` на обработанном изображении. example: - 40 - 40 - 100 - 100 confidence: type: number format: float minimum: 0 maximum: 1 description: Уверенность обнаружения лица (0–1). example: 0.7177750468254089 gender: type: string description: >- Пол обнаруженного лица, спрогнозированный моделью (`male` или `female`). Только для справки. example: male best_angle: type: integer nullable: true description: >- Поворот (в градусах: 0, 90, 180 или 270), при котором было достигнуто наилучшее обнаружение лица. Отличен от нуля, только если `rotate_image=true` скорректировал ориентацию. example: 0 age_estimation: type: number format: float nullable: true description: >- Возраст в годах **самого крупного** обнаруженного лица, спрогнозированный моделью. `null`, если возраст лица не удалось оценить (добавляется предупреждение `AGE_NOT_DETECTED`, и вызов отклоняется). example: 27.33 warnings: type: array description: >- Пусто при чистом одобрении. Любая запись устанавливает для `status` значение `Declined`. items: type: object properties: risk: type: string enum: - NO_FACE_DETECTED - LOW_LIVENESS_SCORE - LIVENESS_FACE_ATTACK - AGE_NOT_DETECTED - AGE_BELOW_MINIMUM description: >- Машиночитаемый код риска. `NO_FACE_DETECTED` — модель проверки живости не обнаружила лицо; `LOW_LIVENESS_SCORE` — `score` живости равен или ниже `face_liveness_score_decline_threshold`; `LIVENESS_FACE_ATTACK` — обнаружена атака предъявления (фото/экран/маска); `AGE_NOT_DETECTED` — не удалось оценить возраст лица; `AGE_BELOW_MINIMUM` — оценённый возраст ниже `age_estimation_decline_threshold`. `NO_FACE_DETECTED` и `LOW_LIVENESS_SCORE` взаимоисключают друг друга — если лицо не найдено, возвращается только `NO_FACE_DETECTED`. feature: type: string enum: - LIVENESS description: >- Функция, вызвавшая предупреждение. На этом endpoint всегда `LIVENESS`. additional_data: type: object nullable: true additionalProperties: true description: >- Всегда `null` для предупреждений оценки возраста. log_type: type: string enum: - error description: >- Уровень серьёзности. Каждое предупреждение, формируемое этим endpoint, является `error` и устанавливает `status` в `Declined`. short_description: type: string description: >- Краткая сводка риска в одну строку в понятном человеку формате. long_description: type: string description: Понятное объяснение риска. vendor_data: type: string nullable: true description: Эхо-значение переданного вами `vendor_data` или `null`. metadata: type: object nullable: true additionalProperties: true description: >- Эхо-значение переданного вами объекта `metadata` или `null`. created_at: type: string format: date-time description: Временная метка ISO 8601 (UTC) момента генерации ответа. '400': description: >- Ошибка валидации. Возвращается, если `user_image` отсутствует, превышает 5 МБ, имеет неподдерживаемое расширение или если порог выходит за допустимые пределы. Тело ответа представляет собой стандартную обёртку ошибок полей DRF: один массив сообщений на каждое некорректное поле. content: application/json: examples: Missing user image: summary: '`user_image` не включён в данные формы' value: user_image: - No file was submitted. Unsupported file extension: summary: Расширение файла отличается от tiff/jpg/jpeg/png/webp value: user_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp. File too large: summary: Размер загружаемого файла превышает лимит в 5 МБ value: user_image: - File size should not exceed 5 MB Threshold out of range: summary: '`face_liveness_score_decline_threshold` вне диапазона 0–100' value: face_liveness_score_decline_threshold: - Ensure this value is less than or equal to 100. '403': description: >- В доступе отказано. Возвращается, если заголовок `x-api-key` отсутствует, а также если баланс вызывающей организации не покрывает вызов; неверный, отозванный или истекший ключ возвращает `401`. Отсутствующий ключ возвращает `403` с `{"detail": ...}`; неверный, отозванный или истекший ключ возвращает `401`. При нехватке кредитов возвращается `403` с `{"error": ...}` до начала любой обработки изображения. content: application/json: examples: Missing or invalid API key: summary: >- Отсутствует заголовок `x-api-key`, либо ключ недействителен/отозван value: detail: You do not have permission to perform this action. Not enough credits: summary: Баланс организации недостаточен для совершения вызова value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- Превышен лимит запросов. Endpoint'ы POST/PATCH/DELETE делят общий лимит в 300 запросов на запись в минуту на один API-ключ (для создания транзакций и отправки событий действует отдельный лимит в 600). Ответ содержит заголовки `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` и `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Более 300 запросов на запись в текущую минуту value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/age-estimation/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'user_image=@./selfie.jpg' \ -F 'age_estimation_decline_threshold=18' \ -F 'face_liveness_score_decline_threshold=30' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.age_estimation.estimate( user_image=open("user_image.jpg", "rb"), face_liveness_score_decline_threshold=30.0, age_estimation_decline_threshold=18, rotate_image=False, save_api_request=True, vendor_data="user-123", metadata={"flow": "age-gate"}, ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.ageEstimation.estimate({ user_image: await fileFromPath("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import java.util.Map; import me.didit.Didit; import me.didit.types.AgeEstimationEstimateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder() .userImage(Path.of("user_image.jpg")) .faceLivenessScoreDeclineThreshold(30.0) .ageEstimationDeclineThreshold(18L) .rotateImage(false) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "age-gate")) .build()); System.out.println(result); - lang: php label: PHP source: |- ageEstimation->estimate([ 'user_image' => File::fromPath('user_image.jpg'), 'face_liveness_score_decline_threshold' => 30.0, 'age_estimation_decline_threshold' => 18, 'rotate_image' => false, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'age-gate'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.age_estimation.estimate( user_image: Pathname("user_image.jpg"), face_liveness_score_decline_threshold: 30.0, age_estimation_decline_threshold: 18, rotate_image: false, save_api_request: true, vendor_data: "user-123", metadata: { flow: "age-gate" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams { UserImage = FileUpload.FromPath("user_image.jpg"), FaceLivenessScoreDeclineThreshold = 30.0, AgeEstimationDeclineThreshold = 18, RotateImage = false, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "age-gate" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.