---
title: "Create Video Person"
method: POST
path: "/v2/videos/{video_id}/persons"
tags: ["Media Persons"]
---

# Create Video Person

`POST /v2/videos/{video_id}/persons`

## 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/videos/{video_id}/persons`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Name a person on this video. You can attach faces and speakers now or later.

The name is also saved on those faces and speakers, and on their transcript lines.

## Path parameters

- `video_id` string, required

## Request body

- CreateMediaPersonRequest: Name someone on this video or audio. Appearances can be added later.
  - `name` string, required: Display name.
  - `appearances` MediaAppearanceInput[]: Faces or speakers to attach now. Omit to name the person first.
    - `face_id` integer, nullable: Face on the video.
    - `speaker_id` integer, nullable: Speaker on this video's audio, or on a standalone audio.

## Response `201`

Successful Response

- MediaPerson: A person named on one video or one standalone audio. ``media_type`` and ``media_id`` are the home. Updates, including from a linked audio page, use that home. A linked audio is not a home of its own.
  - `person_id` string, required
  - `scope` 'media'
  - `media_type` 'video' | 'audio', required: Home this person is stored on. Use this in the update path.
  - `media_id` string, required: Home id. Use this id, not the page you listed from, when you update.
  - `name` string, required
  - `appearances` MediaAppearance[]
    - `video_id` string, nullable: Video this appearance is on.
    - `audio_id` string, nullable: Standalone audio this appearance is on.
    - `face_id` integer, nullable: Face on the video.
    - `speaker_id` integer, nullable: Speaker attached to this person.
    - `linked_at` string, date-time, required
    - `linked_by` string, nullable: Account that attached this appearance. Absent when the viewer is not signed in.
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

## Other responses

- `422`: Validation Error

## Changes

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

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/videos/:video_id/persons/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)