Documentation
v0.3.0 BetaComplete 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:
Get your API key
Request beta access to get your API key
Set up your environment
Store your API key securely in environment variables
export IU_API_KEY="your_api_key_here"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_KEYExample 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)
/video/processConvert videos between formats with GPU acceleration
Request Body
| input_url | URL of the video to process | required |
| output_format | mp4, webm, avi, mov, mkv, flv | required |
| resolution | 1080p, 720p, 480p, 4k | optional |
| webhook_url | URL to receive completion notification | optional |
Example Request
{
"input_url": "https://example.com/input.avi",
"output_format": "mp4",
"resolution": "1080p",
"webhook_url": "https://yourapp.com/webhook"
}Document Parsing (Available)
/parseParse documents (PDF, Word, TXT, MD) and extract text content
Request Body
| file_url | URL of the document to parse | required |
| format | Output format: text, markdown, json | optional |
TTS Async Generation (Available)
/tts/asyncSubmit text for async TTS generation with job queue
Request Body
| text | Text to convert to speech | required |
| voice | Voice ID or name | optional |
| reference_audio | URL for voice cloning reference | optional |
Response
{
"job_id": "tts_abc123xyz",
"status": "queued",
"message": "TTS job queued for processing"
}Metadata & Image Extraction (Available)
/api/proxy/extractExtract metadata and images from videos using AI-powered analysis
Request Body
| video_url | URL of the video to analyze | required |
| extract_images | Extract keyframes and thumbnails | optional |
| extract_metadata | Extract video metadata and AI analysis | optional |
| ai_analysis | Include 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
/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
/video/transcribeExtract transcript from video using Whisper AI
Request Body
| video_file | File ID or upload video file | required |
| language | Language code (en, es, fr, etc.) | optional |
/video/captionAdd custom captions/subtitles to video
Request Body
| video_file | File ID or upload video file | required |
| captions | Array of caption objects with text, start, end | required |
| style | Caption style: default, bold, minimal | optional |
/video/stitchCombine multiple videos into a single file
Request Body
| video_files | Array of file IDs (2-10 videos) | required |
File Management
/files/{directory}List files in uploads, outputs, or static directories
Parameters
| directory | uploads, outputs, or static | required |
| sort_by | name, size, or modified | optional |
| limit | Max files to return (default: 100) | optional |
/cleanupRemove temporary files older than specified age
Request Body
| max_age_hours | Max age in hours (default: 24) | optional |
| directories | Array of directories to clean | optional |
| dry_run | Preview without deleting | optional |
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
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.
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 ToolProcess videos with various operations including captioning, transcoding, stitching, thumbnails, and custom FFmpeg commands.
- • 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
AvailableUpload video, audio, image, or subtitle files to the server for processing.
get_job_status
AvailableCheck the status and progress of a video processing job. Returns job state, progress percentage, and result URLs.
list_videos
AvailableList all uploaded videos and processed outputs with file information including names, sizes, and modification dates.
health_check
AvailableCheck the health status of IU.dev API services. Returns service availability and version information.
Example: Using MCP Tools in Claude
- Calls
process_videowith operation="caption" - Receives job_id from the server
- Polls
get_job_statusuntil complete - 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. Beta users get generous free credits for testing
- 2. Wallet system coming soon for production usage
- 3. Track your usage in the dashboard
- 4. No subscriptions, no surprise charges - you're always in control
Daily Free Credits
5 minutes video processing per day
1080p Video
Standard quality processing
4K Video
Ultra HD processing
Screenshots, Thumbs & Metadata
AI-powered extraction and analysis
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.