API Reference

Base URL: https://api.hypervideo.dev

Full OpenAPI spec available at api.hypervideo.dev/docs (Swagger UI) and /docs.json.

Video Background Removal (Sync)

POST /api/v1/video/remove-background

Processes the video synchronously and returns base64-encoded output directly. Best for shorter videos (<15s). For longer videos, use the async jobs endpoint.

Request

Send as multipart/form-data:

Response

{
  "success": true,
  "data": {
    "url": "data:video/webm;base64,...",
    "format": "webm",
    "width": 768,
    "height": 768,
    "duration": 5.875,
    "frameCount": 141,
    "fps": 24,
    "size": 1597805,
    "processingTime": 12500,
    "processingMethod": "chromakey",
    "detectedBackgroundColor": { "r": 233, "g": 47, "b": 188, "hex": "#E92FBC" },
    "outputs": [
      { "format": "webm", "url": "data:video/webm;base64,...", "size": 1597805 },
      { "format": "stacked-alpha", "url": "data:video/mp4;base64,...", "size": 5242880 }
    ]
  }
}

Example

curl -X POST https://api.hypervideo.dev/api/v1/video/remove-background \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@video.mp4" \
  -F "format=webp" \
  -F "quality=40"

Video Background Removal (Async)

POST /api/v1/jobs/video/remove-background

Submits a job for background removal. Returns immediately with a job ID. See the Async Jobs guide for details.

Get Job Status

GET /api/v1/jobs/:jobId

Polls the status of an async job. Returns progress, stage, and final results when complete.

Extract Frames

POST /api/v1/video/extract-frames

Downloads a video from a URL, extracts frames server-side using ffmpeg, and returns them as base64 data URLs. Useful when the caller doesn't have ffmpeg available locally (e.g., serverless functions, cloud actions).No authentication required.

Request

Send as application/json:

Response

{
  "success": true,
  "data": {
    "frames": [
      { "index": 0, "dataUrl": "data:image/png;base64,..." },
      { "index": 1, "dataUrl": "data:image/png;base64,..." }
    ],
    "frameCount": 90,
    "width": 480,
    "height": 480,
    "processingTimeMs": 3200
  }
}

Example

curl -X POST https://api.hypervideo.dev/api/v1/video/extract-frames \
  -H "Content-Type: application/json" \
  -d '{"videoUrl": "https://example.com/video.mp4", "maxFrames": 90, "format": "png"}'

Image Background Removal

POST /api/v1/image/remove-background

Detect Background Color

POST /api/v1/image/detect-background-color

Returns the dominant edge color of an image.

{
  "success": true,
  "data": { "r": 233, "g": 47, "b": 188, "hex": "#E92FBC" }
}

Smart Processing

The API automatically selects the best processing method based on output format:

Manual chromaKey applies to chromakey formats but does not switch AI formats away from AI processing.