Skip to main content

VirtueGuard-Video Setup Guide

Introduction​

VirtueGuard-Video is our state-of-the-art video safety classifier. It analyzes video at both the frame level (detecting unsafe imagery in any keyframe) and the clip level (detecting unsafe scenes, sequences, and behaviors that only become visible across multiple frames), and returns calibrated per-category probabilities suitable for real-time moderation in uploads, generation pipelines, and content review workflows.

VirtueGuard-Video is part of the VirtueGuard family. It shares its operational model with ImageGuard and AudioGuard so you can compose multimodal moderation with a single API style and key format.

Risk Categories​

VirtueGuard-Video flags the same family of harms as ImageGuard, extended with video-specific categories that require temporal reasoning:

CategoryDescription
Hate_Humiliation_HarassmentFootage promoting hatred, discrimination, bullying, or harassment
Violence_Harm_CrueltyPhysical violence, gore, injury, or acts of cruelty
SexualInappropriate sexual content, nudity, or suggestive material
Criminal_PlanningFootage depicting illegal activities or criminal operations
Weapons_Substance_AbuseWeapons, drug paraphernalia, or substance abuse
Self_HarmFootage depicting or promoting self-injury or suicide
Animal_CrueltyFootage showing harm or abuse to animals
Disasters_EmergenciesNatural disasters, accidents, or emergency situations
PoliticalSensitive political content, propaganda, or extremist messaging
Deepfake_ManipulationSynthetic or face-swapped footage intended to deceive
Scene_Action_RiskUnsafe behaviors visible only over multiple frames (e.g. coordinated attacks, staged self-harm)

Categories can be customized per deployment.

API Integration​

Authentication and Endpoint​

All API requests require an API key included in the request headers.

Endpoint: https://api.virtueai.io/api/videomoderation

Method: POST

Headers:

  • Content-Type: application/json
  • Authorization: Bearer your_api_key_here

Input formats​

VirtueGuard-Video accepts:

  • A URL pointing to the video (mp4, webm, mov).
  • A base64-encoded video payload for short clips.
  • A live stream (HLS, RTMP, WebRTC, or raw frames over WebSocket) for real-time moderation. See Streaming Input below.

For long videos, the service samples keyframes plus short windowed clips; you can override the sampling cadence and window length per request.

API Request Example​

import requests
import base64

url = "https://api.virtueai.io/api/videomoderation"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your_api_key_here",
}

# Option A — pass a URL
payload = {
    "video_url": "https://example.com/clip.mp4",
    "sampling": {
        "fps": 1,            # frames-per-second to sample for frame-level analysis
        "clip_seconds": 4,    # clip window size for temporal analysis
    },
}

# Option B — pass base64-encoded bytes
# with open("clip.mp4", "rb") as f:
#     payload = {"video_b64": base64.b64encode(f.read()).decode()}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

Response​

{
  "flag": true,
  "duration_seconds": 12.4,
  "summary": {
    "categories": {
      "Violence_Harm_Cruelty": true,
      "Sexual": false,
      "Deepfake_Manipulation": false
    },
    "probs": {
      "Violence_Harm_Cruelty": 0.91,
      "Sexual": 0.04,
      "Deepfake_Manipulation": 0.12
    }
  },
  "frames": [
    {
      "timestamp_seconds": 3.0,
      "categories": { "Violence_Harm_Cruelty": true },
      "probs":      { "Violence_Harm_Cruelty": 0.93 }
    }
  ],
  "clips": [
    {
      "start_seconds": 2.0,
      "end_seconds": 6.0,
      "categories": { "Scene_Action_Risk": true },
      "probs":      { "Scene_Action_Risk": 0.78 }
    }
  ],
  "latency_ms": 612
}
FieldDescription
flagtrue if any frame or clip flagged the content.
summary.categories / summary.probsWorst-case aggregated decision and probabilities across the video.
frames[]Per-keyframe decisions at the sampled timestamps.
clips[]Per-window decisions for temporal categories.
latency_msEnd-to-end classification latency.

Streaming Input​

VirtueGuard-Video also accepts live streams and returns moderation events incrementally, so you can block, mute, or interrupt the stream the moment a violation is detected.

Supported transports​

TransportUse Case
HLS / DASHExisting CDN or broadcast pipelines. Point the guard at the manifest URL.
RTMP / RTMPSIngest from OBS, vMix, or other broadcast encoders.
WebRTCBrowser-to-server real-time streams, video calls.
WebSocket (raw frames)Custom pipelines that push H.264 NAL units, MJPEG, or pre-decoded frames.
gRPC bidi streamServer-to-server low-latency integration.

Endpoint​

POST /api/videomoderation/streams to create a session, then push frames / URL to the returned session, or open a wss:// connection to the streaming URL returned by the create call.

curl -X POST "https://api.virtueai.io/api/videomoderation/streams" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "transport": "hls",
    "source_url": "https://stream.example.com/live.m3u8",
    "sampling": { "fps": 2, "clip_seconds": 4 },
    "callback_url": "https://your-app.example.com/policyguard-events"
  }'

Response:

{
  "stream_id": "vs_01HX...",
  "status": "running",
  "websocket_url": "wss://api.virtueai.io/api/videomoderation/streams/vs_01HX.../events"
}

Event stream​

Each moderation decision is emitted as a JSON event over WebSocket (or POSTed to your callback_url):

{
  "stream_id": "vs_01HX...",
  "type": "frame",
  "timestamp_seconds": 12.4,
  "flag": true,
  "categories": { "Violence_Harm_Cruelty": true },
  "probs":      { "Violence_Harm_Cruelty": 0.94 },
  "latency_ms": 78
}

type is one of frame, clip, summary, or error. Frame events fire at your sampled fps; clip events fire at the end of each clip window; a summary event is emitted when you close the stream.

Stop a session with DELETE /api/videomoderation/streams/{stream_id}.

Common Integration Patterns​

  • Upload pipeline — call VirtueGuard-Video on ingest, block or quarantine if flag is true.
  • Generative video moderation — call after generation, before serving the asset to the user.
  • Live broadcast — point the streaming endpoint at your HLS/RTMP source and react to frame / clip events in real time (cut feed, mute, alert).
  • Video calls / WebRTC — moderate participant streams in real time and blur or remove offending video on the spot.
  • Multimodal combo — pair with ImageGuard for thumbnails and AudioGuard for the soundtrack.

For policy-driven decisions (allow/block/review per business rule), wire the output into PolicyGuard and define the decision policy declaratively rather than in code.