---
title: "Upload Image"
method: POST
path: "/v2/images"
tags: ["Image Emotion API"]
---

# Upload Image

`POST /v2/images`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/images`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.imentiv.ai/oauth/authorize`
    - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `media.write`

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:**
- 10 credits per image
- Enterprise plans: 5 credits per image

## Request body `multipart/form-data`

- BodyUploadImageV2ImagesPost
  - `title` string, required: A descriptive title for your image (e.g., 'Customer Reaction' or 'Team Photo').
  - `description` string: Optional notes about the image content or context.
  - `image_url` string: URL to your image source (Dropbox or any direct image link). Leave empty if uploading a file instead.
  - `callback_url` string: Your webhook URL to receive a notification when analysis completes. Must be an https URL on a publicly reachable host.
  - `image_file` string, binary: Upload an image file directly (jpg, jpeg, png, webp). File upload takes priority over image_url.

## Response `200`

Successful Response

- ImageEmotionResponseV2: V2 response model for image emotion detection with URL source tracking. Supports: - File uploads (JPG, JPEG, PNG, WEBP) - Cloud storage URLs (Dropbox, direct URLs) - URL source tracking Attributes: id (str): Unique ID of the image. title (str): Title of the image. status (str): Processing status ("queue"). media_source (str): Source type ("dropbox", "public_url", "file_upload"). media_source_url (str): Full URL as provided by user or uploaded file URL. media_source_type (str): Type of source media (always "image" for this endpoint). user_id (str): ID of the user who uploaded the image. created_at (Optional[str]): Timestamp when image was created.
  - `id` string, required
  - `title` string, required
  - `status` string, required
  - `media_source` string, required
  - `media_source_url` string, required
  - `media_source_type` string, required
  - `user_id` string, required
  - `created_at` string, nullable

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-22** `536bf48bb9fb`: 3 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
  - the endpoint scheme security `BearerAuth` was added to the API
  - the endpoint scheme security `OAuth2Delegated` was added to the API
- **2026-09-08** `b10651168511`: 1 info
  - the `image_file` request property type was generalized from no type to `string`, and format from no format to `binary`
- **2026-08-20** `74ceee4a5c98`: 1 info
  - the `description` request property default value `` was added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/images/post.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)