Imentiv AI AI Insights API

openapi: 3.2.0
info:
  title: Welcome to Imentiv AI AI Insights API
  description: '# Welcome to Imentiv AI


    Imentiv 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.'
  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.
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:
    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."
    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."
    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)."
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key