Skip to main content

​
Overview

The VoD (Video on Demand) API allows you to upload, import, list, and delete video files. All VoD endpoints are prefixed with /v2/vods.

​
Get VoD File

Retrieve a VoD file record from the database.
GET /v2/vods/{id}
curl -X GET "https://example.com:5443/LiveApp/rest/v2/vods/vod123" \
  -H "Authorization: Bearer {jwt}"
​
id
string
required
VoD file ID
​
vodId
string
Unique VoD identifier
​
vodName
string
Display name of the VoD file
​
streamId
string
Associated stream ID (for recorded streams)
​
filePath
string
Relative path to the file
​
duration
integer
Duration in milliseconds
​
fileSize
integer
File size in bytes
​
creationDate
integer
Creation timestamp
​
type
string
VoD type: userVod, streamVod

​
List VoD Files

Get paginated list of VoD files with optional filtering and sorting.
GET /v2/vods/list/{offset}/{size}
curl -X GET "https://example.com:5443/LiveApp/rest/v2/vods/list/0/10?sort_by=date&order_by=desc&search=recording" \
  -H "Authorization: Bearer {jwt}"
​
offset
integer
required
Pagination offset (starting point)
​
size
integer
required
Number of items to fetch (max: 50)
​
sort_by
string
Sort field: name or date
​
order_by
string
Sort order: asc (ascending) or desc (descending)
​
streamId
string
Filter by associated stream ID
​
search
string
Search string to filter VoD files
Response: Array of VoD objects.

​
Get VoD Count

Get total number of VoD files.
GET /v2/vods/count
curl -X GET "https://example.com:5443/LiveApp/rest/v2/vods/count" \
  -H "Authorization: Bearer {jwt}"
​
number
integer
Total number of VoD files in database

​
Get VoD Count (Filtered)

Get number of VoD files matching search criteria.
GET /v2/vods/count/{search}
curl -X GET "https://example.com:5443/LiveApp/rest/v2/vods/count/recording" \
  -H "Authorization: Bearer {jwt}"
​
search
string
required
Search string to filter VoD files
​
number
integer
Number of VoD files matching search criteria

​
Upload VoD File

Upload an external VoD file to Ant Media Server.
POST /v2/vods/create
curl -X POST "https://example.com:5443/LiveApp/rest/v2/vods/create?name=MyVideo" \
  -H "Authorization: Bearer {jwt}" \
  -F "file=@/path/to/video.mp4" \
  -F "metadata={\"title\":\"My Video\",\"description\":\"Sample video\"}"
​
name
string
required
Display name for the VoD file
Supported formats: mp4, webm, mov, avi, mp3, wmv
​
success
boolean
Whether upload was successful
​
dataId
string
Generated VoD ID
​
message
string
Error message or VoD ID
If vodUploadFinishScript is configured in AppSettings, the uploaded file will be queued for processing. The VoD status will be:
  • inqueue - Waiting for processing
  • processing - Currently being processed
  • finished - Processing completed successfully
  • failed - Processing failed

​
Delete VoD File

Delete a specific VoD file from database and storage.
DELETE /v2/vods/{id}
curl -X DELETE "https://example.com:5443/LiveApp/rest/v2/vods/vod123" \
  -H "Authorization: Bearer {jwt}"
​
id
string
required
VoD ID to delete
​
success
boolean
Whether deletion was successful
​
message
string
Result message
This operation:
  • Deletes the video file from disk
  • Deletes the preview/thumbnail if exists
  • Removes the record from database
  • Deletes files from S3 if cloud storage is configured

​
Delete Multiple VoD Files

Delete multiple VoD files in bulk.
DELETE
curl -X DELETE "https://example.com:5443/LiveApp/rest/v2/vods/?ids=vod1,vod2,vod3" \
  -H "Authorization: Bearer {jwt}"
​
ids
string
required
Comma-separated VoD IDs to delete
​
success
boolean
Whether all deletions were successful
​
message
string
Result message (includes failed ID if operation stopped)

​
Import VoD Files from Directory

Import VoD files from a directory and make them streamable.
POST /v2/vods/directory
curl -X POST "https://example.com:5443/LiveApp/rest/v2/vods/directory?directory=/var/videos" \
  -H "Authorization: Bearer {jwt}"
​
directory
string
required
Full path of the directory containing VoD files to import
​
success
boolean
Whether import was successful
​
message
string
Result message
This operation:
  • Scans the specified directory for video files
  • Creates database records for each file
  • Creates symbolic links to make files accessible via HTTP
  • Does NOT copy or move the original files
Delete database records for VoD files without deleting the actual files.
DELETE /v2/vods/directory
curl -X DELETE "https://example.com:5443/LiveApp/rest/v2/vods/directory?directory=/var/videos" \
  -H "Authorization: Bearer {jwt}"
​
directory
string
required
Full path of the directory to unlink VoD files from
​
success
boolean
Whether unlink was successful
​
message
string
Result message
This operation:
  • Removes database records for VoD files in the directory
  • Removes symbolic links
  • Does NOT delete the actual video files

​
Import VoDs to Stalker Portal

Import VoD files to Stalker middleware portal.
POST /v2/vods/import-to-stalker
curl -X POST "https://example.com:5443/LiveApp/rest/v2/vods/import-to-stalker" \
  -H "Authorization: Bearer {jwt}"
​
success
boolean
Whether import was successful
​
message
string
Error message if failed
​
errorId
integer
Error code:
  • 404 - Stalker DB info missing
  • 500 - No VoD folder specified
Requires Stalker portal database configuration in AppSettings:
  • stalkerDBServer
  • stalkerDBUsername
  • stalkerDBPassword
  • vodFolder

​
VoD Upload Processing

When a VoD file is uploaded, you can configure a post-processing script via the vodUploadFinishScript setting in AppSettings.

​
Process Status Values

  • null - No processing configured
  • inqueue - Queued for processing
  • processing - Currently being processed
  • finished - Processing completed successfully
  • failed - Processing failed

​
Example Processing Script

#!/bin/bash
# Script receives the uploaded file path as argument
INPUT_FILE=$1

# Example: Convert to different format, generate thumbnails, etc.
ffmpeg -i "$INPUT_FILE" -vf scale=640:360 "${INPUT_FILE%.*}_360p.mp4"

# Return 0 for success, non-zero for failure
exit $?
Configure in AppSettings: 
vodUploadFinishScript=/path/to/process-vod.sh

​
VoD File Streaming

Once imported or uploaded, VoD files can be streamed via: HLS: 
https://{host}:{port}/{app}/streams/{vodFilePath}
Direct file access: 
https://{host}:{port}/{app}/streams/{relativePath}
The filePath in the VoD object contains the relative path needed for streaming.

Build docs developers (and LLMs) love

Get started for freeTalk to us