---
title: "Trigger Speaker Face Match"
method: POST
path: "/v2/videos/{video_id}/speaker-face-match"
tags: ["Video Emotion API"]
---

# Trigger Speaker Face Match

`POST /v2/videos/{video_id}/speaker-face-match`

Trigger automatic AI-driven speaker-to-face matching for a video.

This endpoint initiates an asynchronous process that automatically matches
speakers from the audio analysis to faces detected in the video using AI.


## Prerequisites

- User must be the video owner or an admin
- Video must be in 'completed' status
- Audio must be in 'completed' status
- Video must have an associated audio_id

## Response

```json
{
  "video_id": "abc123",
  "audio_id": "xyz789",
  "status": "processing",
  "message": "Speaker-face match worker triggered successfully"
}
```

## Error Responses

- **401 Unauthorized**: User is not authenticated or not authorized to access this video
- **404 Not Found**: Video not found
- **409 Conflict**: Video or audio processing not completed
- **400 Bad Request**: Audio ID missing in video document

## Path parameters

- `video_id` string, required — Unique identifier of the video. Video must be in 'completed' status with associated audio.

## Response `200`

Successful Response

- AutoSpeakerFaceMatchTriggerResponse — Response model for triggering the automatic speaker-face match worker. Attributes: video_id (str): Unique identifier of the video. audio_id (str): Unique identifier of the audio document. status (str): Status of the trigger operation (e.g., "processing"). message (str): Informational message about the operation.
  - `video_id` string, required
  - `audio_id` string, required
  - `status` string, required
  - `message` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/imentiv/apis/welcome-to-imentiv-ai.md) · [All operations](https://skmtc.net/imentiv/apis/welcome-to-imentiv-ai/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/imentiv/welcome-to-imentiv-ai/revisions/4a61d1ac9025/schema)