---
title: "Face Similarity"
method: POST
path: "/v2/faces/similarity"
tags: ["Faces"]
---

# Face Similarity

`POST /v2/faces/similarity`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/faces/similarity`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Compare faces across your videos.

Scores each probe face against each gallery face and returns a similarity per pair.
Both lists are explicit: there is no search across all of your videos. Only videos
you own can be compared. Shared or sample videos you can view, and other members'
videos, are reported as `not_found`, the same as a video that does not exist.

Up to 16 probes and 512 gallery faces per call. A face listed twice within a list is
compared once, and a face is never paired with itself.

A face that cannot be scored is listed under `incomparable` with a reason instead of
a score. The response is still 200, with an empty `pairs` when nothing could be
scored. Scores are only computed between faces analysed with the same model version,
named by `model_id` and `embedding_version`.

The response never contains face embeddings or any other biometric template, only
ids and scores. Similarity is a score, not a match decision. No charge is applied.

## Request body

- FaceSimilarityRequest: Faces to score, and the faces to score them against. A face repeated within a list is compared once.
  - `probes` FaceRef[], required: Faces to look up, 1 to 16.
    - `video_id` string, required: A video you own.
    - `face_id` integer, required: A face on that video, as listed in the video's faces.
  - `gallery` FaceRef[], required: Faces to compare each probe against, 1 to 512.
    - `video_id` string, required: A video you own.
    - `face_id` integer, required: A face on that video, as listed in the video's faces.

## Response `200`

Successful Response

- FaceSimilarityResponse: Scores for every comparable probe against every comparable gallery face.
  - `pairs` FaceSimilarityPair[], required: Every comparable probe x every comparable gallery face, except a face with itself. Ordered by probe (request order), then similarity descending, then gallery request order.
    - `probe` FaceRef, required: One face on one video.
      - `video_id` string, required: A video you own.
      - `face_id` integer, required: A face on that video, as listed in the video's faces.
    - `gallery` FaceRef, required: One face on one video.
      - `video_id` string, required: A video you own.
      - `face_id` integer, required: A face on that video, as listed in the video's faces.
    - `similarity` number, required: Cosine similarity, rounded to 4 decimal places. Higher is more alike. It is a score, not a decision: choose your own threshold.
  - `incomparable` IncomparableFace[], required: One entry per distinct requested face that could not be scored, probes first.
    - `video_id` string, required
    - `face_id` integer, required
    - `reason` 'not_found' | 'stale' | 'no_embedding' | 'unverified_model' | 'model_mismatch', required: `not_found`: no such video or face among videos you own. `stale`: the video's faces were merged after analysis; reprocess the video to compare it. `no_embedding`: no usable face data for this face, for example because the video is not completed, predates this feature, or the face was never seen clearly. `unverified_model`: the face data was produced by an unidentified model version. `model_mismatch`: the face data was produced by a different model version from the one this response is scored on.
  - `model_id` string, required: Identifier of the face model every score is computed with.
  - `embedding_version` integer, required: Version of the face representation every score is computed with. Scores are only comparable across responses with the same model_id and embedding_version.

## Other responses

- `422`: Validation Error
- `503`: Face data could not be read in time. Retry after the `Retry-After` delay.

## Changes

- **2026-10-01** `72330e2229c7`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/faces/similarity/post.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)