# Trial the Wowza VIF Postman Collection

This guide walks you through setting up and using the **Wowza Video Intelligence Framework (VIF)** Postman collection to monitor and control real-time AI video analysis on Wowza Streaming Engine (WSE).

## What it covers

The collection exposes the VIF REST API which is the control plane for object detection, scene analysis, and event-driven intelligence on your live streams. With it you can check system and per-stream health, read and update configuration at three levels (defaults, stream patterns, and single streams), and pull annotated thumbnails.

## Prerequisites

Before you start, make sure you have:

- A running Wowza Streaming Engine with the VIF module installed and the REST API enabled (default port `8087`).
- Your WSE Manager username and password.
- [Postman](https://www.postman.com/downloads/) installed.
- The collection file imported — or the accompanying `vif-openapi-3.1.yaml` spec, if you prefer working from OpenAPI.


## Fork the collection

The VIF collection is published on Postman here:

[postman.com/wowzavideo/wowza-video-intelligence-framework](https://www.postman.com/wowzavideo/wowza-video-intelligence-framework/collection/cnuc0yj/wowza-video-intelligence-framework-vif-postman-collection)

Fork it into your own workspace so your copy stays linked to the published source:

1. Open the collection link above in Postman.
2. Click the **⋯** menu next to the collection name and choose **Create a fork** (or click the fork icon).
3. Give your fork a label.
4. Select the workspace to fork it into.
5. Click **Fork Collection**.


Your forked copy appears in your workspace with all folders and saved example responses.

If you don't have a Postman account or prefer a standalone copy, you can **Import** the `Wowza Video Intelligence Framework (VIF) - Postman Collection.postman_collection.json` file instead. An imported copy works the same way day to day but is not linked to the source, so it won't receive updates.

## Configure variables

Click the collection name, open the **Variables** tab, and set the values for your environment. The collection ships with sensible defaults, so in most cases you only need to fill in your credentials.

| Variable | Purpose | Example |
|  --- | --- | --- |
| `baseURL` | WSE REST API base URL | `http://localhost:8087` |
| `server` | WSE server name | `_defaultServer_` |
| `appName` | Your Wowza application | `live` |
| `streamName` | A specific stream | `myStream` |
| `streamType` | Stream name or regex pattern for saved config | `object.*` |
| `vhost` | Virtual host (qualified paths) | `_defaultVHost_` |
| `instance` | Application instance (qualified paths) | `_definst_` |
| `overlay` | Draw detection overlays on thumbnail | `true` |
| `frameId` | Thumbnail frame id (`0` = latest) | `0` |
| `WSE_userName` | WSE Manager username | `admin` |
| `WSE_password` | WSE Manager password | `your_password` |


## Authentication

Every request uses **HTTP Basic Auth**, inherited from the collection level — you only set `WSE_userName` and `WSE_password` once and all requests pick them up. A built-in pre-request script warns you in the console if `baseURL`, `WSE_userName`, or `WSE_password` is missing, and a collection-level test flags `401` (bad credentials) and `404` (wrong server/app/stream) responses.

## How the collection is organized

The requests are grouped into folders that mirror the API:

- **Status & Health** — check overall system status (versions, CPU, GPU utilization, active streams) and drill into a single stream's performance metrics.
- **Configuration (Defaults)** — read and update the global default settings that apply to any stream without its own override.
- **Stream Management – Active Config** — read or change the *in-memory* config of a running stream: enable/disable VIF, adjust `skip_frames`, swap models, toggle overlays.
- **Stream Management – Saved Config** — read, create, update, or delete the *persisted* per-stream config in `video-intelligence.json`, including a fully-qualified vhost/instance variant.
- **Media** — retrieve a stream thumbnail, optionally with detection overlays and a chosen frame.
- **Server Management** — restart WSE when a change requires it.


## The endpoints at a glance


```
GET    /v1/{server}/plugin/vif/status
GET    /v1/{server}/plugin/vif/config
PUT    /v1/{server}/plugin/vif/config
GET    /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}          (active config)
PUT    /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}
GET    /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config   (saved config)
PUT    /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config
POST   /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config
DELETE /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/config
GET    /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/status
GET    /v1/{server}/plugin/vif/applications/{appName}/streams/{streamName}/thumbnail?overlay=&frameId=
```

A fully-qualified variant lets you name the virtual host and instance explicitly: `/v1/{server}/plugin/vif/vhosts/{vhost}/applications/{appName}/instances/{instance}/streams/{streamName}/config`. When omitted, these default to `_defaultVHost_` and `_definst_`.

## Understand active vs. saved config

This distinction matters. **Active config** (`.../streams/{streamName}`) is what's applied in memory to a running stream right now — changes take effect immediately and are ideal for live tuning. **Saved config** (`.../streams/{streamName}/config`) is what's persisted to disk and reloaded on restart. Use active config to experiment on a live stream, and saved config to make changes stick.

## A typical workflow

Start with **Check System Status** to confirm connectivity and see your GPU and active streams. Read the current configuration with **Get Default Configuration** so you know what you're modifying. Enable analysis on a stream via **Enable / Disable VIF on a Stream**, then fine-tune with **Update Active Stream Settings** (e.g. detection classes, model size, confidence threshold). Monitor the result with **Check Single Stream Status**, and pull a **Get Stream Thumbnail** with `overlay=true` to visually confirm detections. If a change requires it, use **Restart WSE** and wait 15–30 seconds before resuming.

## Common configuration examples

Enable VIF globally: `{ "active": true }`

Process every Nth frame: `{ "skip_frames": 10 }`

Set object detection classes:


```json
{ "object_analysis": { "class_names": ["person", "car", "truck"] } }
```

Switch model and tighten confidence:


```json
{ "object_analysis": { "model_name": "large", "confidence_threshold": 0.5 } }
```

Set scene detection classes:


```json
{ "scene_analysis": { "class_names": ["taking pictures", "running", "fight"] } }
```

Disable the overlay event listener on a stream:


```json
{ "vif_event_listeners": { "Overlays": { "methods": ["disabled"] } } }
```

## Tips and troubleshooting

Each request ships with a saved example response, so you can see the expected payload shape without hitting a live server. If you get a `401`, recheck `WSE_userName` and `WSE_password`; a `404` usually means `server`, `appName`, or `streamName` doesn't match your setup. Remember that some settings apply live while others need a WSE restart — when in doubt, restart and re-check status. Thumbnail responses are binary images and render in Postman's response preview pane; use **Send and Download** to save one to disk.

## Related files

The `vif-openapi-3.1.yaml` OpenAPI 3.1 specification describes the same API with full request/response schemas, and can be imported directly into Postman or used for code generation and validation.

For more information, see [Wowza VIF Documentation](https://www.wowza.com/docs/wowza-video-intelligence-framework).