openapi: 3.1.0 info: title: Welcome to Imentiv AI AI Insights API Video Emotion API API description: "# Welcome to Imentiv AI\n\nImentiv AI is an advanced Emotion AI platform that leverages deep learning to analyze human emotions across multiple media formats, including video, audio, images, and text. By interpreting facial expressions, vocal tones, and linguistic cues, it provides detailed emotional insights to support use cases such as content creation, marketing optimization, education, mental health assessments, and more.\n\nImentiv AI offers a suite of Emotion Recognition APIs that allow developers and businesses to seamlessly integrate advanced emotion analysis into their applications, enabling deeper insights into user engagement and emotional responses.\n\n## Key Features of Imentiv AI APIs\n\n### 1. Video Emotion API\n**Functionality:** Analyzes emotions in videos, whether uploaded directly or via YouTube links.\n\n**Insights Provided:**\n- Frame-by-frame and actor-by-actor emotion analysis\n- Valence-arousal mapping to determine emotional intensity and positivity/negativity\n- Personality trait analysis using the Big Five (OCEAN) model\n- Emotion graphs and wheels to visualize emotional dynamics\n\n**Use Cases:** Suitable for researchers analyzing bulk videos, advertising campaigns, webinars, online meetings, and other video-based content to optimize engagement and content strategy.\n\n### 2. Image Emotion API\n**Functionality:** Detects and analyzes emotions in images.\n\n**Insights Provided:**\n- Face detection and recognition\n- Emotion analysis for each detected face\n- Overall emotional tone of the image\n\n**Use Cases:** Enhances image analysis for advertising, market research, psychological studies, and social media content.\n\n### 3. Audio Emotion API\n**Functionality:** Analyzes emotions in audio recordings, either via direct uploads or by extracting audio from YouTube videos.\n\n**Insights Provided:**\n- Differentiation between multiple speakers in a conversation\n- Emotion detection from vocal cues (e.g., happiness, sadness, anger, surprise)\n- Transcription and detection of up to 28 nuanced emotions (e.g., admiration, curiosity, disappointment, pride)\n- Audio summaries and detailed analytics\n\n**Use Cases:** Provides emotional insights for podcasts, voice messages, call analysis, and other audio-based content.\n\n### 4. Text Emotion API\n**Functionality:** Analyzes emotions in textual content.\n\n**Insights Provided:**\n- Detection of 28 distinct emotions, including curiosity, disappointment, and excitement\n- Overall sentiment analysis and identification of dominant emotions at sentence level\n\n**Use Cases:** Integrates into chatbots, social media platforms, and other text-based applications for sentiment and emotion analysis.\n\n---\n\n## Authorization\n\nLearn how to obtain your API keys to access Imentiv AI APIs.\n\n### Generate API Key:\n\n1. **Sign up** at [imentiv.ai](https://imentiv.ai) and log in to your account.\n2. Navigate to the **'My Profile'** tab to obtain your API key.\n3. Use this API key to authorize your API calls.\n\n> **Note:** Keep your API key secure and do not share it publicly. Include it in your API requests using the `Authorization` header or as specified in the endpoint documentation.\n " version: 1.0.0 tags: - name: Video Emotion API description: "The Video Emotion Analysis API by Imentiv analyzes the emotional states of individuals in a video. It performs multi-modal emotion detection using facial expressions, audio, and text transcript, and has the following features:\n\n- Overall emotion summary\n- Frame-by-frame emotion data\n- Per-face emotional analysis\n- Valence-arousal-intensity data\n- Audio and transcript emotion data\n- Personality analysis\n- Video Highlights\n- Optional psychological insights\n " paths: /v2/videos: post: tags: - Video Emotion API summary: Upload Video description: 'Analyze emotions and facial expressions from video content. Submit a video from multiple sources and receive detailed emotion analysis of all detected faces throughout the video timeline. **Input Sources:** - **YouTube**: Provide any YouTube video URL - **Cloud Storage**: Dropbox, Google Drive, or other cloud service links - **Social Media**: Instagram, Facebook, Twitter (X) videos - **Direct URL**: Any publicly accessible video link - **File Upload**: Upload video files directly from your device **Analyze Specific Segments:** Focus on specific portions using `start_millis` and `end_millis` parameters. This helps target key moments and optimize credit usage. **How It Works:** 1. Submit your video and receive an immediate response with a video ID 2. Video is queued for processing (typically completes within minutes) 3. Optionally receive a webhook notification via `callback_url` when complete 4. Retrieve results using the video ID **Supported Formats:** MP4, AVI, MOV, WebM, MPEG **Credit Usage:** Processing time is billed based on the analyzed video duration.' operationId: upload_video_v2_videos_post requestBody: content: multipart/form-data: schema: $ref: '#/components/schemas/Body_upload_video_v2_videos_post' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VideoEmotionResponseV2' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] /v1/videos: get: tags: - Video Emotion API summary: List Videos description: Retrieves a paginated list of uploaded video files associated with the authenticated user. operationId: list_videos_v1_videos_get security: - APIKeyHeader: [] parameters: - name: offset_video_id in: query required: false schema: type: string description: The ID of the reference video from which to paginate forward/backward title: Offset Video Id description: The ID of the reference video from which to paginate forward/backward - name: page_size in: query required: false schema: type: integer description: 'Number of results to return (default: 10)' default: 10 title: Page Size description: 'Number of results to return (default: 10)' - name: direction in: query required: false schema: type: string description: 'Pagination direction: forward (default) or backward' default: forward title: Direction description: 'Pagination direction: forward (default) or backward' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}: get: tags: - Video Emotion API summary: Get Video Emotion Insights description: Get a single video details by ID operationId: get_video_emotion_insights_v1_videos__video_id__get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique ID of the video to be fetched title: Video Id description: The unique ID of the video to be fetched responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VideoResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Video Emotion API summary: Delete Video description: Permanently deletes a video file and all associated emotional insights. This action is irreversible. operationId: delete_video_v1_videos__video_id__delete security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique ID of the video to be deleted. title: Video Id description: The unique ID of the video to be deleted. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VideoDeleteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' put: tags: - Video Emotion API summary: Reprocess Video description: 'Reprocess an already uploaded and completed video file. This is useful when insights need to be regenerated or logic has been updated on the backend. Reprocessing can optionally notify your system via a callback URL.' operationId: reprocess_video_v1_videos__video_id__put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Unique identifier of the video to reprocess title: Video Id description: Unique identifier of the video to reprocess requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_reprocess_video_v1_videos__video_id__put' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ReprocessVideoResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/videos/{video_id}/multimodal-analytics: get: tags: - Video Emotion API summary: Get Video Multimodal Insights description: 'Get complete multimodal analytics for a video including: - Video emotion analysis (face-by-face) - Audio emotion analysis (speaker-by-speaker) - Text sentiment analysis - Detected faces and speakers - Overall summaries' operationId: get_video_multimodal_insights_v2_videos__video_id__multimodal_analytics_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique ID of the video title: Video Id description: The unique ID of the video responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FullVideoAnalyticsResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/videos/{video_id}/emotions/average: get: tags: - Video Emotion API summary: Get Average Emotions description: 'Calculate and retrieve average emotion scores for a video with optional face filtering. This endpoint computes the average emotion percentages across all frames in a video. When a face_id is provided, it calculates the average emotions for only that specific face. **Behavior:** - **Without face_id**: Returns overall average emotion score for entire video (all faces combined) - **With face_id**: Calculates average emotion scores for the specified face **Parameters:** - `video_id`: Unique identifier for the video - `face_id`: (Optional) Calculate average emotions for only this face ID **Response:** Returns emotion scores as percentages (values sum to 1.0): - `angry`: Percentage of anger emotion - `disgust`: Percentage of disgust emotion - `fear`: Percentage of fear emotion - `happy`: Percentage of happiness emotion - `sad`: Percentage of sadness emotion - `surprise`: Percentage of surprise emotion - `neutral`: Percentage of neutral emotion **Use Cases:** - **Overall video analysis**: Understand the general emotional tone of the entire video - **Individual tracking**: Track emotional patterns of specific people throughout the video - **Comparative analysis**: Compare emotional profiles between different faces in the same video **Example Usage:** - Overall average: `GET /v2/videos/123/emotions/average` - Face-specific: `GET /v2/videos/123/emotions/average?face_id=1` **Note:** Face-specific calculations require the face to appear in at least one frame.' operationId: get_average_emotions_v2_videos__video_id__emotions_average_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video for which average emotions are to be calculated title: Video Id description: The unique video ID of the video for which average emotions are to be calculated - name: face_id in: query required: false schema: type: integer description: Optional face ID to calculate average emotions for a specific face title: Face Id description: Optional face ID to calculate average emotions for a specific face responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/EmotionScores' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/videos/{video_id}/annotated_video: get: tags: - Video Emotion API summary: Get Annotated Video description: "Get annotated video with emotion labels and bounding boxes overlaid on each frame.\n\n**How It Works:**\n- First request initiates video generation and returns a status response\n- Poll this endpoint to check generation progress\n- When ready, returns a secure signed URL for downloading the video\n\n**Response Types:**\n\n1. **Status Response** (JSON) - While generating:\n ```json\n {\n \"video_id\": \"abc123\",\n \"message\": \"Annotated video is currently being generated...\",\n \"status\": \"pending\"\n }\n ```\n\n2. **Signed URL Response** (JSON) - When complete:\n ```json\n {\n \"video_id\": \"abc123\",\n \"download_url\": \"https://storage.googleapis.com/...\",\n \"filename\": \"My_Video_abc123.mp4\",\n \"expires_in_minutes\": 60,\n \"expires_at\": \"2026-01-09T12:00:00Z\",\n \"note\": \"Download URL will expire. Request a new URL if expired.\"\n }\n ```\n\n**Parameters:**\n- `video_id`: Video identifier\n- `callback_url`: Optional webhook URL to receive notification when generation completes\n\n**Prerequisites:**\nVideo analysis must be complete before requesting annotated video.\n\n**Security:**\n- New videos are stored privately and require signed URLs for access\n- Signed URLs expire after 60 minutes for security\n- Old videos may use public URLs (backward compatibility)\n\n**Example Workflow:**\n\n```python\n# 1. Request annotated video (with optional callback URL)\nGET /v2/videos/abc123/annotated_video?callback_url=https://example.com/webhook\nResponse: {\"status\": \"pending\", \"message\": \"...\"}\n\n# 2. Check status (poll until ready)\nGET /v2/videos/abc123/annotated_video\nResponse: {\"status\": \"in progress\", \"message\": \"...\"}\n\n# 3. Get download URL when ready\nGET /v2/videos/abc123/annotated_video\nResponse: {\"video_id\": \"abc123\", \"download_url\": \"https://...\", ...}\n\n# 4. Download video from the signed URL\nGET \n```" operationId: get_annotated_video_v2_videos__video_id__annotated_video_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video title: Video Id description: The unique video ID of the video - name: callback_url in: query required: false schema: type: string description: Optional callback URL to notify when annotated video generation is complete default: '' title: Callback Url description: Optional callback URL to notify when annotated video generation is complete responses: '200': description: Successful Response content: application/json: schema: anyOf: - $ref: '#/components/schemas/SignedDownloadUrlResponse' - $ref: '#/components/schemas/AnnotatedVideoResponse' title: Response Get Annotated Video V2 Videos Video Id Annotated Video Get '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/valence_arousal: get: tags: - Video Emotion API summary: Get Valence Arousal description: Get emotion intensities of a video based on video_id operationId: get_valence_arousal_v1_videos__video_id__valence_arousal_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video whose emotion intensity is to be fetched title: Video Id description: The unique video ID of the video whose emotion intensity is to be fetched responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ValenceArousalIntensity' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames: get: tags: - Video Emotion API summary: Get Multiple Frame description: API to Retrieve Frames of the video based on video_id. operationId: get_multiple_frame_v1_videos__video_id__frames_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video for which the frames to be fetched title: Video Id description: The unique video ID of the video for which the frames to be fetched - name: start_frame in: query required: false schema: type: string description: The frame number from which retrieval should begin. Defaults to the start of the video if not provided. title: Start Frame description: The frame number from which retrieval should begin. Defaults to the start of the video if not provided. - name: length in: query required: false schema: type: string description: The number of frames to retrieve, starting from 'start_frame'. If omitted, all available frames will be returned. title: Length description: The number of frames to retrieve, starting from 'start_frame'. If omitted, all available frames will be returned. - name: face_ids in: query required: false schema: type: string description: Optional comma-separated list of face IDs (e.g., '1,2,3') default: '' title: Face Ids description: Optional comma-separated list of face IDs (e.g., '1,2,3') responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MultipleFramesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames/{frame_id}: get: tags: - Video Emotion API summary: Get Single Frame description: Get a unique frame details based on video_id and frame_id operationId: get_single_frame_v1_videos__video_id__frames__frame_id__get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video for which the frame to be fetched. title: Video Id description: The unique video ID of the video for which the frame to be fetched. - name: frame_id in: path required: true schema: type: string description: The unique frame ID of the frame to be fetched. title: Frame Id description: The unique frame ID of the frame to be fetched. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FramesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames/{frame_id}/dominant_emotion: get: tags: - Video Emotion API summary: Retrieve Domination Emotion For A Specific Frame description: 'This API endpoint is designed to fetch and return the dominant emotion of frames within a video based on its video_id. If face_id is provided, the dominant emotion of a specific face will be the output.' operationId: retrieve_domination_emotion_for_a_specific_frame_v1_videos__video_id__frames__frame_id__dominant_emotion_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Unique identifier of the video from which the frame’s dominant emotion is to be fetched. title: Video Id description: Unique identifier of the video from which the frame’s dominant emotion is to be fetched. - name: frame_id in: path required: true schema: type: string description: The unique id of the frame from which the dominant emotion is to be fetched. title: Frame Id description: The unique id of the frame from which the dominant emotion is to be fetched. - name: face_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The id of the face whose dominant emotion is to be retrieved. If not provided, the dominant emotion for the entire frame will be returned. title: Face Id description: The id of the face whose dominant emotion is to be retrieved. If not provided, the dominant emotion for the entire frame will be returned. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FrameEmotionResponseData' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames/{frame_id}/valence_arousal: get: tags: - Video Emotion API summary: Retrieve Emotion Intensity description: Retrieve Emotion Intensity for a Specific Frame operationId: retrieve_emotion_intensity_v1_videos__video_id__frames__frame_id__valence_arousal_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video for which the frame's valence, arousal, and intensity are to be fetched. title: Video Id description: The unique video ID of the video for which the frame's valence, arousal, and intensity are to be fetched. - name: frame_id in: path required: true schema: type: string description: The unique frame ID of the frame from which to fetch the valence, arousal, and intensity. title: Frame Id description: The unique frame ID of the frame from which to fetch the valence, arousal, and intensity. - name: face_id in: query required: false schema: anyOf: - type: string - type: 'null' description: The ID of the face whose valence, arousal, and intensity are to be retrieved. If not provided, these values for the entire frame will be returned. title: Face Id description: The ID of the face whose valence, arousal, and intensity are to be retrieved. If not provided, these values for the entire frame will be returned. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ValenceArousalIntensity' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames/{frame_id}/faces/{face_id}/emotions: put: tags: - Video Emotion API summary: Update Emotion Per Frame description: Update the emotion of a specific face in a frame operationId: update_emotion_per_frame_v1_videos__video_id__frames__frame_id__faces__face_id__emotions_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video. title: Video Id description: The unique video ID of the video. - name: frame_id in: path required: true schema: type: string description: The unique frame ID of the frame. title: Frame Id description: The unique frame ID of the frame. - name: face_id in: path required: true schema: type: string description: The unique face ID of the face in the frame. title: Face Id description: The unique face ID of the face in the frame. requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_update_emotion_per_frame_v1_videos__video_id__frames__frame_id__faces__face_id__emotions_put' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/UpdateEmotionResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames/{frame_id}/faces/{face_id}/note: put: tags: - Video Emotion API summary: Edit Face Note description: Update the note associated with a detected face in a frame. operationId: edit_face_note_v1_videos__video_id__frames__frame_id__faces__face_id__note_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video id of the video. title: Video Id description: The unique video id of the video. - name: frame_id in: path required: true schema: type: string description: The unique id of the frame inside the video. title: Frame Id description: The unique id of the frame inside the video. - name: face_id in: path required: true schema: type: string description: The unique id of the face inside the frame. Use '0' to add a note to the entire frame instead of a specific face. title: Face Id description: The unique id of the face inside the frame. Use '0' to add a note to the entire frame instead of a specific face. requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_edit_face_note_v1_videos__video_id__frames__frame_id__faces__face_id__note_put' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/FrameNoteResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/frames/faces: put: tags: - Video Emotion API summary: Update Multiple Faces description: Update Face ID in multiple frames of a video operationId: update_multiple_faces_v1_videos__video_id__frames_faces_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video in which face ID to be changed title: Video Id description: The unique video ID of the video in which face ID to be changed requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_update_multiple_faces_v1_videos__video_id__frames_faces_put' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MultiFaceResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/faces: put: tags: - Video Emotion API summary: Merge Face description: Merge multiple face detections into a single face to remove duplicates from a video. operationId: merge_face_v1_videos__video_id__faces_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video. title: Video Id description: The unique video ID of the video. requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_merge_face_v1_videos__video_id__faces_put' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/MergeResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' delete: tags: - Video Emotion API summary: Delete Faces description: Delete specified faces from a video while ensuring at least one face remains. operationId: delete_faces_v1_videos__video_id__faces_delete security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique identifier of the video from which faces will be deleted. title: Video Id description: The unique identifier of the video from which faces will be deleted. requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_delete_faces_v1_videos__video_id__faces_delete' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/DeleteFacesResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/faces/names: put: tags: - Video Emotion API summary: Update Faces Names description: Updates the names of multiple faces in a video. operationId: update_faces_names_v1_videos__video_id__faces_names_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video. title: Video Id description: The unique video ID of the video. requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/FaceNameItem' description: List of face id and name pairs. title: Face Updates responses: '200': description: Successful Response content: application/json: schema: type: array items: $ref: '#/components/schemas/NameUpdateResponse' title: Response Update Faces Names V1 Videos Video Id Faces Names Put '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/highlights: post: tags: - Video Emotion API summary: Process Highlight description: "Trigger automatic highlight video generation using emotion-based analysis.\n\nAnalyzes video frames to identify emotionally significant moments and generates\na highlight reel. The process runs asynchronously via Celery workers.\n\nArgs:\n video_id: The unique video ID for highlight generation\n user_info: Authenticated user information\n api_info: API request metadata including domain\n\nReturns:\n HighlightGenerateResponse: Contains video_id, processing status, and message\n \nRaises:\n InvalidParams: If video_id is missing\n InvalidUser: If user doesn't own the video\n CreditExpired: If user has insufficient credits\n VideoNotFound: If video doesn't exist or is not completed" operationId: process_highlight_v1_videos_highlights_post requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_process_highlight_v1_videos_highlights_post' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HighlightGenerateResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] /v1/videos/{video_id}/highlights: get: tags: - Video Emotion API summary: Fetch Highlight Video description: API endpoint for highlight generation of a video. operationId: fetch_highlight_video_v1_videos__video_id__highlights_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The video id to get the highlight video url title: Video Id description: The video id to get the highlight video url responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HighlightResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' put: tags: - Video Emotion API summary: Update Highlight Video description: "Generate custom highlight video using user-defined time segments.\n\nCreates a highlight reel by concatenating specific video segments chosen by the user.\nThe process runs asynchronously via Celery workers to handle video processing.\n\nArgs:\n video_id: The unique video ID for which highlights are being generated\n segments: List of time segments with start_millis and end_millis timestamps\n user_info: Authenticated user information\n\nReturns:\n HighlightGenerateResponse: Contains video_id, status=\"queue\", and processing message\n \nRaises:\n InvalidParams: If segments list is empty\n InvalidUser: If user doesn't own the video\n UserVideoException: If segment timestamps are invalid:\n - Both start and end are 0\n - Start equals end\n - Start is greater than or equal to end\n - Timestamps are out of video duration bounds\n CreditExpired: If user has insufficient credits\n VideoNotFound: If video doesn't exist or is not completed" operationId: update_highlight_video_v1_videos__video_id__highlights_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video id of the video for which the update highlight video to be edited. title: Video Id description: The unique video id of the video for which the update highlight video to be edited. requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/SegmentResponse' description: List of video highlight segments title: Segments responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/HighlightGenerateResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/highlight_video: get: tags: - Video Emotion API summary: Download Highlight Video description: Download the highlight video. operationId: download_highlight_video_v1_videos__video_id__highlight_video_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The video id to download the highlight video. title: Video Id description: The video id to download the highlight video. responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/metadata: put: tags: - Video Emotion API summary: Edit Title Or Description By Id description: Edit the title or description of a video based on the provided audio ID. operationId: edit_title_or_description_by_id_v1_videos__video_id__metadata_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Provide the video ID to edit or title and description of the audio title: Video Id description: Provide the video ID to edit or title and description of the audio requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_edit_title_or_description_by_id_v1_videos__video_id__metadata_put' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/VideoEditResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/videos/{video_id}/report: post: tags: - Video Emotion API summary: Generate Video Emotion Analysis Report description: 'Initiates the generation of an analysis report for the specified video. The user will be notified at the provided callback URL once the process is complete.' operationId: generate_video_emotion_analysis_report_v1_videos__video_id__report_post security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: The unique video ID of the video whose analysis report is to be generated. title: Video Id description: The unique video ID of the video whose analysis report is to be generated. requestBody: content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_generate_video_emotion_analysis_report_v1_videos__video_id__report_post' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/GenerateCSVResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' get: tags: - Video Emotion API summary: Download Video Emotion Analysis Report description: Download a videos processed analysis details based on the provided video ID. operationId: download_video_emotion_analysis_report_v1_videos__video_id__report_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Provide the video ID to download analysis title: Video Id description: Provide the video ID to download analysis responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/videos/{video_id}/speaker-face-match: put: tags: - Video Emotion API summary: Update Speaker Face Match description: "Manually match detected faces to identified speakers with bidirectional name synchronization.\n\nThis endpoint enables client-driven multimodal person identification by allowing you to manually\nspecify which detected faces (from video analysis) correspond to which identified speakers \n(from audio analysis). Each mapping synchronizes identity information across video and audio \nmodalities while managing personality analysis data.\n\n## Features\n\n- **Face-to-Speaker Mapping**: Links face IDs (from video) to speaker IDs (from audio)\n- **Bidirectional Name Sync**: Automatically synchronizes names between faces and speakers\n- **Duplicate Prevention**: Validates that each face and speaker is mapped only once\n- **Personality Data Cleanup**: Clears existing personality analysis when mappings change\n- **Batch Operations**: Process multiple mappings in a single request\n\n## Name Synchronization\n\nThe `name` field in each mapping supports bidirectional synchronization:\n\n- **Empty/null name** (`\"\"` or `null`): Fetches the speaker's name from the audio document\n and applies it to the face\n- **Provided name** (e.g., `\"Alice\"`): Updates both the face name AND the speaker name\n in their respective documents\n\nThis ensures consistency across audio and video data while giving you control over\nwhether to use existing speaker names or provide new ones.\n\n## Request Body\n\n```json\n{\n \"mappings\": [\n {\n \"face_id\": 1,\n \"speaker_id\": 0,\n \"name\": \"Alice Johnson\"\n },\n {\n \"face_id\": 2,\n \"speaker_id\": 1,\n \"name\": \"\"\n }\n ]\n}\n```\n\nEach mapping object contains:\n- `face_id` (int, required): ID of detected face from video analysis\n- `speaker_id` (int, required): ID of identified speaker from audio analysis\n- `name` (string, optional): Person's name for synchronization\n\n## Response\n\nReturns a confirmation response:\n```json\n{\n \"status\": \"completed\",\n \"message\": \"Speaker-face matching completed successfully\"\n}\n```\n\n## Prerequisites\n\n- Video must be in \"completed\" status\n- Video must have associated audio document (multimodal analysis)\n- Face IDs must exist in the video's face detections\n- Speaker IDs must exist in the audio's speaker identifications\n\n## Use Cases\n\n1. **Manual Initial Matching**: Manually map speakers to faces after video processing completes\n2. **Name Updates**: Update names while preserving analysis data\n3. **Correction of Auto-Matching**: Override or correct automatic face-to-speaker associations\n4. **Custom Mappings**: Specify mappings based on client-side knowledge or user input\n5. **Prepare for Personality Analysis**: Define mappings before triggering personality analysis\n6. **Batch Processing**: Map multiple face-speaker pairs in a single API call\n\n## Validation Rules\n\n- ✅ Each `face_id` must appear only once in the request (no duplicate faces)\n- ✅ Each `speaker_id` must appear only once in the request (no duplicate speakers)\n- ✅ All `face_id` values must exist in the video document\n- ✅ All `speaker_id` values must exist in the audio document\n- ✅ User must own the video (admin users can access any video)\n\n## Important Notes\n\n- **Manual Operation**: This endpoint requires the client to explicitly provide all \n face-to-speaker mappings. For automatic AI-driven matching, use the POST endpoint.\n- **Personality Data**: When mappings are created or updated, any existing\n personality analysis data for those faces is cleared and must be re-analyzed\n- **Audio Document Updates**: If you provide names, the audio document's speaker\n names are automatically updated to match\n- **Idempotent**: Calling this endpoint multiple times with the same mappings\n will update the entities (not create duplicates)\n\n## Example Scenarios\n\n### Scenario 1: Create New Mappings\n```json\nPUT /v2/videos/abc123/speaker-face-match\n{\n \"mappings\": [\n {\"face_id\": 1, \"speaker_id\": 0, \"name\": \"Alice\"},\n {\"face_id\": 2, \"speaker_id\": 1, \"name\": \"Bob\"}\n ]\n}\n```\n\n### Scenario 2: Use Existing Speaker Names\n```json\nPUT /v2/videos/abc123/speaker-face-match\n{\n \"mappings\": [\n {\"face_id\": 1, \"speaker_id\": 0, \"name\": \"\"},\n {\"face_id\": 2, \"speaker_id\": 1, \"name\": \"\"}\n ]\n}\n```\nNames will be fetched from the audio document's speaker records.\n\n### Scenario 3: Update Names\n```json\nPUT /v2/videos/abc123/speaker-face-match\n{\n \"mappings\": [\n {\"face_id\": 1, \"speaker_id\": 0, \"name\": \"Alice Johnson\"}\n ]\n}\n```\nUpdates both the face name and speaker name to \"Alice Johnson\".\n\n## Error Responses\n\n- **400 Bad Request**: Empty mappings, duplicate face/speaker IDs, or missing audio ID\n- **401 Unauthorized**: Missing authentication\n- **403 Forbidden**: User doesn't own the video\n- **404 Not Found**: Face ID or speaker ID not found in respective documents\n- **422 Unprocessable Entity**: Video processing not completed" operationId: update_speaker_face_match_v2_videos__video_id__speaker_face_match_put security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Unique identifier of the video. Video must be in 'completed' status with associated audio analysis. title: Video Id description: Unique identifier of the video. Video must be in 'completed' status with associated audio analysis. requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/SpeakerFaceMatchRequest' description: 'List of face-to-speaker mappings. Each mapping contains: face_id (detected face from video), speaker_id (identified speaker from audio), and optional name. Name behavior: empty/null fetches from speaker; provided value updates both face and speaker. Validates against duplicate face_id and speaker_id values.' title: Mappings responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SpeakerFaceMatchResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' post: tags: - Video Emotion API summary: Trigger Speaker Face Match description: "Trigger automatic AI-driven speaker-to-face matching for a video.\n\nThis endpoint initiates an asynchronous process that automatically matches\nspeakers from the audio analysis to faces detected in the video using AI.\n\n\n## Prerequisites\n\n- User must be the video owner or an admin\n- Video must be in 'completed' status\n- Audio must be in 'completed' status\n- Video must have an associated audio_id\n\n## Response\n\n```json\n{\n \"video_id\": \"abc123\",\n \"audio_id\": \"xyz789\",\n \"status\": \"processing\",\n \"message\": \"Speaker-face match worker triggered successfully\"\n}\n```\n\n## Error Responses\n\n- **401 Unauthorized**: User is not authenticated or not authorized to access this video\n- **404 Not Found**: Video not found\n- **409 Conflict**: Video or audio processing not completed\n- **400 Bad Request**: Audio ID missing in video document" operationId: trigger_speaker_face_match_v2_videos__video_id__speaker_face_match_post security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Unique identifier of the video. Video must be in 'completed' status with associated audio. title: Video Id description: Unique identifier of the video. Video must be in 'completed' status with associated audio. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AutoSpeakerFaceMatchTriggerResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/videos/{video_id}/personality/analyze: post: tags: - Video Emotion API summary: Trigger Personality Analysis description: "Trigger personality analysis for a specific face in a video.\n\nInitiates asynchronous personality trait assessment based on facial expressions and,\nwhen available, vocal characteristics from linked audio speaker data.\n\n## Analysis Types\n\n- **overall**: Analyzes personality traits across the entire video\n- **by_segment**: Analyzes personality traits by time segments\n- **combined**: Performs both overall and segment analysis\n\nOverall and segment analyses are independent - triggering one does not affect the other.\n\n## Multimodal Analysis\n\n- **Face only**: Analyzes facial expressions when no speaker is linked\n- **Face + Audio**: Combines facial and vocal characteristics when face is linked to a speaker\n\n## Prerequisites\n\n- Video must be completed\n- Face ID must exist in the video\n- If face has speaker mapping: audio must be completed\n- User must have sufficient credits\n\n## Request\n\n```json\n{\n \"face_id\": 1,\n \"analysis_type\": \"overall\",\n \"callback_url\": \"https://example.com/webhook\"\n}\n```\n\n## Response\n\n```json\n{\n \"video_id\": \"abc123\",\n \"face_id\": 1,\n \"speaker_id\": 2,\n \"analysis_type\": \"overall\",\n \"status\": \"processing\",\n \"message\": \"Personality analysis triggered successfully\"\n}\n```\n\n## Notes\n\n- Analysis runs asynchronously in the background\n- Use callback_url for webhook notifications when complete\n- Credits are deducted when analysis is triggered\n- Retrieve results using the video analytics endpoints" operationId: trigger_personality_analysis_v2_videos__video_id__personality_analyze_post security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Unique identifier of the video. Video must be in 'completed' status with detected faces. title: Video Id description: Unique identifier of the video. Video must be in 'completed' status with detected faces. requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/Body_trigger_personality_analysis_v2_videos__video_id__personality_analyze_post' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PersonalityTriggerResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v2/videos/{video_id}/faces/{face_id}/personality-analysis: get: tags: - Video Emotion API summary: Get Personality Analysis description: 'Retrieve OCEAN personality analysis results for a specific face in a video. This endpoint provides comprehensive Big Five (OCEAN) personality trait analysis for a specific face detected in a video. It retrieves both processing status and completed analysis data from dual data sources, returning conditional data based on completion status.' operationId: get_personality_analysis_v2_videos__video_id__faces__face_id__personality_analysis_get security: - APIKeyHeader: [] parameters: - name: video_id in: path required: true schema: type: string description: Unique identifier of the video containing the face. title: Video Id description: Unique identifier of the video containing the face. - name: face_id in: path required: true schema: type: integer minimum: 1 description: Face identifier for which to retrieve personality analysis. title: Face Id description: Face identifier for which to retrieve personality analysis. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PersonalityAnalysisResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError MultiFaceResponse: properties: message: type: string title: Message updated_frames: items: {} type: array title: Updated Frames type: object required: - message - updated_frames title: MultiFaceResponse description: "Response model after updating multiple faces.\n\nAttributes:\n message (str): Operation status or result.\n updated_frames (List): List of frames with updated faces." PaginatedResponse: properties: documents: title: Documents count: type: integer title: Count type: object required: - documents - count title: PaginatedResponse description: "Model for paginated audio emotion responses.\n\nAttributes:\n documents (List[AudioEmotionResponse]): List of audio responses.\n count (int): Total count of documents." MultipleFramesResponse: properties: processed_frames: items: $ref: '#/components/schemas/FramesResponse' type: array title: Processed Frames type: object required: - processed_frames title: MultipleFramesResponse description: Model for returning the MultipleFrame Responses FullVideoAnalyticsResponse: properties: title: type: string title: Title default: '' examples: - Customer Interview - Q4 2025 status: type: string title: Status default: '' examples: - completed description: type: string title: Description default: '' examples: - Quarterly customer satisfaction interview created_at: type: string title: Created At default: '' examples: - '2025-12-01T14:30:00Z' media_type: type: string title: Media Type default: video examples: - video video_id: type: string title: Video Id default: '' examples: - 01a5aceb-8411-4174-b80f-af6789dbd925 audio_id: type: string title: Audio Id default: '' examples: - 1154940c-473f-46cb-a32d-923e6f23bedc text_id: type: string title: Text Id default: '' examples: - c74a3fe1-e8a3-4c7a-98c9-a496ee4a3fb8 duration: type: number title: Duration default: 0 examples: - 20.56 total_frames_count: type: integer title: Total Frames Count default: 0 examples: - 87480 frame_rate: anyOf: - type: number - type: 'null' title: Frame Rate examples: - 30 frame_height: anyOf: - type: number - type: 'null' title: Frame Height examples: - 1080 frame_width: anyOf: - type: number - type: 'null' title: Frame Width examples: - 1920 face_count: type: integer title: Face Count default: 0 examples: - 2 speaker_count: type: integer title: Speaker Count default: 0 examples: - 2 media_source_url: type: string title: Media Source Url default: '' examples: - https://storage.googleapis.com/.../video.mp4 annotated_video_url: type: string title: Annotated Video Url default: '' examples: - https://storage.googleapis.com/.../annotated.mp4 youtube_url: anyOf: - type: string - type: 'null' title: Youtube Url examples: - null detected_faces: items: additionalProperties: true type: object type: array title: Detected Faces examples: - - face_id: 1 image: https://storage.googleapis.com/.../faces/1.jpg name: John Smith - face_id: 2 image: https://storage.googleapis.com/.../faces/2.jpg name: '' detected_speakers: items: additionalProperties: true type: object type: array title: Detected Speakers examples: - - name: John Smith speaker_id: 1 - name: Interviewer speaker_id: 2 emotion_analysis: $ref: '#/components/schemas/EmotionAnalysis' examples: - faces: John Smith: happy: 0.175 neutral: 0.408 sad: 0.049 face_2: angry: 0.087 happy: 0.184 neutral: 0.314 overall: audio: angry: 0.047 happy: 0.185 neutral: 0.638 text: admiration: 0.015 joy: 0.018 neutral: 0.75 video: angry: 0.059 happy: 0.175 neutral: 0.408 sad: 0.049 speakers: Interviewer: audio: angry: 0.05 happy: 0.18 neutral: 0.65 text: curiosity: 0.08 neutral: 0.85 John Smith: audio: angry: 0.045 happy: 0.19 neutral: 0.625 text: admiration: 0.02 joy: 0.025 neutral: 0.72 type: object required: - emotion_analysis title: FullVideoAnalyticsResponse description: Complete multimodal analytics response for video content. HighlightResponse: properties: highlight_status: anyOf: - type: string - type: 'null' title: Highlight Status highlight_url: anyOf: - type: string - type: 'null' title: Highlight Url type: object title: HighlightResponse description: "Model for highlight video response.\n\nAttributes:\n message (str): Status or success message.\n highlight_url (str): URL to the generated highlight video." EmotionAnalysis: properties: overall: $ref: '#/components/schemas/OverallEmotions' examples: - audio: angry: 0.047 happy: 0.185 neutral: 0.638 text: admiration: 0.015 joy: 0.018 neutral: 0.75 video: angry: 0.059 happy: 0.175 neutral: 0.408 sad: 0.049 faces: anyOf: - additionalProperties: additionalProperties: type: number type: object type: object - type: 'null' title: Faces examples: - John Smith: happy: 0.175 neutral: 0.408 sad: 0.049 face_2: angry: 0.087 happy: 0.184 neutral: 0.314 speakers: additionalProperties: $ref: '#/components/schemas/SpeakerEmotions' type: object title: Speakers examples: - Interviewer: audio: angry: 0.05 happy: 0.18 neutral: 0.65 text: curiosity: 0.08 neutral: 0.85 John Smith: audio: angry: 0.045 happy: 0.19 neutral: 0.625 text: admiration: 0.02 joy: 0.025 neutral: 0.72 type: object required: - overall title: EmotionAnalysis description: Hierarchical emotion analysis structure. VideoDeleteResponse: properties: id: type: string title: Id status: type: string title: Status type: object required: - id - status title: VideoDeleteResponse description: "Response after deleting a video entry.\n\nInherits:\n ResponseStatus: Generic response with status and message." VideoEmotionResponseV2: properties: id: type: string title: Id title: type: string title: Title status: type: string title: Status duration: type: integer title: Duration media_source: type: string title: Media Source media_source_url: type: string title: Media Source Url user_id: type: string title: User Id created_at: anyOf: - type: string - type: 'null' title: Created At type: object required: - id - title - status - duration - media_source - media_source_url - user_id title: VideoEmotionResponseV2 description: "V2 response model for video emotion detection with URL source tracking.\n\nSupports:\n- YouTube URLs\n- Cloud storage URLs (Dropbox, direct URLs, etc.)\n- Social Media URLs (Instagram Reels, Facebook videos/reels, Twitter/X status videos)\n- Time parameters for all URL types\n- URL source tracking\n\nAttributes:\n id (str): Unique ID of the video.\n title (str): Title of the video.\n status (str): Processing status (queue, processing, done, etc.).\n duration (int): Duration in seconds (trimmed duration if time params provided).\n media_source (str): Source type (\"youtube\", \"dropbox\", \"instagram\", \"facebook\", \"twitter\", \"public_url\", \"file_upload\").\n media_source_url (str): Full URL as provided by user.\n user_id (str): ID of the user who uploaded the video.\n created_at (Optional[str]): Timestamp when video was created." PersonalitySegmentMetrics: properties: segment_interval_millis: type: integer exclusiveMinimum: 0 title: Segment Interval Millis segments: items: $ref: '#/components/schemas/PersonalitySegmentItem' type: array title: Segments type: object required: - segment_interval_millis - segments title: PersonalitySegmentMetrics description: "Segment-level personality analysis with segment interval and list of segments.\n\nAttributes:\n segment_interval_millis (int): Interval duration in milliseconds\n segments (List[PersonalitySegmentItem]): List of segment data with OCEAN metrics" ReprocessVideoResponse: properties: id: type: string title: Id message: type: string title: Message status: type: string title: Status type: object required: - id - message - status title: ReprocessVideoResponse description: "Response returned after requesting reprocessing of a video.\n\nInherits from:\n GenerateCSVResponse" BoundingBox: additionalProperties: true type: object PersonalityTriggerResponse: properties: video_id: type: string title: Video Id face_id: type: integer title: Face Id speaker_id: anyOf: - type: integer - type: 'null' title: Speaker Id analysis_type: type: string title: Analysis Type status: type: string title: Status message: type: string title: Message type: object required: - video_id - face_id - analysis_type - status - message title: PersonalityTriggerResponse description: "Response model returned after triggering personality processing\nfor a specific face (and optionally a speaker) within a video.\n\nAttributes:\n video_id (str): Unique identifier of the video where personality processing was triggered.\n face_id (int): Identifier of the face entity associated with the personality trigger.\n speaker_id (Optional[int]): Identifier of the linked speaker entity, if applicable; otherwise None.\n analysis_type (str): Type of personality analysis - 'overall', 'by_segment', or 'combined'.\n status (str): Result status of the trigger operation\n message (str): Status message describing the result of the trigger operation." AnnotatedVideoResponse: properties: video_id: type: string title: Video Id message: type: string title: Message status: type: string title: Status type: object required: - video_id - message - status title: AnnotatedVideoResponse description: "Response for annotated video generation status.\n\nAttributes:\n video_id (str): ID of the video.\n message (str): Status message.\n status (str): Current status of annotated video generation (pending, in progress, completed)." AutoSpeakerFaceMatchTriggerResponse: properties: video_id: type: string title: Video Id audio_id: type: string title: Audio Id status: type: string title: Status message: type: string title: Message type: object required: - video_id - audio_id - status - message title: AutoSpeakerFaceMatchTriggerResponse description: "Response model for triggering the automatic speaker-face match worker.\n\nAttributes:\n video_id (str): Unique identifier of the video.\n audio_id (str): Unique identifier of the audio document.\n status (str): Status of the trigger operation (e.g., \"processing\").\n message (str): Informational message about the operation." Body_merge_face_v1_videos__video_id__faces_put: properties: selected_face_id: type: integer title: Selected Face Id description: The unique face ID of the face in the video to be selected. merge_face_id: type: string title: Merge Face Id description: A comma-separated list of unique face IDs of the faces in the video to be merged. type: object required: - selected_face_id - merge_face_id title: Body_merge_face_v1_videos__video_id__faces_put ListOfFaces: properties: faces: items: $ref: '#/components/schemas/Faces' type: array title: Faces type: object required: - faces title: ListOfFaces description: "Model representing a collection of faces.\n\nAttributes:\n faces (List[Faces]): List of detected or named faces." PersonalityOceanMetrics: properties: agreeableness: type: number maximum: 1 minimum: 0 title: Agreeableness conscientiousness: type: number maximum: 1 minimum: 0 title: Conscientiousness extraversion: type: number maximum: 1 minimum: 0 title: Extraversion neuroticism: type: number maximum: 1 minimum: 0 title: Neuroticism openness: type: number maximum: 1 minimum: 0 title: Openness type: object required: - agreeableness - conscientiousness - extraversion - neuroticism - openness title: PersonalityOceanMetrics description: "OCEAN personality trait metrics (Big Five personality traits).\n\nAttributes:\n agreeableness (float): Agreeableness level (0-1 range)\n conscientiousness (float): Conscientiousness level (0-1 range)\n extraversion (float): Extraversion level (0-1 range)\n neuroticism (float): Neuroticism level (0-1 range)\n openness (float): Openness to experience (0-1 range)" VideoResponse: properties: title: type: string title: Title default: '' description: type: string title: Description default: '' id: type: string title: Id audio_id: type: string title: Audio Id default: '' model_id: type: string title: Model Id default: '' emotions_list: items: type: string type: array title: Emotions List default: - angry - contempt - disgust - fear - happy - neutral - sad - surprise url: type: string title: Url faces: $ref: '#/components/schemas/ListOfFaces' annotated_video_mp4: title: Annotated Video Mp4 summary: type: string title: Summary default: '' total_frames_count: type: integer title: Total Frames Count fps: type: number title: Fps height: type: number title: Height width: type: number title: Width status: type: string title: Status created_at: title: Created At default: '' thumbnail_image: type: string title: Thumbnail Image default: '' text_id: type: string title: Text Id default: '' type: object required: - id - status title: VideoResponse description: "Model representing detailed video metadata and analysis.\n\nAttributes:\n title (Optional[str]): Title of the video.\n description (str): Description of the video.\n id (str): Unique video identifier.\n audio_id (str): Related audio ID if extracted.\n model_id (str): Model used to process video.\n emotions_list (List[str]): List of possible emotions.\n url (Any): Original video file url\n faces (ListOfFaces): Detected faces in the video.\n annotated_video_mp4 (Any): Processed video with annotations.\n summary (str): Summary text of the video.\n total_frames_count (Optional[int]): Total number of frames.\n fps (Optional[float]): Frames per second.\n height (Optional[float]): Height of the video.\n width (Optional[float]): Width of the video.\n status (str): Current processing status.\n created_at (str): Creation timestamp.\n thumbnail_image (str): URL or data of the thumbnail image.\n text_id (str): Linked text analysis ID." Body_delete_faces_v1_videos__video_id__faces_delete: properties: face_ids: type: string title: Face Ids description: Comma-separated list of face IDs to delete (e.g., 1,2,3) type: object required: - face_ids title: Body_delete_faces_v1_videos__video_id__faces_delete Body_upload_video_v2_videos_post: properties: title: type: string minLength: 1 title: Title description: A descriptive title for your video (e.g., 'Team Meeting' or 'Customer Interview'). description: type: string title: Description description: Optional notes about the video content or context. video_url: type: string title: Video Url description: 'URL to your video. Supported sources: YouTube, Dropbox, Instagram, Facebook, Twitter (X), or any direct video link. Leave empty if uploading a file instead. ' default: '' start_millis: type: number title: Start Millis description: Start point in milliseconds to begin analysis. Use 0 to start from the beginning. If provided (>0), end_millis is required with minimum 1-second (1000ms) gap. default: 0 end_millis: type: number title: End Millis description: End point in milliseconds to stop analysis. Use 0 only when analyzing the full video (start_millis must also be 0). If start_millis is provided, end_millis is required and must be at least 1000ms greater than start_millis. default: 0 callback_url: type: string title: Callback Url description: Your webhook URL to receive a notification when analysis completes. default: '' video_file: title: Video File description: Upload a video file directly (mp4, avi, mov, webm, mpeg). File upload takes priority over video_url. project_id: type: string title: Project Id description: Optional project ID to associate the video with an existing project. default: '' type: object required: - title title: Body_upload_video_v2_videos_post VideoEditResponse: properties: title: anyOf: - type: string - type: 'null' title: Title description: anyOf: - type: string - type: 'null' title: Description type: object title: VideoEditResponse description: "Response model after editing a video.\n\nInherits:\n ImageEditResponse: Includes status and edit metadata." DeleteFacesResponse: properties: id: type: string title: Id message: type: string title: Message type: object required: - id - message title: DeleteFacesResponse description: "Response model after deleting one or more faces.\n\nAttributes:\n id (str): Video or frame ID the faces belonged to.\n message (str): Confirmation or error message." SpeakerEmotions: properties: audio: additionalProperties: type: number type: object title: Audio examples: - angry: 0.045 happy: 0.19 neutral: 0.625 text: additionalProperties: type: number type: object title: Text examples: - admiration: 0.02 joy: 0.025 neutral: 0.72 type: object title: SpeakerEmotions description: Speaker-specific emotions across audio and text modalities. Body_reprocess_video_v1_videos__video_id__put: properties: callback_url: type: string title: Callback Url description: The callback url to notify video reprocessing is completed. Give a valid URL. reprocess: type: boolean title: Reprocess description: Set to 'True' to reprocess an already completed video; defaults to 'False'. default: false type: object title: Body_reprocess_video_v1_videos__video_id__put NameUpdateResponse: properties: face_id: type: integer title: Face Id name: type: string title: Name type: object required: - face_id - name title: NameUpdateResponse description: "Model for updating the name associated with a face.\n\nAttributes:\n face_id (int): Identifier of the face being updated.\n name (str): New name to assign to the face." SignedDownloadUrlResponse: properties: video_id: type: string title: Video Id download_url: type: string title: Download Url filename: type: string title: Filename expires_in_minutes: type: integer title: Expires In Minutes expires_at: type: string title: Expires At note: type: string title: Note default: Download URL will expire. Request a new URL if expired. type: object required: - video_id - download_url - filename - expires_in_minutes - expires_at title: SignedDownloadUrlResponse description: "Response containing a signed URL for downloading annotated video.\n\nAttributes:\n video_id (str): ID of the video.\n download_url (str): Signed URL for downloading the video file.\n filename (str): Suggested filename for the download.\n expires_in_minutes (int): Number of minutes until the URL expires.\n expires_at (str): ISO 8601 formatted expiration timestamp.\n note (str): Additional information about the download." Body_process_highlight_v1_videos_highlights_post: properties: video_id: type: string title: Video Id description: The unique video ID of the video for which the highlight to be generated. type: object required: - video_id title: Body_process_highlight_v1_videos_highlights_post Body_edit_face_note_v1_videos__video_id__frames__frame_id__faces__face_id__note_put: properties: note: type: string title: Note description: The note to attach to the face or frame. type: object required: - note title: Body_edit_face_note_v1_videos__video_id__frames__frame_id__faces__face_id__note_put Faces: properties: image: type: string title: Image name: anyOf: - type: string - type: 'null' title: Name face_id: type: integer title: Face Id type: object required: - image - face_id title: Faces description: "Model representing a detected face.\n\nAttributes:\n image (str): Image data (base64 or URL) of the face.\n name (Optional[str]): Optional name of the person.\n face_id (int): Unique identifier for the face." Body_update_multiple_faces_v1_videos__video_id__frames_faces_put: properties: frame_ids: type: string title: Frame Ids description: The comma separated list of frame IDs to be updated. current_face_id: type: integer title: Current Face Id description: The face ID to be replaced. new_face_id: type: integer title: New Face Id description: The new face ID to replace with. type: object required: - frame_ids - current_face_id - new_face_id title: Body_update_multiple_faces_v1_videos__video_id__frames_faces_put HighlightGenerateResponse: properties: video_id: type: string title: Video Id message: type: string title: Message status: type: string title: Status type: object required: - video_id - message - status title: HighlightGenerateResponse description: "Model for highlight video generation trigger response.\n\nAttributes:\n video_id (str): The video ID for which highlights are being generated.\n message (str): Status message about the highlight generation process.\n status (str): Current status of highlight generation (queue, processing, completed, failed)." FrameEmotionResponseData: properties: frame_id: type: string title: Frame Id face_id: anyOf: - type: integer - type: 'null' title: Face Id dominant_emotion: anyOf: - type: string - type: 'null' title: Dominant Emotion message: anyOf: - type: string - type: 'null' title: Message type: object required: - frame_id title: FrameEmotionResponseData description: "Model for dominant emotion data of a frame.\n\nAttributes:\n frame_id (str): Identifier for the video frame.\n face_id (Optional[int]): Face ID detected in the frame.\n dominant_emotion (Optional[str]): Most prominent emotion detected.\n message (Optional[str]): Optional message or status info." UpdateEmotionResponse: properties: frame_id: type: string title: Frame Id face_id: type: integer title: Face Id emotions: additionalProperties: type: number type: object title: Emotions type: object required: - frame_id - face_id - emotions title: UpdateEmotionResponse description: "Model representing updated emotion values for a face.\n\nAttributes:\n frame_id (str): Frame identifier.\n face_id (int): ID of the face.\n emotions (Dict[str, float]): Dictionary of emotion scores." FrameNoteResponse: properties: id: type: string title: Id status: type: string title: Status type: object required: - id - status title: FrameNoteResponse description: "Model for response after adding a note to a frame.\n\nAttributes:\n id (str): Frame ID or reference.\n status (str): Status of the note operation." SpeakerFaceMatchRequest: properties: speaker_id: type: integer title: Speaker Id face_id: type: integer title: Face Id name: anyOf: - type: string - type: 'null' title: Name type: object required: - speaker_id - face_id - name title: SpeakerFaceMatchRequest description: "Request model for mapping a detected face to a speaker with an optional name.\n\nAttributes:\n speaker_id (int): Unique identifier for the speaker from audio analysis.\n face_id (int): Unique identifier for the detected face in the video.\n name (Optional[str]): Optional name for the person. If empty/null, fetches from speaker;\n if provided, updates both face and speaker names." Body_update_emotion_per_frame_v1_videos__video_id__frames__frame_id__faces__face_id__emotions_put: properties: angry: type: number title: Angry default: 0 contempt: type: number title: Contempt default: 0 disgust: type: number title: Disgust default: 0 fear: type: number title: Fear default: 0 happy: type: number title: Happy default: 0 neutral: type: number title: Neutral default: 0 sad: type: number title: Sad default: 0 surprise: type: number title: Surprise default: 0 type: object title: Body_update_emotion_per_frame_v1_videos__video_id__frames__frame_id__faces__face_id__emotions_put SegmentResponse: properties: start_millis: type: number title: Start Millis end_millis: type: number title: End Millis type: object required: - start_millis - end_millis title: SegmentResponse description: "Model for a video segment time range.\n\nAttributes:\n start_millis (float): Start time in milliseconds.\n end_millis (float): End time in milliseconds." Body_generate_video_emotion_analysis_report_v1_videos__video_id__report_post: properties: callback_url: type: string title: Callback Url description: The callback URL to notify when video CSV processing is completed. Provide a valid URL. type: object title: Body_generate_video_emotion_analysis_report_v1_videos__video_id__report_post PersonalityAnalysisStatus: properties: status: type: string pattern: ^(pending|processing|completed|failed)$ title: Status percentage: anyOf: - type: integer maximum: 100 minimum: 0 - type: 'null' title: Percentage type: object required: - status title: PersonalityAnalysisStatus description: "Status detail for personality analysis processing.\n\nAttributes:\n status (str): One of: pending, processing, completed, failed\n percentage (Optional[int]): Progress percentage (0-100), only present during processing" OverallEmotions: properties: video: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Video examples: - angry: 0.059 happy: 0.175 neutral: 0.408 sad: 0.049 audio: additionalProperties: type: number type: object title: Audio examples: - angry: 0.047 happy: 0.185 neutral: 0.638 text: additionalProperties: type: number type: object title: Text examples: - admiration: 0.015 joy: 0.018 neutral: 0.75 type: object title: OverallEmotions description: Overall emotions across modalities. GenerateCSVResponse: properties: id: type: string title: Id message: type: string title: Message status: type: string title: Status type: object required: - id - message - status title: GenerateCSVResponse description: "Response after generating a CSV report.\n\nAttributes:\n id (str): ID of the resource associated with the CSV.\n message (str): Confirmation or status message.\n status (str): Current status of the CSV generation." EmotionScores: properties: angry: type: number minimum: 0 title: Angry description: Score for angry default: 0 contempt: type: number minimum: 0 title: Contempt description: Score for contempt default: 0 disgust: type: number minimum: 0 title: Disgust description: Score for disgust default: 0 fear: type: number minimum: 0 title: Fear description: Score for fear default: 0 happy: type: number minimum: 0 title: Happy description: Score for happy default: 0 neutral: type: number minimum: 0 title: Neutral description: Score for neutral default: 0 sad: type: number minimum: 0 title: Sad description: Score for sad default: 0 surprise: type: number minimum: 0 title: Surprise description: Score for surprise default: 0 type: object title: EmotionScores description: 'Emotion scores representing the intensity of each emotion. All scores must be non-negative integers.' ValenceArousalIntensity: properties: valence: type: number title: Valence arousal: type: number title: Arousal intensity: type: number title: Intensity type: object required: - valence - arousal - intensity title: ValenceArousalIntensity description: "Model representing emotional intensity values.\n\nAttributes:\n valence (float): Positive or negative emotion scale.\n arousal (float): Energy or excitement level.\n intensity (float): Overall emotion strength." PersonalitySegmentItem: properties: segment_id: type: integer minimum: 1 title: Segment Id start_millis: type: integer minimum: 0 title: Start Millis end_millis: type: integer exclusiveMinimum: 0 title: End Millis ocean_metrics: $ref: '#/components/schemas/PersonalityOceanMetrics' type: object required: - segment_id - start_millis - end_millis - ocean_metrics title: PersonalitySegmentItem description: "Individual segment data with OCEAN metrics.\n\nAttributes:\n segment_id (int): Unique identifier for this segment\n start_millis (int): Segment start time in milliseconds\n end_millis (int): Segment end time in milliseconds\n ocean_metrics (PersonalityOceanMetrics): OCEAN personality trait scores for this segment" PersonalityAnalysisResponse: properties: video_id: type: string title: Video Id face_id: type: integer minimum: 1 title: Face Id analysis_status: anyOf: - additionalProperties: $ref: '#/components/schemas/PersonalityAnalysisStatus' type: object - type: 'null' title: Analysis Status overall: anyOf: - $ref: '#/components/schemas/PersonalityOverallMetrics' - type: 'null' by_segment: anyOf: - $ref: '#/components/schemas/PersonalitySegmentMetrics' - type: 'null' type: object required: - video_id - face_id title: PersonalityAnalysisResponse description: "Complete response for personality analysis retrieval (public API).\n\nAttributes:\n video_id (str): Video identifier\n face_id (int): Face identifier (must be >= 1)\n analysis_status (Optional[Dict[str, PersonalityAnalysisStatus]]): Status of overall and/or by_segment analysis (only includes keys that exist)\n overall (Optional[PersonalityOverallMetrics]): Overall analysis (only if completed)\n by_segment (Optional[PersonalitySegmentMetrics]): Segment analysis (only if completed)" HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError Body_trigger_personality_analysis_v2_videos__video_id__personality_analyze_post: properties: face_id: type: integer title: Face Id description: Face identifier from video analysis to perform personality assessment on. Must exist in the video's detected faces. analysis_type: type: string title: Analysis Type description: 'Type of personality analysis: ''overall'', ''by_segment'', or ''combined''. Default is ''overall''.' default: overall callback_url: anyOf: - type: string - type: 'null' title: Callback Url description: Optional webhook URL to receive notification when personality analysis completes. Webhook will receive the analysis results as JSON payload. type: object required: - face_id title: Body_trigger_personality_analysis_v2_videos__video_id__personality_analyze_post PersonalityOverallMetrics: properties: ocean_metrics: $ref: '#/components/schemas/PersonalityOceanMetrics' type: object required: - ocean_metrics title: PersonalityOverallMetrics description: "Overall personality analysis metrics.\n\nAttributes:\n ocean_metrics (PersonalityOceanMetrics): OCEAN personality trait scores" FramesResponse: properties: original_frame_image: type: string title: Original Frame Image frame_image: type: string title: Frame Image found_faces: items: type: integer type: array title: Found Faces timestamp: type: integer title: Timestamp faces: items: $ref: '#/components/schemas/BoundingBox' type: array title: Faces frame_id: type: integer title: Frame Id note: type: string title: Note type: object title: FramesResponse description: "Model for a single video frame with face data.\n\nAttributes:\n original_frame_image (str): Unprocessed frame image.\n frame_image (str): Processed frame image with annotations.\n found_faces (List[int]): List of detected face IDs.\n timestamp (int): Timestamp of the frame in milliseconds.\n faces (List[BoundingBox]): Face details including bounding boxes.\n frame_id (int): Frame identifier.\n note (str): Optional notes or remarks." Body_edit_title_or_description_by_id_v1_videos__video_id__metadata_put: properties: title: type: string title: Title description: 'Title to be changed for the video (Max: 50 characters)' description: type: string title: Description description: 'Description to be changed for the video (Max: 300 characters)' type: object title: Body_edit_title_or_description_by_id_v1_videos__video_id__metadata_put MergeResponse: properties: message: type: string title: Message type: object required: - message title: MergeResponse description: "Response model for merging video/audio content.\n\nAttributes:\n message (str): Status message about the merge result." FaceNameItem: properties: face_id: type: integer title: Face Id default: 0 name: type: string title: Name type: object required: - name title: FaceNameItem description: 'Represents a mapping between a face ID and its assigned name. Used for labeling or identifying detected faces.' SpeakerFaceMatchResponse: properties: status: type: string title: Status message: type: string title: Message type: object required: - status - message title: SpeakerFaceMatchResponse description: "Response model for the result of speaker-face matching operations.\n\nAttributes:\n status (str): Status of the operation (e.g., \"completed\").\n message (str): Informational message about the operation result." securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key