> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.coactive.ai/latest/docs-guides/getting-started/accepted-media-formats/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.coactive.ai/_mcp/server.

The Coactive Ingestion API enables users to upload image and video assets for high-speed, scalable processing on the Coactive platform. Designed for performance at scale, it efficiently ingests large volumes of content across various formats, resolutions, and durations.

By automating video processing, intelligent keyframe selection, and indexing, Coactive transforms raw media into instantly searchable and organized assets, unlocking features like AI-powered search, dynamic tags, and advanced analytics. This document outlines accepted asset formats, resolutions, and CSV submission requirements.

## Upload Methods

Users can upload assets to Coactive in the following ways:

* **Cloud Storage** – Provide an S3 file path to a single asset or millions of assets stored in an S3 bucket.
* **List of Assets** - Provide a list of up to 100 asset S3 paths, public or pre-signed URLs.
* **Batch CSV/JSON** Upload\* – Submit 1 to 100,000 rows of assets via CSV or JSON file.
  > **Note**
  >
  > For bulk ingestions of more than 100 assets, using S3 URLs is recommended for efficiency. If using non-public URLs, please use our [Connections API](https://docs.coactive.ai/api-reference/api-reference/connections/create-connection) or [contact us](https://coactive.ai/contact) to help facilitate providing the proper credentials for a seamless ingestion process.

## Supported Image Formats

**`Supported Image Formats`**

```txt title="Supported Image Formats" wordWrap
.jpg
.jpeg
.png
.ppm
.bmp
.pgm
.tif
.tiff
.webp
.ico
.svg
.heic
.heif
```

> **Success**
>
> `.jpg` is the preferred format and provides the fastest ingestion performance.

The maximum supported image file size is **15 MB**.

### Image dimensions and aspect ratio

Images must meet the following requirements:

| Requirement                | Limit                                   |
| -------------------------- | --------------------------------------- |
| **Maximum resolution**     | 64 megapixels (64 million total pixels) |
| **Maximum dimension**      | 16,000 pixels on either side            |
| **Supported aspect ratio** | Up to 4:1 or 1:4                        |

For example, an 8,000 × 8,000 image is within the 64-megapixel limit. A 16,000 × 4,000 image is also supported because it is 64 megapixels, does not exceed 16,000 pixels on its longest side, and has a 4:1 aspect ratio.

> **Tip**
>
> For best results, Coactive recommends images with a minimum resolution of **350 × 350 pixels**.

## Supported Video Formats

#### Format

**`Format`**

```txt title="Format"
.ts
.mp4
.mkv
.webm
.flv
.avi
.mpg
```

#### Video Codec

**`Video Codec`**

```txt title="Video Codec"
.MPEG-2
.H.264
.H.265
.MPEG-4
.VP8
.VP9
.flv
```

#### Audio Codec

**`Audio Codec`**

```txt title="Audio Codec"
.aac
.ac3
.opus
.vorbis
.mp3
```

> **Warning**
>
> Please ensure that the format, video codec and audio codec are supported.

Key Considerations:

* Recommended format: H.264 .mp4
* Minimum video length: 5 seconds
* Maximum supported video length: 5 hours

> **Note**
>
> For videos longer than 5 hours, [please contact us](https://coactive.ai/contact) since this requires special handling and coordination with our team.

### Accepted Resolutions & Frame Rates

#### Accepted Video Resolutions

Coactive processes videos in their original resolution without modifications. However, AI processing models work best at 360p.

* 240p
* 360p (Recommended for AI processing)
* 480p
* 720p
* 1080p

#### Frame Rate Guidelines

* Recommended FPS: 30fps
* Supported FPS: Up to 60fps (higher FPS will increase processing time)

## CSV Submission Guidelines

Coactive supports using CSV files with **public URLs**, allowing users to associate metadata with video and image assets.

### File Submission Rules

* File Format: Must be a valid CSV (Comma-Separated Values) file.
* Encoding: UTF-8 is required.
* File Size Limits: 10mb

### Header Line

The file must have exactly one header row with at least one column:

* `source_path`: Required and is the path to the asset either s\:// or http\:// or https\://
* `asset_type`: optional and if provided, it must be one of the following values:
  * unspecified
  * image
  * video
* Headers must follow these rules:
  * No spaces – Use camelCase or snake\_case (e.g., customerID, customer\_id).
  * Cannot contain special characters:  , ;  ( ) = \ \n \t
  * Case-sensitive – Headers are preserved exactly as submitted. (e.g., CustomerID remains CustomerID).

### Metadata

* All other columns are treated as string metadata.
* Column order does not matter.

#### Valid CSV Example

![CSV Example](/_fern-img/783115bd50491e270082169c0cc0aab04654f598a783ed77ad60b088e53839af.webp)