Video Detection API

Endpoint overview

Synchronous video detection

Submit one video as the multipart field file.

curl -X POST   -H "X-API-Key: $ORIVFY_API_KEY"   -F "file=@sample.mp4"   https://mlvideo.orivfy.com/v4/detect-video

Python

import requests

with open("sample.mp4", "rb") as video:
    response = requests.post(
        "https://mlvideo.orivfy.com/v4/detect-video",
        headers={"X-API-Key": api_key},
        files={"file": ("sample.mp4", video, "video/mp4")},
        timeout=360,
    )
response.raise_for_status()
result = response.json()

Asynchronous jobs

POST /v4/detect-video-async
GET  /v4/jobs/{job_id}

Job status: queued → processing → done | error

Send X-API-Key on both the upload request and every polling request.

Forensic explanation WebSocket

Browser clients first ask their trusted application backend to create a one-time ticket.

POST /v4/ws-ticket
X-API-Key: YOUR_ORIVFY_API_KEY

{
  "ticket": "...",
  "expires_in": 120,
  "expires_at": "..."
}

const socket = new WebSocket(
  `wss://mlvideo.orivfy.com/v4/ws/explain-video?ticket=${encodeURIComponent(ticket)}`
);

socket.onopen = () => socket.send(JSON.stringify(detectionResult));
socket.onmessage = event => {
  const message = JSON.parse(event.data);
  // message.type: start | chunk | complete | error
};

Representative detection response

{
  "prediction": "AI-generated",
  "confidence": 0.93,
  "success": true,
  "source": "unknown AI",
  "detection_stage": "Stage 3",
  "video_duration": 8.4,
  "frame_count": 252,
  "successful_frames": 16,
  "ai_ratio": 0.875,
  "real_ratio": 0.125,
  "base64_frames": ["..."],
  "pipeline_results": { }
}

The exact response includes legacy-compatible fields used by existing Orivfy clients. Decode failures return a structured JSON result with prediction: "Error" and success: false.

Limits and status codes