Skip to content
Wowza Video Intelligence...
/
/
/
Get single stream status

Wowza Video Intelligence Framework (VIF) REST API

The Video Intelligence Framework (VIF) adds real-time, AI-powered object detection, scene analysis, and event-driven intelligence to live video streams running on Wowza Streaming Engine (WSE).

This REST API lets you inspect system and per-stream status, read and update the default configuration, manage the active (in-memory) and saved (on-disk) configuration of individual streams, and retrieve annotated thumbnails.

VIF WSE plugin reference

Configuration hierarchy

Settings cascade through three levels of increasing specificity: Defaults (/v1/{server}/plugin/vif/config) → Stream pattern → Single stream. A more specific setting overrides a less specific one.

Active vs. saved configuration

  • Active config (/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}) is the configuration currently applied in memory to a running stream. Supports GET and PUT.

  • Saved config (/v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config) is the persisted configuration in video-intelligence.json. Supports GET, PUT, POST, and DELETE.

Authentication

All requests use HTTP Basic authentication with Wowza Streaming Engine Manager credentials.

Download OpenAPI description
vif-openapi-3.1.json
vif-openapi-3.1.yaml
Overview
URL
https://www.wowza.com/docs
License
Wowza
Languages
Servers
Local Wowza Streaming Engine REST API
http://localhost:8087
Custom Wowza Streaming Engine host
http://{host}:{port}

Status & Health

Monitor VIF system and per-stream health and performance.

Operations

Get system status

Request

Returns a full snapshot of the VIF system: host information (WSE/VIF versions, CPU, NVIDIA GPU type and utilization) and an array of every stream currently registered with the VI service.

Security
basicAuth
Path
serverstringrequired

WSE server name. Any value is accepted; commonly _defaultServer_.

Default "_defaultServer_"
curl -i -X GET \
  -u <username>:<password> \
  http://localhost:8087/v1/http://localhost:8087/plugin/vif/status

Responses

System status returned successfully.

Bodyapplication/json
hostobject(HostInfo)required

Host-level information and hardware utilization.

host.​wse_versionstring
host.​vif_module_versionstring
host.​cpu_avgnumber

Average CPU utilization (%).

host.​nvidia_gpu_typestring
host.​nvidia_driver_versionstring
host.​cuda_versionstring
host.​gpu_avgobject(Measurement)

A measured value with its unit.

host.​gpu_memory_avgobject(Measurement)

A measured value with its unit.

host.​gpu_encode_avgobject(Measurement)

A measured value with its unit.

host.​gpu_decode_avgobject(Measurement)

A measured value with its unit.

streamsArray of objects(StreamStatus)required
streams[].​api_versionstring
streams[].​wse_versionstring
streams[].​vif_module_versionstring
streams[].​vi_service_urlstring(uri)
streams[].​vi_service_versionstring
streams[].​vhost_namestring
streams[].​app_namestring
streams[].​instance_namestring
streams[].​stream_namestring
streams[].​activeboolean
streams[].​model_namestring
streams[].​widthinteger
streams[].​heightinteger
streams[].​frame_ratenumber
streams[].​skip_framesinteger
streams[].​durationinteger
streams[].​resize_outputboolean
streams[].​grayscaledboolean
streams[].​detector_typestring
Enum"object""scene"
streams[].​statusstring
streams[].​reasonstring

Diagnostic detail when status is not running.

streams[].​vif_event_listenersobject(EventListenerStatus)

Configured event listeners grouped by built-in type.

streams[].​performanceobject(Performance)

Per-stream processing performance metrics (all times in milliseconds).

Response
application/json
{
  "host": {
    "wse_version": "4.9.1",
    "vif_module_version": "1.2.0",
    "cpu_avg": 23.5,
    "nvidia_gpu_type": "NVIDIA A10",
    "nvidia_driver_version": "535.129.03",
    "cuda_version": "12.2",
    "gpu_avg": { … },
    "gpu_memory_avg": { … },
    "gpu_encode_avg": { … },
    "gpu_decode_avg": { … }
  },
  "streams": [
    { … }
  ]
}

Get single stream status

Request

Returns detailed status and performance metrics for a specific stream. The stream must be registered with the VI service. If status is anything other than running, inspect the reason field for diagnostic information.

Security
basicAuth
Path
serverstringrequired

WSE server name. Any value is accepted; commonly _defaultServer_.

Default "_defaultServer_"
appNamestringrequired

Name of the Wowza application the stream is running on (e.g. live).

streamNamestringrequired

Stream name or a stream pattern (regex) used to match streams, e.g. objects.*.

curl -i -X GET \
  -u <username>:<password> \
  'http://localhost:8087/v1/http://localhost:8087/plugin/vif/applications/{appName}/streams/{streamName}/status'

Responses

Stream status returned successfully.

Bodyapplication/json
api_versionstring
wse_versionstring
vif_module_versionstring
vi_service_urlstring(uri)
vi_service_versionstring
vhost_namestring
app_namestring
instance_namestring
stream_namestring
activeboolean
model_namestring
widthinteger
heightinteger
frame_ratenumber
skip_framesinteger
durationinteger
resize_outputboolean
grayscaledboolean
detector_typestring
Enum"object""scene"
statusstring
reasonstring

Diagnostic detail when status is not running.

vif_event_listenersobject(EventListenerStatus)

Configured event listeners grouped by built-in type.

performanceobject(Performance)

Per-stream processing performance metrics (all times in milliseconds).

Response
application/json
{
  "wse_version": "4.9.1",
  "vif_module_version": "1.2.0",
  "api_version": "v1",
  "vi_service_url": "http://vi-service:8089",
  "vi_service_version": "1.2.0",
  "instance_name": "_definst_",
  "stream_name": "security_cam_01",
  "active": true,
  "model_name": "large",
  "width": 1920,
  "height": 1080,
  "frame_rate": 30,
  "skip_frames": 5,
  "duration": 0,
  "resize_output": false,
  "grayscaled": false,
  "detector_type": "object",
  "status": "running",
  "reason": "",
  "vif_event_listeners": {
    "Id3Tags": [],
    "Webhooks": [ … ],
    "LogFiles": [ … ],
    "Overlays": []
  },
  "performance": {
    "ping_rtt_avg": 1.2,
    "ping_pong_rtt_avg": 2.4,
    "preprocess_time_avg": 3.1,
    "inference_time_avg": 12.3,
    "postprocess_time_avg": 2.8,
    "total_processing_time_avg": 18.7,
    "frame_detect_time_avg": 19.2,
    "video_frames_ttl": 54000,
    "object_frames_detected": 12340
  }
}

Configuration

Read and update the default VIF configuration.

Operations

Stream Management

Manage the active and saved configuration of individual streams.

Operations

Media

Retrieve annotated media such as thumbnails.

Operations