Vision AI Agents API Reference

The Vision AI Agents API enables developers to ingest video content, run intelligence analysis, perform audience testing, and retrieve results using structured and vector search.

Base URL

All API requests are made against the following base endpoint.

https://api.roboticaxai.com

Authentication

All API requests must include an API key in the Authorization header.

Authentication Headers

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

Example:

Authorization: Bearer YOUR_API_KEY

API Workflow

Vision AI Agents follows a structured video intelligence pipeline. Each video must first be ingested to generate a system video ID before analysis or search operations can occur.

Video Upload
     ↓
Video ID Generated
     ↓
Video Intelligence Analysis
     ↓
Optional Audience Testing
     ↓
Indexes + Vector Embeddings Created
     ↓
Search APIs Retrieve Results

Video Ingest APIs

Video ingest APIs upload video content into the platform and generate the system video_id. All downstream intelligence, audience testing, and search APIs depend on this identifier.

Ingest Video

Upload a single video for processing and analysis.

Endpoint

POST /api/video/ingest

Request Example

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

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

Request Parameters

Field	Type	Required	Description	Example
video_url	string	Yes	Publicly accessible video URL	https://example.com/video.mp4
analysis	string	No	Run full or selective analysis	full

Response Example

{
  "video_id": "vid_8932jfks92",
  "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	Current processing state
message	string	Human-readable processing message

Batch Video Ingest

Upload multiple videos in a single request.

Endpoint

POST /api/video/batch-ingest

Request Example

{
  "videos": [
    "https://example.com/video1.mp4",
    "https://example.com/video2.mp4"
  ]
}

Request Fields

Field	Type	Required	Description
videos	array	Yes	List of video URLs to ingest

Response Example

{
  "batch_id": "batch_734893",
  "videos_ingested": 2,
  "status": "processing"
}

Response Fields

Field	Type	Description
batch_id	string	Unique identifier for the ingest batch
videos_ingested	integer	Total videos accepted for ingest
status	string	Processing status

Video Intelligence APIs

Video intelligence APIs run analysis pipelines on previously ingested videos. Developers can run either full analysis or request selective analytics modules.

Run Video Analysis

Endpoint

POST /api/video/analyze

Request Parameters

Field	Type	Required	Description
video_id	string	Yes	Video identifier returned from ingest
analysis_type	string	No	Run full analysis
analysis_modules	array	No	Specific analysis modules to run

Response Example

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

Video Intelligence Domains

Vision AI Agents extracts multiple intelligence signals across several analysis domains to understand both narrative structure and audience engagement.

Domain	Description
Scene Actor Analytics	Measures actor emotion engagement and attention
Scene Elements Analysis	Detects audio patterns, script linguistics, and color traversal
Scene Psychology Analysis	Classifies emotional signals from audio, color, and script
Crescendo Detection	Identifies narrative peaks and high-impact scenes

Audience Testing APIs

Audience testing is optional and must be explicitly requested through the API. Each request may include up to ten participants.

Request Audience Test

Endpoint

POST /api/audience/test

Request Parameters

Field	Type	Required	Description
video_id	string	Yes	Video ID generated by ingest
participants	integer	Yes	Number of audience participants (max 10)
analytics	array	No	Selected analytics modules

Response Example

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

Search APIs

Search APIs allow developers to retrieve indexed intelligence signals and vector-embedded scene results from analyzed videos.

Endpoint

POST /api/search/query

Search Request Parameters

Parameter	Type	Required	Description
query	string	Yes	Semantic search query
filters	object	No	Metadata filters applied to results
limit	integer	No	Maximum results returned

Response Fields

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

Rate Limits

API usage limits vary by developer tier. Limits apply to concurrent requests, daily API calls, and monthly token consumption.

Tier	Concurrent Requests	Daily Max Requests	Monthly Token Limit
Tier 0	5	500	50,000
Tier 1	10	2,000	250,000
Tier 2	20	10,000	1,000,000
Tier 3	40	25,000	5,000,000
Tier 4	80	100,000	Custom Enterprise

Error Codes

The API returns standard HTTP status codes.

Code	Name	Description
200	Success	Request successful
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid API key
404	Not Found	Resource not found
429	Rate Limit Exceeded	Usage limits exceeded
500	Internal Server Error	Unexpected server error

Example Integration Flow

Typical developer integration follows this sequence.

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

Support

For integration assistance or enterprise access, contact:

support@roboticaxai.com