Documentation

v0.3.0 Beta

Complete guide to IU.dev APIs, MCP server integration, and security features

Getting Started

Beta Notice: IU.dev is currently in beta. APIs and features may change. We're actively developing new video processing capabilities.

Welcome to IU.dev! Simple, powerful APIs with no SDK required. Just make HTTP requests and you're ready to go - it's that easy!

3-Container Architecture

IU.dev runs on a modern microservices architecture with 3 specialized containers:

Main API (8000)
Core API gateway, authentication, file management
MCP Server (3001)
AI integrations via Server-Sent Events
Video Worker (8004)
GPU-accelerated video processing
1

Get your API key

Request beta access to get your API key

2

Set up your environment

Store your API key securely in environment variables

export IU_API_KEY="your_api_key_here"
3

Make your first request

Start processing videos right away

const response = await fetch('https://api.iu.dev/video/process', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    input_url: 'https://example.com/video.mp4',
    output_format: 'mp4'
  })
})

Authentication

All API requests need an API key. During beta, API keys are available by request.

Pro tip: Keep your API key secret! Never put it in client-side code.

Using the X-API-Key Header

Include your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

Example with cURL

curl -X POST https://api.iu.dev/video/process \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input_url": "https://example.com/video.mp4", "output_format": "mp4"}'

Security Features

IU.dev implements multiple security layers to protect your data and ensure secure access to our APIs and services.

API Key Authentication

All API requests are secured with X-API-Key headers. API keys are validated against environment variables and provide secure access to containerized microservices.

  • • Unique API keys per user account
  • • Server-side validation and rate limiting
  • • Environment-based key management

HTTPS Enforcement & Security Headers

All connections are encrypted with TLS 1.2/1.3 and protected by comprehensive security headers including CSP, HSTS, and permissions policies.

  • • Automatic HTTP to HTTPS redirect
  • • Strict-Transport-Security (HSTS) enabled
  • • Content-Security-Policy headers
  • • X-Frame-Options and Permissions-Policy

Request Validation & File Security

Request size limits and file type validation protect against DoS attacks and malicious uploads. Magic byte verification ensures file integrity.

  • • Request body size limits (100MB default)
  • • File type whitelist validation
  • • Magic byte verification for uploads
  • • Protection against path traversal attacks

Enhanced Session Security

Sessions are bound to IP addresses and user agents to prevent hijacking and token theft. Automatic session renewal and cleanup ensure optimal security.

  • • IP binding prevents session hijacking
  • • User agent verification detects token theft
  • • Automatic session renewal (15 min default)
  • • Maximum concurrent sessions per API key

Security Configuration Variables

Configure these environment variables for production deployment:

TRUST_PROXY Enable proxy header trust (set to true if behind nginx/cloudflare)
TRUSTED_PROXIES Comma-separated list of trusted proxy IPs (required if TRUST_PROXY is enabled)
ENFORCE_HTTPS Auto-redirect HTTP to HTTPS (recommended: true for production)
MAX_REQUEST_SIZE Request body size limit in bytes (default: 100MB = 104857600)
SESSION_IP_BINDING Bind sessions to IP addresses (recommended: true)
SESSION_UA_VERIFICATION Verify user agent during session (recommended: true)
MCP_API_KEY Optional API key for MCP server authentication (leave empty to disable)

Security Best Practices

For API Usage:

  • • Keep your API key secret and secure
  • • Never expose API keys in client-side code
  • • Use environment variables for key storage
  • • Regenerate keys if compromised
  • • Enable HTTPS enforcement in production

For Production Deployment:

  • • Set TRUST_PROXY=true if behind reverse proxy
  • • Configure TRUSTED_PROXIES with proxy IPs
  • • Enable SESSION_IP_BINDING and SESSION_UA_VERIFICATION
  • • Use ENFORCE_HTTPS=true for automatic redirects
  • • Set appropriate MAX_REQUEST_SIZE limits

API Endpoints

API Status

Video processing endpoints are being upgraded. TTS and document parsing are currently available.

Video Processing (Coming Soon)

POST /video/process

Convert videos between formats with GPU acceleration

Request Body

input_urlURL of the video to processrequired
output_formatmp4, webm, avi, mov, mkv, flvrequired
resolution1080p, 720p, 480p, 4koptional
webhook_urlURL to receive completion notificationoptional

Example Request

{
  "input_url": "https://example.com/input.avi",
  "output_format": "mp4",
  "resolution": "1080p",
  "webhook_url": "https://yourapp.com/webhook"
}

Document Parsing (Available)

POST /parse

Parse documents (PDF, Word, TXT, MD) and extract text content

Request Body

file_urlURL of the document to parserequired
formatOutput format: text, markdown, jsonoptional

TTS Async Generation (Available)

POST /tts/async

Submit text for async TTS generation with job queue

Request Body

textText to convert to speechrequired
voiceVoice ID or nameoptional
reference_audioURL for voice cloning referenceoptional

Response

{
  "job_id": "tts_abc123xyz",
  "status": "queued",
  "message": "TTS job queued for processing"
}

Metadata & Image Extraction (Available)

POST /api/proxy/extract

Extract metadata and images from videos using AI-powered analysis

Request Body

video_urlURL of the video to analyzerequired
extract_imagesExtract keyframes and thumbnailsoptional
extract_metadataExtract video metadata and AI analysisoptional
ai_analysisInclude AI content analysis (tags, topics, sentiment)optional

Response

{
  "metadata": {
    "duration": 120.5,
    "resolution": "1920x1080",
    "fps": 30,
    "codec": "h264",
    "bitrate": "5000kbps",
    "size_mb": 75.2
  },
  "images": [
    {
      "type": "thumbnail",
      "timestamp": 0,
      "url": "https://cdn.iu.dev/thumb_001.jpg"
    },
    {
      "type": "keyframe",
      "timestamp": 30.5,
      "url": "https://cdn.iu.dev/frame_030.jpg"
    }
  ],
  "ai_analysis": {
    "topics": ["technology", "tutorial", "programming"],
    "tags": ["javascript", "web development", "api"],
    "sentiment": "positive",
    "summary": "A tutorial on building REST APIs with Node.js",
    "key_moments": [
      {"time": "00:02:15", "description": "Introduction to REST principles"},
      {"time": "00:15:30", "description": "Implementing authentication"}
    ]
  }
}

TTS Stream Progress

GET /tts/stream/{job_id}

Server-Sent Events stream for real-time TTS progress updates

Event Stream Format

data: {"type": "progress", "chunk": 1, "total": 5, "text": "Processing chunk 1 of 5"}
data: {"type": "chunk_complete", "chunk": 1, "audio_url": "/audio/chunk_1.wav"}
data: {"type": "complete", "audio_url": "/audio/final.wav", "duration": 45.2}
data: {"type": "error", "message": "TTS processing failed"}

Progressive Playback

Audio chunks can be played progressively as they're generated, providing near-instant playback for long texts without waiting for complete generation.

Video Tools

POST /video/transcribe

Extract transcript from video using Whisper AI

Request Body

video_fileFile ID or upload video filerequired
languageLanguage code (en, es, fr, etc.)optional
POST /video/caption

Add custom captions/subtitles to video

Request Body

video_fileFile ID or upload video filerequired
captionsArray of caption objects with text, start, endrequired
styleCaption style: default, bold, minimaloptional
POST /video/stitch

Combine multiple videos into a single file

Request Body

video_filesArray of file IDs (2-10 videos)required

File Management

GET /files/{directory}

List files in uploads, outputs, or static directories

Parameters

directoryuploads, outputs, or staticrequired
sort_byname, size, or modifiedoptional
limitMax files to return (default: 100)optional
POST /cleanup

Remove temporary files older than specified age

Request Body

max_age_hoursMax age in hours (default: 24)optional
directoriesArray of directories to cleanoptional
dry_runPreview without deletingoptional

MCP Servers

Model Context Protocol (MCP) servers enable AI assistants like Claude Desktop and Claude CLI to directly access IU.dev video processing capabilities. Connect securely via HTTPS with Server-Sent Events (SSE) at https://mcp.iu.dev.

New: SSE-Based MCP Server

We've deployed a dedicated MCP server container running on port 3001, providing seamless integration with Claude Desktop and CLI via Server-Sent Events over HTTPS. This replaces the previous SSH-based approach with a more modern, web-native protocol.

3-Container Architecture

Main API
Port 8000
MCP Server
Port 3001
Video Worker
Port 8004
Claude Desktop / CLI
How it works: The MCP server acts as a bridge between Claude and your video processing infrastructure, translating natural language requests into API calls across the main API and video worker containers.

SSE-Based Setup (Recommended)

Server-Sent Events (SSE) over HTTPS

Connect using standard HTTPS with Server-Sent Events for real-time bidirectional communication. Modern, web-native, and firewall-friendly.

https://mcp.iu.dev
Base URL
/sse
SSE Endpoint
Optional
API Key Auth

Benefits: TLS 1.2/1.3 encryption, works through corporate firewalls, no SSH dependencies, browser-compatible, real-time updates

For Claude Desktop App

Download from claude.ai/download

Add SSE connection to your config file:

  • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "iu-dev": {
      "url": "https://mcp.iu.dev/sse",
      "transport": "sse"
    }
  }
}

No API key required by default! The MCP server is currently open for public testing during beta.

Optional: With API Key Authentication

If the server admin has set MCP_API_KEY, use this config:

{
  "mcpServers": {
    "iu-dev": {
      "url": "https://mcp.iu.dev/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Available MCP Tools

The MCP server provides 5 tools for AI assistants to interact with IU.dev video processing:

process_video

Core Tool

Process videos with various operations including captioning, transcoding, stitching, thumbnails, and custom FFmpeg commands.

Operations:
  • caption - Add subtitles/captions to video
  • transcode - Convert format, resolution, or codec
  • stitch - Combine multiple videos
  • thumbnail - Generate thumbnail image
  • custom - Custom FFmpeg commands

upload_file

Available

Upload video, audio, image, or subtitle files to the server for processing.

get_job_status

Available

Check the status and progress of a video processing job. Returns job state, progress percentage, and result URLs.

list_videos

Available

List all uploaded videos and processed outputs with file information including names, sizes, and modification dates.

health_check

Available

Check the health status of IU.dev API services. Returns service availability and version information.

Example: Using MCP Tools in Claude

User:
"Add captions from captions.srt to my video at https://example.com/video.mp4"
Claude using MCP:
  1. Calls process_video with operation="caption"
  2. Receives job_id from the server
  3. Polls get_job_status until complete
  4. Returns download URL for the captioned video

Examples

Python

import requests

api_key = "YOUR_API_KEY"
headers = {
    "X-API-Key": api_key,
    "Content-Type": "application/json"
}

# Example 1: Process video
video_data = {
    "input_url": "https://example.com/video.avi",
    "output_format": "mp4",
    "resolution": "1080p"
}
response = requests.post("https://api.iu.dev/v1/video/process",
                        json=video_data, headers=headers)
print(response.json())

# Example 2: Extract metadata and images
extract_data = {
    "video_url": "https://example.com/video.mp4",
    "extract_images": True,
    "extract_metadata": True,
    "ai_analysis": True
}
response = requests.post("https://api.iu.dev/api/proxy/extract",
                        json=extract_data, headers=headers)
result = response.json()
print(f"Duration: {result['metadata']['duration']}s")
print(f"Topics: {', '.join(result['ai_analysis']['topics'])}")

JavaScript/Node.js

const apiKey = 'YOUR_API_KEY';

// Example 1: Process video
const processVideo = async () => {
  const response = await fetch('https://api.iu.dev/video/process', {
    method: 'POST',
    headers: {
      'X-API-Key': apiKey,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      input_url: 'https://example.com/video.avi',
      output_format: 'mp4',
      resolution: '1080p'
    })
  });
  const result = await response.json();
  console.log(result);
};

// Example 2: Extract metadata and images
const extractMetadata = async () => {
  const response = await fetch('https://api.iu.dev/api/proxy/extract', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      video_url: 'https://example.com/video.mp4',
      extract_images: true,
      extract_metadata: true,
      ai_analysis: true
    })
  });
  const data = await response.json();
  console.log('Duration:', data.metadata.duration);
  console.log('Topics:', data.ai_analysis.topics);
};

processVideo();
extractMetadata();

Pricing & Billing

During beta, enjoy generous free credits. Full pricing will be available at launch.

How Our Billing Works

  1. 1. Beta users get generous free credits for testing
  2. 2. Wallet system coming soon for production usage
  3. 3. Track your usage in the dashboard
  4. 4. No subscriptions, no surprise charges - you're always in control

Daily Free Credits

5 minutes video processing per day

FREE

1080p Video

Standard quality processing

$0.08/min

4K Video

Ultra HD processing

$0.12/min

Screenshots, Thumbs & Metadata

AI-powered extraction and analysis

$0.009/min

Prepaid Wallet System

Add funds to your wallet anytime (minimum $5). Your balance never expires and you only pay for what you use beyond the daily free tier.

Frequently Asked Questions

What happens if I run out of free credits?

If you exceed your daily free tier, usage will be deducted from your wallet balance at the rates shown above. If your wallet is empty, requests will be declined until the next day's free credits or you add funds.

When do free credits reset?

Free credits reset every day at midnight Pacific Time (PT). You'll get a fresh 5 minutes of video processing to use.

Do wallet funds expire?

No! Your wallet balance never expires. Add funds once and use them whenever you need.

How is metadata extraction priced?

Metadata and image extraction is charged at $0.009 per minute of video analyzed. This includes AI analysis, keyframe extraction, and comprehensive metadata.

Can I get a refund?

Wallet funds are non-refundable, but since you only pay for what you use and there's no subscription, you're never locked in.