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.
openapi: 3.1.0
info:
title: Welcome to Imentiv AI AI Insights API Image 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: 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.\n "
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:
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."
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.
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
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
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
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."
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_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
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."
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.
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
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
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.
securitySchemes:
APIKeyHeader:
type: apiKey
in: header
name: X-API-Key