> For the complete documentation index, see [llms.txt](https://doc.ozforensics.com/oz-knowledge-ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.ozforensics.com/oz-knowledge-ru/obshaya-informaciya/kratkie-rukovodstva-po-integracii/kak-zapustit-biometricheskii-analiz-sopostavlenie-lic.md).

# Как запустить биометрический анализ (сопоставление лиц)

{% hint style="warning" icon="display" %}
Внимание: это машинный перевод.
{% endhint %}

Эта статья охватывает сценарий, когда вам нужно выполнить сопоставление лиц с внешним фото, используя OzCapsula для передачи данных. Вот что нужно сделать.

1. В зависимости от конфигурации API:
   1. Instant API: запустите анализ Liveness с использованием OzCapsula и включенным извлечением лучшего кадра. Этот лучший кадр затем используется для сравнения.
   2. Full API: запустите обычный анализ Liveness.
2. Запустите запрос на сопоставление лиц без OzCapsula. Сопоставление происходит на бэкенде, поэтому защищенная передача данных не требуется.

Инструкции ниже показывают, как настроить поток для каждой конфигурации API.

## Instant API

{% stepper %}
{% step %}

### Запустите анализ Liveness с лучшим кадром

Лучший кадр — это кадр из видео Liveness, на котором лицо видно наиболее четко. Когда извлечение лучшего кадра включено, сервер выбирает этот кадр во время анализа Quality (Liveness) и сохраняет его в той же папке, что и исходное видео, так что его можно повторно использовать как входные данные для анализа сопоставления лиц (Biometry) без повторной съемки медиа.

#### 1.1. Включите извлечение лучшего кадра

В этом разделе описано, где включить извлечение лучшего кадра в каждом Oz SDK.

{% tabs %}
{% tab title="Android SDK" %}
Добавьте `extract_best_shot` в map `params` того `AnalysisProfile`, у которого `type` равен `QUALITY`, внутри `CaptureRequest.analysisProfileList`.

```kotlin
val livenessProfile = AnalysisProfile(
    mediaList = listOf(
        MediaRequest(
            id = UUID.randomUUID().toString(),
            actionMedia = OzAction.Smile
        )
    ),
    type = "QUALITY",
    params = mapOf("extract_best_shot" to true)
)

val captureRequest = CaptureRequest(
    analysisProfileList = listOf(livenessProfile)
)
```

После этого выполните `createMediaCaptureScreen(captureRequest, session_token)`, чтобы получить контейнер данных, и отправьте его на анализ с помощью `addContainer(container)` — точно так же, как в стандартном OzCapsula-потоке.
{% endtab %}

{% tab title="iOS SDK" %}
Добавьте `extract_best_shot` в `params` того `AnalysisProfile`, у которого `type` равен `.quality`, внутри `CaptureRequest.analysisProfileList`.

```swift
let livenessProfile = AnalysisProfile(
    mediaList: [
        MediaRequest(
            id: UUID().uuidString,
            actionMedia: .smile
        )
    ],
    type: .quality,
    params: ["extract_best_shot": true]
)

let captureRequest = CaptureRequest(
    analysisProfileList: [livenessProfile]
)
```

После этого выполните `createMediaCaptureScreen(request: captureRequest, session_token: token)`, чтобы получить контейнер данных, и отправьте его на анализ с помощью `addContainer(container)`.
{% endtab %}

{% tab title="Web SDK" %}
Добавьте `extract_best_shot` в `params` объекта, передаваемого в `OzLiveness.open()`. В отличие от мобильных SDK, этот параметр находится на верхнем уровне опций запуска, а не вложен в конкретный анализ, и работает одинаково независимо от того, используете ли вы контейнер данных OzCapsula или устаревший поток.

```javascript
OzLiveness.open({
    session_token,                 // required for OzCapsula (Web SDK 1.9.2+)
    action: ['video_selfie_blank'],
    params: {
        extract_best_shot: true
    },
    // ... other options
});
```

{% endtab %}
{% endtabs %}

#### 1.2. Получите медиа для сравнения

Instant API возвращает лучший кадр в формате base64. В ответе вы найдете его в `folder.analyses.results_media` → `output_images` → `image_b64`. Декодируйте base64-лучший кадр из ответа Liveness и сохраните его как файл (например, `best_shot.jpeg`).
{% endstep %}

{% step %}

### Запустите анализ сопоставления лиц

Сопоставление лиц запускается напрямую через Oz API, без шага съемки в SDK.

Вызовите `POST /api/instant/folders/` с вашим эталонным фото и лучшим кадром, который вы получили из анализа Liveness, как показано в 1.2.

{% hint style="warning" %}
Ключи ваших медиафайлов и соответствующие имена файлов должны совпадать.
{% endhint %}

{% code title="Request body" %}

```json
{
  "media:tags": {
    "UUID_of_reference_photo.jpeg": ["photo_selfie"],
    "best_shot.jpeg": ["photo_selfie"]
  },
  "analyses": [
    { "type": "biometry" }
  ]
}
```

{% endcode %}

Ответ будет содержать результат анализа biometry.
{% endstep %}
{% endstepper %}

***

## Full API

{% stepper %}
{% step %}

### Запустите анализ Liveness

{% tabs %}
{% tab title="Android SDK" %}

```kotlin
val livenessProfile = AnalysisProfile(
    mediaList = listOf(
        MediaRequest(
            id = UUID.randomUUID().toString(),
            actionMedia = OzAction.Smile
        )
    ),
    type = "QUALITY"
)

val captureRequest = CaptureRequest(
    analysisProfileList = listOf(livenessProfile)
)
```

После этого выполните `createMediaCaptureScreen(captureRequest, session_token)`, чтобы получить контейнер данных, и отправьте его на анализ с помощью `addContainer(container)` — точно так же, как в стандартном OzCapsula-потоке.
{% endtab %}

{% tab title="iOS SDK" %}

```swift
let livenessProfile = AnalysisProfile(
    mediaList: [
        MediaRequest(
            id: UUID().uuidString,
            actionMedia: .smile
        )
    ],
    type: .quality
)

let captureRequest = CaptureRequest(
    analysisProfileList: [livenessProfile]
)
```

После этого выполните `createMediaCaptureScreen(request: captureRequest, session_token: token)`, чтобы получить контейнер данных, и отправьте его на анализ с помощью `addContainer(container)`.
{% endtab %}

{% tab title="Web SDK" %}

```javascript
OzLiveness.open({
    session_token,                 // required for OzCapsula (Web SDK 1.9.2+)
    action: ['video_selfie_blank'],
    // ... other options
});
```

{% endtab %}
{% endtabs %}

Из ответа вам нужны `folder_id` и оригинальное имя вашего медиафайла (снятого видео), которое находится в `folder.media` → `original_name`.
{% endstep %}

{% step %}

### Запустите анализ сопоставления лиц

{% stepper %}
{% step %}

#### Добавьте ваше эталонное фото в папку

Добавьте ваше эталонное фото в папку, определяемую по `folder_id` из ответа на ваш запрос Liveness: `POST /api/folders/{{folder_id}}/media/`.

{% code title="Request body" %}

```json
{
  "media:tags": {
    "UUID_of_reference_photo.jpeg": ["photo_selfie"]
  }
}
```

{% endcode %}
{% endstep %}

{% step %}

#### Вызовите Oz API с Folder ID

Вызовите Oz API `POST /api/folders/{{folder_id}}/analyses/` с `folder_id` из ответа на ваш запрос Liveness (**шаг 1**). Задайте biometry как тип анализа и определите, какие медиафайлы сравнивать, в секции `source_media`. Используйте оригинальное имя и расширение вашего медиафайла из **шага 1**, например, `original_name.zip` или `original_name.mp4`.

{% code title="Request body" %}

```json
{
  "analyses": [
    {
      "type": "biometry",
      "source_media": [
        <original_name_with_extension>,
        <UUID_of_reference_photo.jpeg>
      ]
    }
  ]
}
```

{% endcode %}

Ответ будет содержать результат анализа biometry.
{% endstep %}
{% endstepper %}
{% endstep %}
{% endstepper %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://doc.ozforensics.com/oz-knowledge-ru/obshaya-informaciya/kratkie-rukovodstva-po-integracii/kak-zapustit-biometricheskii-analiz-sopostavlenie-lic.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.