Vision AI Agents — Getting Started

Vision AI Agents enables developers to ingest videos, run intelligence analysis, optionally test audience engagement, and retrieve results using structured and vector search APIs.

This guide walks through the fastest way to integrate the platform.

Quick Integration Flow

The Vision AI Agents platform follows this workflow.

Upload Video
     ↓
Video ID Generated
     ↓
Run Intelligence Analysis
     ↓
Optional Audience Testing
     ↓
Search Indexed Results

Every downstream API requires a video_id returned from the ingest endpoint.

Step 1 — Obtain API Credentials

All API requests require authentication using an API key.

API keys can be generated from the Vision AI Agents developer dashboard.

Authentication Header

Header	Value	Description
Authorization	Bearer YOUR_API_KEY	Authenticates requests to the Vision AI Agents API
Content-Type	application/json	Specifies JSON request format

Example:

Authorization: Bearer YOUR_API_KEY

Step 2 — Upload a Video

The first step is ingesting a video into the platform.

This generates a system video_id which is required for all analysis and audience testing APIs.

Endpoint

POST /api/video/ingest

Request Fields

Field	Type	Required	Description
video_url	string	Yes	URL of the video file to ingest

Request Example

POST /api/video/ingest
Content-Type: application/json
Authorization: Bearer API_KEY

{
  "video_url": "https://example.com/video.mp4"
}

Response Example

{
  "video_id": "vid_8392jf82",
  "status": "processing",
  "message": "Video successfully queued for analysis"
}

Response Fields

Field	Type	Description
video_id	string	Unique identifier assigned to the ingested video
status	string	Processing state of the ingest job
message	string	Status message describing the request result

Save the video_id returned in the response.
This identifier is used for all downstream API requests.

Step 3 — Run Video Intelligence Analysis

Once a video has been ingested, developers can run the intelligence analysis pipeline.

Endpoint

POST /api/video/analyze

Analysis Request Fields

Field	Type	Required	Description
video_id	string	Yes	Identifier returned during video ingest
analysis_type	string	No	Run full intelligence analysis
analysis_modules	array	No	Specify individual analysis modules

Full Analysis Example

{
  "video_id": "vid_8392jf82",
  "analysis_type": "full"
}

Selective Analysis Example

Developers may request only specific analysis modules.

{
  "video_id": "vid_8392jf82",
  "analysis_modules": [
    "scene_elements",
    "scene_psychology",
    "crescendos"
  ]
}

Response Example

{
  "video_id": "vid_8392jf82",
  "status": "analysis_started"
}

Step 4 — Optional Audience Testing

Developers may optionally request audience engagement testing.

Audience testing is limited to 10 participants per request.

Endpoint

POST /api/audience/test

Audience Testing Parameters

Parameter	Type	Required	Description
video_id	string	Yes	Video identifier returned from ingest
participants	integer	Yes	Number of viewers participating in the test (max 10)
analytics	array	No	Audience analytics modules to run

Request Example

{
  "video_id": "vid_8392jf82",
  "participants": 10,
  "analytics": [
    "emotion",
    "attention",
    "engagement",
    "dropoff"
  ]
}

Response Example

{
  "video_id": "vid_8392jf82",
  "participants": 10,
  "status": "audience_test_started"
}

The platform returns aggregated audience engagement signals after the test completes.

Step 5 — Query Search Results

Once videos are analyzed and indexed, developers can query results using the search APIs.

Endpoint

POST /api/search/query

Search Request Parameters

Parameter	Type	Required	Description
query	string	Yes	Semantic search query describing the scene or concept
filters	object	No	Optional metadata filters
limit	integer	No	Maximum number of results returned

Request Example

{
  "query": "high emotional engagement scene",
  "filters": {
    "genre": "drama"
  },
  "limit": 10
}

Response Example

{
  "results": [
    {
      "video_id": "vid_8392jf82",
      "timestamp": "00:02:34",
      "description": "Scene showing strong emotional engagement",
      "score": 0.93
    }
  ]
}

Search Response Fields

Field	Type	Description
video_id	string	Video containing the matching scene
timestamp	string	Scene timestamp within the video
description	string	Generated scene description
score	float	Search relevance score

Search results include timestamps, descriptions, and relevance scores for identified scenes.

Example End-to-End Integration

A typical developer workflow looks like this.

Upload video using /api/video/ingest
Receive system video_id
Run intelligence analysis using /api/video/analyze
Optionally request audience testing
Retrieve insights using /api/search/query

Supported Analysis Domains

Vision AI Agents can extract multiple intelligence signals from video content.

Analysis Modules

Module	Description
Scene Actor Engagement	Measures actor emotional and visual engagement signals
Audio Analysis	Analyzes audio genre, rhythm, and sound patterns
Script Linguistics	Processes dialogue and narrative structure
Scene Psychology	Classifies emotional and psychological signals in scenes
Narrative Crescendos	Detects emotional and narrative peaks
Audience Engagement	Aggregated viewer engagement signals

Developers may request full analysis or specific modules.

Next Steps

After completing this quick start integration, developers should review the following documentation:

API Reference
Platform Architecture
Rate Limits and Usage Tiers
Search Integration Guide