Imentiv AI Image Emotion API

openapi: 3.2.0
info:
  title: Welcome to Imentiv AI Image Emotion 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: Image Emotion API
  description: The Image Emotion Recognition API by Imentiv analyzes human facial expressions in an image and returns the detected emotions. It can detect multiple faces and evaluate each face's emotional state, providing detailed emotional labels such as happy, sad, angry, neutral, surprise, disgust, fear, and contempt.
paths:
  /v2/images:
    post:
      tags:
      - Image Emotion API
      summary: Upload Image
      description: 'Analyze emotions and facial expressions from image content.


        Submit an image from multiple sources and receive detailed emotion analysis

        of all detected faces in the image.


        **Input Sources:**

        - **Cloud Storage**: Dropbox or other cloud service links

        - **Direct URL**: Any publicly accessible image link

        - **File Upload**: Upload image files directly from your device


        **How It Works:**

        1. Submit your image and receive an immediate response with an image ID

        2. Image is queued for processing (typically completes within seconds)

        3. Optionally receive a webhook notification via `callback_url` when complete

        4. Retrieve results using the image ID


        **Supported Formats:**

        JPG, JPEG, PNG, WEBP


        **Credit Usage:**

        - UI: 10 credits per image

        - API: 5 credits per image'
      operationId: upload_image_v2_images_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_image_v2_images_post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageEmotionResponseV2'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
      - APIKeyHeader: []
  /v1/images:
    get:
      tags:
      - Image Emotion API
      summary: List Images
      description: 'Retrieves a paginated list of all uploaded or processed images.

        Use this endpoint to browse through image records based on their ID, status, and title.'
      operationId: list_images_v1_images_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: start_after
        in: query
        required: false
        schema:
          type: string
          description: ID of the last image from the previous page. Fetches results after this ID.
          title: Start After
        description: ID of the last image from the previous page. Fetches results after this ID.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          description: Number of results to return per page. The default is 10.
          default: 10
          title: Page Size
        description: Number of results to return per page. The default is 10.
      - name: direction
        in: query
        required: false
        schema:
          type: string
          description: 'Pagination direction: ''forward'' or ''backward''. Default is ''forward'''
          default: forward
          title: Direction
        description: 'Pagination direction: ''forward'' or ''backward''. Default is ''forward'''
      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/images/{image_id}:
    get:
      tags:
      - Image Emotion API
      summary: Get Image Emotion Analysis
      description: 'Retrieves detailed emotion analysis results and metadata for a specific uploaded image.

        Includes detected faces, their emotional scores, image dimensions, and annotated visualizations.'
      operationId: get_image_emotion_analysis_v1_images__image_id__get
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: Unique ID of the image to retrieve.
          title: Image Id
        description: Unique ID of the image to retrieve.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageDBResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Image Emotion API
      summary: Delete Image
      description: Deletes a specific image and all associated emotion analysis data from the system. This action is irreversible.
      operationId: delete_image_v1_images__image_id__delete
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: Unique ID of the image
          title: Image Id
        description: Unique ID of the image
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageDeleteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - Image Emotion API
      summary: Reprocess Image
      description: 'Reprocesses an image that has either failed or completed.

        You can trigger the reprocessing by setting reprocess to True.

        This will reanalyze the image and provide updated insights.'
      operationId: reprocess_image_v1_images__image_id__put
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: The unique image ID of the image.
          title: Image Id
        description: The unique image ID of the image.
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_reprocess_image_v1_images__image_id__put'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageReprocessResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/images/{image_id}/annotated_image:
    get:
      tags:
      - Image Emotion API
      summary: Send Image
      description: Downloads the annotated version of the image, which highlights detected faces and their corresponding emotions.
      operationId: send_image_v1_images__image_id__annotated_image_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: Unique ID of the image.
          title: Image Id
        description: Unique ID of the image.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/images/{image_id}/faces/{face_id}/note:
    put:
      tags:
      - Image Emotion API
      summary: Add Note To Specific Face
      description: Adds or updates a note attached to a specific face detected in an image.
      operationId: add_note_to_specific_face_v1_images__image_id__faces__face_id__note_put
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: The unique image ID of the image
          title: Image Id
        description: The unique image ID of the image
      - name: face_id
        in: path
        required: true
        schema:
          type: string
          description: Unique ID of the face within the image
          title: Face Id
        description: Unique ID of the face within the image
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_add_note_to_specific_face_v1_images__image_id__faces__face_id__note_put'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageNoteResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/images/{image_id}/metadata:
    put:
      tags:
      - Image Emotion API
      summary: Edit Image Metadata
      description: Edit image title and description of the uploaded image
      operationId: edit_image_metadata_v1_images__image_id__metadata_put
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: Provide the image ID to edit the title or description of the image
          title: Image Id
        description: Provide the image ID to edit the title or description of the image
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_edit_image_metadata_v1_images__image_id__metadata_put'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImageEditResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/images/{image_id}/report:
    get:
      tags:
      - Image Emotion API
      summary: Download Image Emotion Report
      description: 'Downloads the emotion analysis insights for a specific image in CSV format.

        The report includes detected faces and their associated emotion scores.'
      operationId: download_image_emotion_report_v1_images__image_id__report_get
      security:
      - APIKeyHeader: []
      parameters:
      - name: image_id
        in: path
        required: true
        schema:
          type: string
          description: Unique ID of the image
          title: Image Id
        description: Unique ID of the image
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '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
    ImageDeleteResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
      type: object
      required:
      - id
      - status
      title: ImageDeleteResponse
      description: Response returned after deleting an image analysis result.
    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."
    ImageNoteResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
      type: object
      required:
      - id
      - status
      title: ImageNoteResponse
      description: Response after updating or retrieving notes for an image.
    Body_upload_image_v2_images_post:
      properties:
        title:
          type: string
          maxLength: 150
          minLength: 1
          title: Title
          description: A descriptive title for your image (e.g., 'Customer Reaction' or 'Team Photo').
        description:
          type: string
          maxLength: 300
          title: Description
          description: Optional notes about the image content or context.
        image_url:
          type: string
          title: Image Url
          description: URL to your image source (Dropbox or any direct image link). Leave empty if uploading a file instead.
          default: ''
        callback_url:
          type: string
          title: Callback Url
          description: Your webhook URL to receive a notification when analysis completes.
          default: ''
        image_file:
          title: Image File
          description: Upload an image file directly (jpg, jpeg, png, webp). File upload takes priority over image_url.
      type: object
      required:
      - title
      title: Body_upload_image_v2_images_post
    ImageDBResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        title:
          type: string
          title: Title
        description:
          type: string
          title: Description
        created_at:
          title: Created At
        original_frame_image:
          title: Original Frame Image
        height:
          type: number
          title: Height
        width:
          type: number
          title: Width
        found_faces:
          items:
            type: integer
          type: array
          title: Found Faces
        faces:
          title: Faces
        annotated_image:
          title: Annotated Image
      type: object
      required:
      - id
      - status
      - title
      - description
      - created_at
      - original_frame_image
      - height
      - width
      - found_faces
      - faces
      - annotated_image
      title: ImageDBResponse
      description: "Detailed response model for image emotion stored in DB.\n\nAttributes:\n    title (str): Title of the image.\n    description (str): Description provided by the user.\n    created_at (Any): Timestamp when image was added.\n    original_frame_image (Any): Original image file.\n    height (float): Height of the image.\n    width (float): Width of the image.\n    found_faces (int): Number of faces detected.\n    faces (Any): Detailed face data.\n    annotated_image (Any): Image with annotations (e.g., bounding boxes)."
    Body_reprocess_image_v1_images__image_id__put:
      properties:
        callback_url:
          type: string
          title: Callback Url
          description: The callback url to notify image reprocessing is completed. Give a valid URL.
        reprocess:
          anyOf:
          - type: boolean
          - type: string
          title: Reprocess
          description: Set to 'True' to reprocess an already completed image; defaults to 'False'.
          default: false
      type: object
      title: Body_reprocess_image_v1_images__image_id__put
    Body_add_note_to_specific_face_v1_images__image_id__faces__face_id__note_put:
      properties:
        note:
          type: string
          title: Note
          description: Note to be updated for the detected face in the image
          default: ''
      type: object
      title: Body_add_note_to_specific_face_v1_images__image_id__faces__face_id__note_put
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Body_edit_image_metadata_v1_images__image_id__metadata_put:
      properties:
        title:
          type: string
          title: Title
          default: ''
        description:
          type: string
          title: Description
          default: ''
        callback_url:
          anyOf:
          - type: string
          - type: 'null'
          title: Callback Url
        image_url:
          type: string
          title: Image Url
          default: ''
      type: object
      title: Body_edit_image_metadata_v1_images__image_id__metadata_put
    ImageReprocessResponse:
      properties:
        id:
          type: string
          title: Id
        status:
          type: string
          title: Status
        message:
          type: string
          title: Message
      type: object
      required:
      - id
      - status
      - message
      title: ImageReprocessResponse
      description: Response model returned after reprocessing an image emotion analysis.
    ImageEditResponse:
      properties:
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
      type: object
      title: ImageEditResponse
      description: "Model for editing image metadata.\n\nAttributes:\n    title (str): Updated title.\n    description (str): Updated description."
    ImageEmotionResponseV2:
      properties:
        id:
          type: string
          title: Id
        title:
          type: string
          title: Title
        status:
          type: string
          title: Status
        media_source:
          type: string
          title: Media Source
        media_source_url:
          type: string
          title: Media Source Url
        media_source_type:
          type: string
          title: Media Source Type
        user_id:
          type: string
          title: User Id
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      required:
      - id
      - title
      - status
      - media_source
      - media_source_url
      - media_source_type
      - user_id
      title: ImageEmotionResponseV2
      description: "V2 response model for image emotion detection with URL source tracking.\n\nSupports:\n- File uploads (JPG, JPEG, PNG, WEBP)\n- Cloud storage URLs (Dropbox, direct URLs)\n- URL source tracking\n\nAttributes:\n    id (str): Unique ID of the image.\n    title (str): Title of the image.\n    status (str): Processing status (\"queue\").\n    media_source (str): Source type (\"dropbox\", \"public_url\", \"file_upload\").\n    media_source_url (str): Full URL as provided by user or uploaded file URL.\n    media_source_type (str): Type of source media (always \"image\" for this endpoint).\n    user_id (str): ID of the user who uploaded the image.\n    created_at (Optional[str]): Timestamp when image was created."
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key