---
title: "Trigger Personality Analysis"
method: POST
path: "/v2/videos/{video_id}/personality/analyze"
tags: ["Video Emotion API"]
---

# Trigger Personality Analysis

`POST /v2/videos/{video_id}/personality/analyze`

## 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}/personality/analyze`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.imentiv.ai/oauth/authorize`
    - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `media.write`

Trigger personality analysis for a specific face in a video.

Initiates asynchronous personality trait assessment based on facial expressions and,
when available, vocal characteristics from linked audio speaker data.

## Analysis Types

- **overall**: Analyzes personality traits across the entire video
- **by_segment**: Analyzes personality traits by time segments
- **combined**: Performs both overall and segment analysis

Overall and segment analyses are independent - triggering one does not affect the other.

## Multimodal Analysis

- **Face only**: Analyzes facial expressions when no speaker is linked
- **Face + Audio**: Combines facial and vocal characteristics when face is linked to a speaker

## Prerequisites

- Video must be completed
- Face ID must exist in the video
- If face has speaker mapping: audio must be completed
- User must have sufficient credits

## Request

```json
{
  "face_id": 1,
  "analysis_type": "overall",
  "callback_url": "https://example.com/webhook"
}
```

## Response

```json
{
  "video_id": "abc123",
  "face_id": 1,
  "speaker_id": 2,
  "analysis_type": "overall",
  "status": "processing",
  "message": "Personality analysis triggered successfully"
}
```

## Credit Usage

Credits are billed per minute of video duration based on `analysis_type`.

| analysis_type | Personal | Enterprise |
|---|---|---|
| overall | 30 credits/min | 15 credits/min |
| by_segment | 50 credits/min | 25 credits/min |
| combined | 60 credits/min | 30 credits/min |

## Notes

- Analysis runs asynchronously in the background
- Use callback_url for webhook notifications when complete
- Credits are deducted when analysis is triggered
- Retrieve results using the video analytics endpoints

## Path parameters

- `video_id` string, required: Unique identifier of the video. Video must be in 'completed' status with detected faces.

## Request body `application/x-www-form-urlencoded`

- BodyTriggerPersonalityAnalysisV2VideosVideoIdPersonalityAnalyzePost
  - `face_id` integer, required: Face identifier from video analysis to perform personality assessment on. Must exist in the video's detected faces.
  - `analysis_type` string: Type of personality analysis: 'overall', 'by_segment', or 'combined'. Default is 'overall'.
  - `callback_url` string, nullable: Optional webhook URL to receive notification when personality analysis completes. Webhook will receive the analysis results as JSON payload. Must be an https URL on a publicly reachable host.

## Response `200`

Successful Response

- PersonalityTriggerResponse: Response model returned after triggering personality processing for a specific face (and optionally a speaker) within a video. Attributes: video_id (str): Unique identifier of the video where personality processing was triggered. face_id (int): Identifier of the face entity associated with the personality trigger. speaker_id (Optional[int]): Identifier of the linked speaker entity, if applicable; otherwise None. analysis_type (str): Type of personality analysis - 'overall', 'by_segment', or 'combined'. status (str): Result status of the trigger operation message (str): Status message describing the result of the trigger operation.
  - `video_id` string, required
  - `face_id` integer, required
  - `speaker_id` integer, nullable
  - `analysis_type` string, required
  - `status` string, required
  - `message` string, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-22** `536bf48bb9fb`: 3 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
  - the endpoint scheme security `BearerAuth` was added to the API
  - the endpoint scheme security `OAuth2Delegated` was added to the API

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