openapi: 3.1.0 info: title: Welcome to Imentiv AI AI Insights 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: AI Insights API description: "The AI Insights API provides conversational AI-powered analysis of emotional data from your media content.\n\n**Features:**\n- Ask natural language questions about detected emotions, patterns, and trends\n- Receive AI-generated insights with real-time streaming (SSE)\n- Conversation continuity across multiple messages\n- Works with all media types: video, audio, image, and text\n\n**Endpoints:**\n- `POST /v2/{media_type}/{media_id}/ai-insights` - Send a message and receive AI response (streaming recommended)\n- `GET /v2/{media_type}/{media_id}/ai-insights` - Retrieve conversation history\n\n**Use Cases:** Ideal for gaining deeper insights into emotional patterns, generating summaries, comparing emotional states, and understanding sentiment trends in your media content.\n " paths: /v2/{media_type}/{media_id}/ai-insights: post: tags: - AI Insights API summary: Send message to AI Insights description: 'Send a message to AI Insights and receive an AI-generated response about the media''s emotional analysis. ## Streaming (Recommended) Set `stream=true` (default) to receive the response as Server-Sent Events (SSE) with progressive text chunks. This is the **recommended** approach as it provides real-time feedback and avoids potential timeout issues with longer responses. **SSE Events:** - `stream_start`: Initial event confirming the connection - `metadata`: Contains `conversation_id` and `message_id` - `stream_chunk`: Progressive text chunks from AI - `stream_end`: Final event with complete text and token usage - `done`: Completion signal - `error`: Error event if processing fails (includes `error_id` and `message`) ## Non-Streaming Set `stream=false` to receive the complete response as JSON. **Note:** This mode waits for the full AI response before returning, which may result in longer response times or timeouts for complex queries. Use streaming mode for a better experience. ## Requirements - **Message Length:** Maximum 10,000 characters - **Media Status:** Media processing must be completed (status: "completed") - **Analysis Data:** Emotional analysis data must be available. If not yet ready, you''ll receive error code 1601 — retry after 30–60 seconds. ## Conversation Management The system maintains one conversation per user per media item. Your conversation history is preserved across multiple requests — no need to manage conversation IDs manually. ## Supported Media Types video, audio, image, text' operationId: chat_ai_insights_v2__media_type___media_id__ai_insights_post security: - APIKeyHeader: [] parameters: - name: media_type in: path required: true schema: type: string title: Media Type - name: media_id in: path required: true schema: type: string title: Media Id - name: stream in: query required: false schema: type: boolean description: Enable SSE streaming (true) or return full JSON response (false) default: true title: Stream description: Enable SSE streaming (true) or return full JSON response (false) requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AIInsightsChatRequest' responses: '200': description: AI response (SSE stream or JSON) content: application/json: schema: $ref: '#/components/schemas/AIInsightsChatResponse' example: conversation_id: user123_01 message_id: 1 response: Based on the video analysis, the dominant emotions are... token_usage: input_tokens: 1500 output_tokens: 350 is_quota_exceeded: false text/event-stream: example: 'event: stream_start data: {"status": "initializing"} event: metadata data: {"message_id": 1, "conversation_id": "user123_01"} event: stream_chunk data: {"text": "Based on the video analysis, "} event: stream_chunk data: {"text": "the dominant emotions are..."} event: stream_end data: {"message_id": 1, "full_text": "Based on...", "token_usage": {"input_tokens": 1500, "output_tokens": 350}} event: done data: {} ' '400': description: Bad Request - Analysis data not yet available content: application/json: example: error_id: 1601 message: CSV data not available for video. Please wait for processing to complete. timestamp: '2024-01-15T10:30:00.000000+00:00' '401': description: Unauthorized - Authentication failed content: application/json: example: detail: Invalid User or Not Authorized '404': description: Not Found - Media not found content: application/json: example: detail: Video not found '422': description: Validation Error - Invalid input parameters content: application/json: examples: invalid_media_type: summary: Invalid media type value: detail: 'Invalid media_type. Must be one of: video, audio, image, text' media_not_completed: summary: Media processing not completed value: detail: 'Media processing not completed. Current status: processing' message_too_long: summary: Message exceeds length limit value: detail: '''message'' string should have at most 10000 characters' '500': description: Internal Server Error content: application/json: example: detail: Internal Server Error get: tags: - AI Insights API summary: Get AI Insights conversation history description: 'Retrieve the conversation history for a specific media item''s AI Insights session. ## Response Returns all messages (user questions and AI responses) in chronological order. **Empty History:** If no conversation exists yet, returns an empty `messages` array with a conversation_id. The conversation will be created automatically when you send your first message via POST. ## Supported Media Types video, audio, image, text' operationId: get_ai_insights_history_v2__media_type___media_id__ai_insights_get security: - APIKeyHeader: [] parameters: - name: media_type in: path required: true schema: type: string title: Media Type - name: media_id in: path required: true schema: type: string title: Media Id responses: '200': description: Conversation history retrieved successfully content: application/json: schema: $ref: '#/components/schemas/AIInsightsHistoryResponse' examples: with_messages: summary: Conversation with messages value: conversation_id: user123_01 messages: - role: user text: What emotions were detected? message_id: 1 timestamp: '2024-01-15T10:30:00.000000' - role: ai_assistant text: Based on the analysis, the dominant emotions are... message_id: 1 timestamp: '2024-01-15T10:30:05.000000' empty_history: summary: No conversation yet value: conversation_id: user123_01 messages: [] '401': description: Unauthorized - Authentication failed content: application/json: example: detail: Invalid User or Not Authorized '404': description: Not Found - Media not found content: application/json: example: detail: Video not found '422': description: Validation Error - Invalid input parameters content: application/json: example: detail: 'Invalid media_type. Must be one of: video, audio, image, text' components: schemas: AIInsightsChatMessage: properties: role: type: string title: Role description: 'Message role: ''user'' or ''ai_assistant''' text: type: string title: Text description: Message content message_id: type: integer title: Message Id description: Message ID timestamp: anyOf: - type: string - type: 'null' title: Timestamp description: ISO 8601 timestamp type: object required: - role - text - message_id title: AIInsightsChatMessage description: "Individual message in conversation history.\n\nAttributes:\n role (str): Message role - \"user\" or \"ai_assistant\".\n text (str): Message text content.\n message_id (int): Message ID within the conversation.\n timestamp (Optional[str]): ISO 8601 timestamp when message was created." AIInsightsHistoryResponse: properties: conversation_id: type: string title: Conversation Id description: Conversation session ID messages: items: $ref: '#/components/schemas/AIInsightsChatMessage' type: array title: Messages description: Conversation message history type: object required: - conversation_id - messages title: AIInsightsHistoryResponse description: "Response model for retrieving AI Insights conversation history.\n\nAttributes:\n conversation_id (str): The conversation session ID.\n messages (List[AIInsightsChatMessage]): List of messages in chronological order\n (user messages and AI responses)." AIInsightsChatRequest: properties: message: type: string maxLength: 10000 minLength: 1 title: Message description: User's question or message about the media content type: object required: - message title: AIInsightsChatRequest description: "Request model for sending a message to AI Insights (REST API).\n\nThe system automatically manages conversation continuity - one conversation per user per media item.\n\nAttributes:\n message (str): The user's question or message about the media content." AIInsightsChatResponse: properties: conversation_id: type: string title: Conversation Id description: Conversation session ID message_id: type: integer title: Message Id description: Message ID within conversation response: type: string title: Response description: AI assistant's complete response token_usage: anyOf: - additionalProperties: type: integer type: object - type: 'null' title: Token Usage description: Token usage (input_tokens, output_tokens) is_quota_exceeded: type: boolean title: Is Quota Exceeded description: Whether LLM quota exceeded default: false type: object required: - conversation_id - message_id - response title: AIInsightsChatResponse description: "Response model for AI Insights chat (non-streaming mode with ?stream=false).\n\nAttributes:\n conversation_id (str): Unique identifier for this conversation session.\n message_id (int): Sequential message ID within the conversation.\n response (str): The complete AI assistant's response text.\n token_usage (Optional[Dict[str, int]]): LLM token usage statistics\n (input_tokens, output_tokens).\n is_quota_exceeded (bool): Whether the user's LLM quota has been exceeded." securitySchemes: APIKeyHeader: type: apiKey in: header name: X-API-Key