Video Processing API Design: RESTful Interfaces and Real-Time Streaming APIs

Video Processing API Design Principles

Video processing APIs differ from ordinary CRUD APIs — they involve complex scenarios such as large file transfers, long-running processing, and state tracking. A well-designed video processing API should follow these principles:

• Async First: Video processing typically takes a long time; use asynchronous patterns to avoid request timeouts
• Idempotency: Re-submitting the same request should not cause side effects; use unique task IDs to ensure idempotency
• Observability: Provide task status queries, progress callbacks, log access, and other capabilities
• Elastic Scaling: Support horizontal scaling, dynamically adjust processing capacity based on task volume
• Error Recovery: Support task retries and resumable transfers to improve system fault tolerance
• Clear Layering: Separate access layer, business layer, and processing layer for easier maintenance and extension

RESTful Interface Specifications

Video processing APIs should follow RESTful design principles, using standard HTTP methods and status codes to provide a clear and consistent interface experience.

Resource Naming

• Task Resource: /api/v1/tasks, video processing tasks
• File Resource: /api/v1/files, uploaded video files
• Template Resource: /api/v1/templates, processing templates/presets
• Job Resource: /api/v1/jobs, specific processing jobs

HTTP Method Usage

• POST: Create tasks, upload files, submit processing requests
• GET: Query task status, get processing results, list tasks
• PUT: Update task configuration (before task starts)
• DELETE: Cancel tasks, delete files

Upload / Process / Callback Flow

A typical video processing workflow includes four stages: file upload, task submission, asynchronous processing, and result callback.

Stage 1: File Upload

For large file uploads, we recommend using multipart upload:

# 1. Initialize upload
POST /api/v1/uploads
{
  "filename": "video.mp4",
  "file_size": 1073741824,
  "content_type": "video/mp4"
}

# Response
{
  "upload_id": "upl_abc123",
  "chunk_size": 5242880,
  "chunks": 205
}

# 2. Upload chunk
PUT /api/v1/uploads/upl_abc123/chunks/1
Content-Range: bytes 0-5242879/1073741824

# 3. Complete upload
POST /api/v1/uploads/upl_abc123/complete
{
  "checksum": "sha256:abc123..."
}

# Response
{
  "file_id": "file_xyz789",
  "filename": "video.mp4",
  "size": 1073741824
}

Stage 2: Submit Processing Task

POST /api/v1/tasks
Content-Type: application/json

{
  "input_file": "file_xyz789",
  "output_format": "mp4",
  "video": {
    "codec": "h264",
    "bitrate": "2000k",
    "resolution": "1920x1080",
    "fps": 30
  },
  "audio": {
    "codec": "aac",
    "bitrate": "128k"
  },
  "callback_url": "https://example.com/webhook",
  "callback_secret": "my-secret-key"
}

# Returns 202 Accepted
{
  "task_id": "task_abc123",
  "status": "queued",
  "created_at": "2026-04-28T12:00:00Z",
  "estimated_time": 180
}

Stage 3: Query Task Status

GET /api/v1/tasks/task_abc123

# Response
{
  "task_id": "task_abc123",
  "status": "processing",
  "progress": 45,
  "current_stage": "encoding",
  "created_at": "2026-04-28T12:00:00Z",
  "started_at": "2026-04-28T12:00:10Z",
  "estimated_completion": "2026-04-28T12:03:10Z",
  "input_file": "file_xyz789",
  "output_file": null,
  "error": null
}

Stage 4: Callback Notification

# Server sends POST request to callback_url
POST https://example.com/webhook
X-Signature: sha256=abc123...

{
  "task_id": "task_abc123",
  "status": "completed",
  "progress": 100,
  "output_file": {
    "file_id": "file_output_123",
    "url": "https://cdn.example.com/output.mp4",
    "size": 250000000,
    "duration": 600.5
  },
  "completed_at": "2026-04-28T12:03:05Z"
}

Real-Time Streaming API Design

Real-time streaming APIs differ significantly from ordinary video processing APIs — they need to handle long connections, real-time data transmission, and dynamic bitrate adjustment.

Live Stream Management API

# Create live stream
POST /api/v1/live/streams
{
  "title": "Product Launch Live Stream",
  "publish_type": "rtmp",
  "resolution": ["1080p", "720p", "480p"],
  "record": true,
  "callback_url": "https://example.com/live/webhook"
}

# Response
{
  "stream_id": "live_abc123",
  "push_url": "rtmp://push.example.com/live/abc123",
  "push_key": "live_abc123?token=xyz789",
  "play_urls": {
    "hls": "https://play.example.com/live/abc123/index.m3u8",
    "flv": "https://play.example.com/live/abc123.flv",
    "webrtc": "webrtc://play.example.com/live/abc123"
  },
  "status": "waiting"
}

# Get live stream status
GET /api/v1/live/streams/live_abc123

# Response
{
  "stream_id": "live_abc123",
  "status": "live",
  "viewer_count": 1250,
  "bitrate": 2500000,
  "resolution": "1920x1080",
  "started_at": "2026-04-28T12:00:00Z",
  "duration": 1800
}

Real-Time Statistics API

For real-time streaming, fine-grained statistical data is required:

• Real-time concurrent viewers, bandwidth usage
• Real-time frame rate, bitrate, resolution data
• QoE metrics such as stalling rate and time to first frame
• Publisher health status monitoring

Authentication and Security

API Authentication Methods

Video processing APIs typically use the following authentication methods:

1. API Key + Signature

Use Access Key + Secret Key for signature verification, suitable for server-side calls:

# Request header example
X-Access-Key: your_access_key
X-Timestamp: 1714305600
X-Signature: HMAC-SHA256:...
X-Nonce: random_string

2. JWT Token

Suitable for frontend calls or short-lived scenarios:

• Obtain token after user login
• Token contains permissions and expiration time
• Stateless verification on server side

3. URL Signature

Used to protect video playback URLs and prevent hotlinking:

https://cdn.example.com/video.mp4?sign=abc123&t=1714305600

# Verification logic
sign = md5(uri + expire_time + secret_key)
if time not expired && sign verification passes:
    return video content
else:
    return 403 Forbidden

Security Best Practices

• All API calls must use HTTPS
• Sensitive operations (delete, batch processing) require secondary verification
• File uploads undergo type validation and virus scanning
• IP whitelist and geographic access control
• Regularly rotate keys and credentials

Error Handling

Unified Error Response Format

# Error response example
{
  "error": {
    "code": "TASK_LIMIT_EXCEEDED",
    "message": "Maximum number of concurrent tasks reached",
    "details": {
      "current_tasks": 5,
      "max_tasks": 5
    },
    "request_id": "req_abc123",
    "retryable": true,
    "retry_after": 60
  }
}

Common Error Code Categories

• 400 Bad Request: Invalid parameters, unsupported file format
• 401 Unauthorized: Authentication failed, token expired
• 403 Forbidden: Insufficient permissions, IP restricted
• 404 Not Found: Task or file does not exist
• 409 Conflict: Task status conflict, duplicate submission
• 429 Too Many Requests: Too many requests
• 500 Internal Server Error: Server-side internal error
• 503 Service Unavailable: Service temporarily unavailable

Rate Limiting Strategies

Video processing services consume significant resources, so reasonable rate limiting strategies must be implemented to protect system stability.

Rate Limiting Dimensions

• API Call Frequency: Limit on requests per minute/hour
• Concurrent Tasks: Limit on simultaneous tasks per user
• File Size Limit: Single file size limit, daily total processing limit
• Bandwidth Limit: Upload/download bandwidth limits
• Storage Quota: Total storage capacity limit

Rate Limiting Algorithms

• Token Bucket: Suitable for burst traffic, smooth processing
• Leaky Bucket: Uniform processing rate, suitable for stable output
• Sliding Window: Precise time window counting
• Distributed Rate Limiting: Cluster-level rate limiting using Redis

API Documentation Recommendations

Documentation Content

• Quick Start Guide: authentication, first API call
• Detailed API docs: parameters, return values, error codes
• Code examples: SDKs or sample code in multiple languages
• Best practices: implementation solutions for common scenarios
• FAQ: frequently asked questions

Documentation Tool Recommendations

• Swagger / OpenAPI: Standard API description format
• Postman: Runnable API collections
• API Blueprint: Markdown-style API documentation
• Interactive Console: Debug APIs directly on the documentation page

Summary

Video processing API design requires full consideration of the unique characteristics of video scenarios: large files, long processing times, high concurrency, and significant resource consumption. Using asynchronous processing patterns, multipart uploads, and callback notifications can provide a good user experience. Meanwhile, a comprehensive authentication system, reasonable rate limiting strategies, and clear error handling are guarantees for stable API operation.

Following RESTful specifications, providing detailed documentation and SDKs, and maintaining backward compatibility of interfaces can greatly reduce developer onboarding costs and improve API usability and competitiveness.

Want to learn more about video technology? Check out our HLS.js Guide, or use our M3U8 Player to experience streaming playback.