People

Every face the index finds (in videos, photos and document pages) is grouped into people across your whole workspace, the way a phone’s photo library does it: one person, many appearances, whatever the asset. You name them, merge or split them, and the next re-grouping keeps what you decided.

How grouping works

On arrival. A new upload’s faces join an existing person when they clearly match one. Faces that match nobody wait.
Re-clustering groups the faces that are waiting into new people (a person needs at least 3 good faces) and tidies existing ones. Run it with POST /api/v1/people/recluster after adding a batch of uploads.
Your decisions win. A named person is never merged automatically, and only gains faces. People you merge and faces you reject stay that way through every re-cluster and re-index.
Quality. Each face has a quality score (size, sharpness, pose). Small or blurry faces are kept and shown, but only good faces decide who someone is.

People are per workspace: an asset’s faces belong to the People of the workspace that owns it. Faces are detected and described with open-source models (YuNet + SFace). Turn faces or People off per upload or per workspace with the faces / people index options.

List people

curl https://api.niravi.io/api/v1/people -H "X-API-Key: $NIRAVI_API_KEY"

{ "people": [
    { "person_id": "p_a1145a6a219f", "name": "Suni Williams", "status": "named",
      "face_count": 67, "cover_face_id": "7958e97eb48b46c0_face_000000_00", "merged_into": null }
  ], "total": 1 }

status is unverified (found by grouping, not yet named), named, or hidden. Hidden people are left out unless you pass ?include_hidden=true.

One person: faces and where they appear

GET /api/v1/people/{person_id} (paginated with limit / offset) returns the person, their faces with boxes, and appearances: every asset they are in, with its kind, how many faces and the first timestamp.

curl "https://api.niravi.io/api/v1/people/p_a1145a6a219f?limit=50" -H "X-API-Key: $NIRAVI_API_KEY"

A person merged into another keeps working as an ID: asking for it returns the person it was merged into (requested_id says what you asked for).

Faces also appear per asset, with their person_id, under /videos/{id}/regions.

Change a person (write scope)

Call	Body	Does
`PATCH /people/{id}`	`{"name": "Suni Williams"}`	Names them (`""` clears the name)
`PATCH /people/{id}`	`{"hidden": true}`	Hides them from the list (`false` shows them again)
`PATCH /people/{id}`	`{"cover_face_id": "…"}`	Pins the cover to one of their faces
`POST /people/{id}/merge`	`{"into": "p_…"}`	Merges this person into another; the old ID keeps resolving
`POST /people/{id}/remove`	`{"face_ids": ["…"], "reject": true}`	Takes faces off this person. `reject: true` means “not them”: a re-cluster never puts those faces back. `false` only splits them out to be re-grouped
`POST /people/recluster`		Re-groups waiting faces in the background (`202`). Add `?dry_run=true` to get the plan without changing anything

curl -X PATCH https://api.niravi.io/api/v1/people/p_a1145a6a219f \
  -H "X-API-Key: $NIRAVI_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Suni Williams"}'

If a re-cluster is running when you edit, the call may answer 409 busy: retry a moment later.

Deleting assets

Deleting a video, photo or document refreshes everyone whose faces it held: their face count, cover and matching drop that asset. A person left with no faces is removed unless you named them.