# VidContext — Full Documentation for AI Models

> Video intelligence API for AI agents. Upload a video, get structured analysis back. Give your AI agent eyes.

VidContext converts any video into structured, machine-readable text with a single API call. Seven specialized analysis modes cover different workflows: general understanding, content quality, ad effectiveness, e-commerce conversion, training evaluation, UGC vetting, and competitive intelligence. Videos are deleted immediately after processing — privacy by design.

---

## API Overview

- **Base URL:** https://api.vidcontext.com
- **Endpoint:** POST /v1/analyze
- **Auth:** API key via `X-API-Key` header
- **Interactive Docs:** https://docs.vidcontext.com
- **Content-Type:** multipart/form-data (file upload) or application/json (URL)

### Authentication

Every request requires an API key passed in the `X-API-Key` header. Get your key at https://www.vidcontext.com/app/developer after signing up.

### Rate Limits

- **Free/anonymous:** 3 requests per 60 seconds per IP
- **Authenticated:** 3 requests per 60 seconds per API key

### File Limits

- **Free tier:** 100MB max file size, 60 seconds max duration
- **Paid tier:** 500MB max file size, 15 minutes max duration

### Credit System

- 1 credit = 1 minute of video (rounded up)
- 5 free analyses without an account (no signup required)
- 20 credits on signup
- Credits never expire

---

## Request Format

### File Upload

```
POST /v1/analyze
Content-Type: multipart/form-data

Fields:
  file: <video file>
  output_format: <mode>
```

### URL Input

```
POST /v1/analyze
Content-Type: application/json

{
  "url": "<video URL>",
  "output_format": "<mode>"
}
```

### Response Format

All modes return JSON with a `result` field containing structured markdown text:

```json
{
  "success": true,
  "result": "# Video Analysis\n\n## Scene Breakdown\n...",
  "credits_used": 1,
  "credits_remaining": 19,
  "duration_seconds": 45.2,
  "processing_time_ms": 3200
}
```

Error responses:

```json
{
  "success": false,
  "error": "Description of what went wrong",
  "code": "INSUFFICIENT_CREDITS"
}
```

---

## Analysis Modes — Full Details

### 1. context — General Video Understanding

Extracts everything a language model needs to understand a video: scene-by-scene breakdown, full transcript, on-screen text (OCR), brand/logo detection, audio description, visual composition, and structured metadata.

**Best for:** Giving an LLM full context about any video. RAG pipelines, video search, accessibility, content cataloging.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=context"
```

**Returns:** Scene timestamps, transcript with speaker labels, on-screen text, detected brands/logos, audio elements, visual composition notes, and content metadata.

---

### 2. analysis — Technical Video Quality & Production Scoring

Evaluates video production quality across 7 frameworks: hook effectiveness, pacing and retention, visual quality, audio quality, editing technique, storytelling structure, and overall content score.

**Best for:** Content creators optimizing video quality. Creator tools, video editing assistants, content performance dashboards.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=analysis"
```

**Returns:** Numerical scores (0-100) per framework, detailed breakdown of strengths and weaknesses, specific improvement recommendations with timestamps.

---

### 3. ad — Advertising Effectiveness Scoring

Scores ad creative for media buyers: message clarity, brand presence and recall, persuasion mechanics, emotional triggers, call-to-action effectiveness, platform optimization, and compliance checks.

**Best for:** Ad agencies, media buyers, brand marketers. Pre-flight ad review, A/B test analysis, creative brief compliance.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=ad"
```

**Returns:** Overall ad effectiveness score, per-dimension scores, brand safety assessment, platform-specific recommendations (Meta, TikTok, YouTube), compliance flags, and improvement priorities.

---

### 4. ecommerce — Product Video Conversion Analysis

Analyzes product videos for conversion potential: product visibility and clarity, feature demonstration completeness, purchase psychology triggers, trust signals, and platform-specific optimization weights.

**Best for:** E-commerce brands, product listing optimization, marketplace sellers. Shopify, Amazon, TikTok Shop video evaluation.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=ecommerce"
```

**Returns:** Conversion readiness score, product visibility metrics, feature coverage assessment, purchase trigger analysis, platform-specific scores, and optimization recommendations.

---

### 5. training — Educational Content Effectiveness

Evaluates training and educational videos using learning science frameworks: cognitive load management, knowledge scaffolding, learner engagement, visual aid effectiveness, assessment readiness, and information retention design.

**Best for:** L&D teams, course creators, corporate training, edtech platforms. Evaluate whether training videos actually teach effectively.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=training"
```

**Returns:** Pedagogical effectiveness score, cognitive load assessment, knowledge scaffolding evaluation, engagement metrics, retention design score, and specific improvement recommendations grounded in learning science.

---

### 6. ugc — User-Generated Content & Creator Evaluation

Evaluates UGC and creator content for brand partnerships: production quality, authenticity markers, brand safety, audience alignment, whitelisting potential, and creator professionalism.

**Best for:** Influencer marketing platforms, brand partnership teams, UGC agencies. Vet creator content before deals or whitelisting.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=ugc"
```

**Returns:** Creator quality score, authenticity assessment, brand safety rating, production quality metrics, whitelisting recommendation, and partnership fit analysis.

---

### 7. competitor — Competitive Video Intelligence

Analyzes competitor video content for strategic intelligence: messaging strategy extraction, target audience identification, differentiation gaps, production investment estimation, counter-positioning opportunities, and competitive threat scoring.

**Best for:** Competitive intelligence teams, strategy consultants, brand managers. Understand what competitors are doing in video and how to respond.

```bash
curl -X POST https://api.vidcontext.com/v1/analyze \
  -H "X-API-Key: your-api-key" \
  -F "file=@video.mp4" \
  -F "output_format=competitor"
```

**Returns:** Competitive threat score, messaging strategy breakdown, target audience profile, differentiation analysis, production value estimate, counter-positioning recommendations, and strategic response suggestions.

---

## MCP Server (Model Context Protocol)

VidContext provides an MCP server so AI agents (Claude, Cursor, Windsurf, etc.) can analyze videos directly.

### Installation

```bash
pip install vidcontext-mcp
```

### Configuration (Claude Desktop)

Add to your Claude Desktop MCP config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vidcontext": {
      "command": "vidcontext-mcp",
      "env": {
        "VIDCONTEXT_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Available MCP Tools

- `analyze_video` — Analyze a video file or URL with any of the 7 modes
- `get_credits` — Check remaining credit balance
- `list_modes` — List available analysis modes with descriptions

**PyPI:** https://pypi.org/project/vidcontext-mcp/

---

## Integration Patterns

### Pattern 1: Video RAG (Retrieval-Augmented Generation)

Use `context` mode to convert video libraries into searchable text. Store the structured output in a vector database, then retrieve relevant video context when answering user queries.

### Pattern 2: Automated Ad Review Pipeline

Use `ad` mode in a CI/CD-style pipeline. When new ad creative is uploaded, automatically score it and flag ads below threshold before they go to media spend.

### Pattern 3: E-commerce Listing Optimization

Use `ecommerce` mode to score all product videos in a catalog. Prioritize re-shooting or editing videos with low conversion readiness scores.

### Pattern 4: Competitive Monitoring

Use `competitor` mode on a schedule to analyze competitor video ads and content. Track messaging strategy changes over time and get counter-positioning recommendations.

### Pattern 5: Training Content QA

Use `training` mode to evaluate all training videos in an LMS. Identify content with high cognitive load or poor knowledge scaffolding for revision.

### Pattern 6: Creator Vetting at Scale

Use `ugc` mode to programmatically evaluate creator content before signing partnership deals. Filter by brand safety, production quality, and authenticity scores.

---

## Pricing

### Free Tier
- 5 analyses without an account (no signup required)
- 20 credits on signup (free)
- 100MB file limit, 60-second duration limit

### Credit Packs (one-time, never expire)
- 10 credits — $5
- 50 credits — $20
- 250 credits — $80

### Subscriptions (monthly credits, rollover)
- **Starter** — $15/mo (40 credits) or $144/yr
- **Pro** — $35/mo (100 credits) or $336/yr
- **Business** — $69/mo (250 credits) or $660/yr

1 credit = 1 minute of video, rounded up. A 90-second video costs 2 credits.

---

## Links

- **Website:** https://www.vidcontext.com
- **API Docs:** https://docs.vidcontext.com
- **Developer Dashboard:** https://www.vidcontext.com/app/developer
- **Blog:** https://www.vidcontext.com/blog
- **Comparison Page:** https://www.vidcontext.com/compare
- **Use Cases:** https://www.vidcontext.com/app/use-cases
- **MCP Server (PyPI):** https://pypi.org/project/vidcontext-mcp/
- **Playground:** https://www.vidcontext.com/app/playground

## Contact

- **Support:** support@vidcontext.com
- **Website:** https://www.vidcontext.com