Videos

Operations related to uploading and categorizing videos.

Create a video

This operation creates a video object in Wowza Video. You can upload a video from your local storage (DIRECT) or from an external storage provider (FETCH).

Request

Request Body schema: application/json

object (video)

	DirectInputRequest (object) or FetchInputRequest (object) (InputVideoRequest) Specifies the input method for uploading the video. There are two methods to choose from: `DIRECT` or `FETCH`. Expand the `input` description, by clicking the > next to the `input` label, then click each tab to learn about the methods. Learn more: Upload a video from local storage Upload a video from external storage
name	string The video name. Can be displayed in the player. If not specified, it will default to the input file's name.
description	string The video description. Can be displayed in the player.
unpublish	boolean Default: true If `true`, the `unpublished_at` is respected and the video will not be available after `unpublished_at`. If `false`, the video will not be unpublished.
unpublished_at	string <date-time> Date and time, in ISO-8601, format when video no longer is available for publishing. After this date, the video is not visible in the player if using `ovp-plugin` to request the video.
published	boolean Determines, together with `published_at` and `unpublished_at`, if this video will be visible in public listings such as MRSS-feeds, endscreens and playlists. If `true`, and if `published_at` and `unpublished_at` allows, the video will be visible.
published_at	string <date-time> Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using `ovp-plugin` to request the video.
tags	Array of strings An array of tags.
category_id	string Default: "<The account's default category>" The unique identifier for the category that the video belongs to.
	Array of objects A list of ad insertion points specified for a video. Ad insertion points are pre-defined locations in a video where advertisements are placed during playback. Ads can be inserted at pre-roll (at the beginning of the video), mid-roll (during the video), or post-roll (at the end of the video) position(s). Note: Ad insertion points are only applicable for client-side ad insertion. If you create mid-roll ad insertion points for a video, for example, they overwrite any mid-roll ad positions created using the Video Ad Serving Template ad schedule form. This is because the ad insertion points created using the Wowza Video 2.0 API are time-specific and more accurate than the percentages chosen in the Video Ad Serving Template ad schedule page.
no_ads	boolean When set to `true`, no ads will be displayed during this video. Note: This feature only works for Iframe embeds.
ad_keywords	string Used for replacing the `ad_keywords` macro in the VAST-tag in any player that plays the video.

Responses

200

Success

Response Schema: application/json

object (video)

id

string

The unique identifier for the video.

name

string

The video name. Can be displayed in the player. If not specified, it will default to the input file's name.

description

string

The video description. Can be displayed in the player.

duration_in_ms

integer <int64>

Duration of the video in milliseconds.

unpublish

boolean

Default: true

If true, the unpublish_date is respected and the video will not be available after unpublish_date. If false, the video will not be unpublished.

unpublished_at

string <date-time>

Date and time, in ISO-8601 format, when video no longer is available for publishing. After this date, the video is not visible in the player if using ovp-plugin to request the video.

published

boolean

This field, together with publish_date and unpublish_date, determines if this video will be visible in public listings such as MRSS-feeds, endscreens and playlists. If true, and publish_date and unpublish_date allows, the video will be visible.

published_at

string <date-time>

Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using ovp-plugin to request the video.

tags

Array of strings

An array of tags.

category_id

string

Default: "<The account's default category>"

The unique identifier for the category that the video belongs to.

Array of objects

A list of ad insertion points specified for a video. Ad insertion points are pre-defined locations in a video where advertisements are placed during playback. Ads can be inserted at pre-roll (at the beginning of the video), mid-roll (during the video), or post-roll (at the end of the video) position(s).

Note: Ad insertion points are only applicable for client-side ad insertion. If you create mid-roll ad insertion points for a video, for example, they overwrite any mid-roll ad positions created using the Video Ad Serving Template ad schedule form. This is because the ad insertion points created using the Wowza Video 2.0 API are time-specific and more accurate than the percentages chosen in the Video Ad Serving Template ad schedule page.

no_ads

boolean

When set to true, no ads will be displayed during this video. Note: This feature only works for Iframe embeds.

ad_keywords

string

Used for replacing the ad_keywords macro in the VAST-tag in any player that plays the video.

created_at

string <date-time>

Date and time, in ISO-8601 format, when video was created.

updated_at

string <date-time>

Date and time, in ISO-8601 format, when video was updated.

state

string

The current state of the video. The state reflects the current status of the video files for the video asset. Possible states listed below:

State	Description
UPLOADING	The source file is currently being uploaded or waiting to be downloaded by our API.
WAITING_FOR_ENCODER	The source file was successfully downloaded by the platform and is in queue to be encoded.
PROCESSING	Source file for the asset is encoding. The current encoding progress can be found on `encoding_progress` property.
FINISHED	The encoding is done and the encoded files can be fetched. In this state it's possible to embed the video.
ERROR	If the platform, for some reason, could not download the source file or failed during the encoding process. `error_messsage` property can give more information about why it errored.
DELETED	The video files have been deleted. Usually the Video asset have been deleted when this state is reached and because of that it's very uncommon to see assets with this state.

encoding_progress

number <double>

Progress of video encoding, in percentage. The max value, 100, is reached when all video files have been encoded.

upload_progress

number <double>

Progress of source file upload, in percentage. If the value is 100, the source file is uploaded.

error_message

string

If the platform failed to encode the source file, a message describing the error reason will be presented in this property.

deactivated

boolean

Default: false

If true, this video has been deactivated and is no longer available for embedding. This usually happens if the account was cancelled or trial limits were exceeded.

Array of objects (ImageModel)

Images used together with the video in the platform and the player.

For platform video images specified in create and update requests, these are uploaded and delivered through the platform. For remote assets, the specified image URLs are passed along to the player using the URL specified in the request.

Array of objects (EncodingModel)

Array containing all available video files and their metadata.

object (DRMConfigModel)

Contains all DRM configurations for one video.

shallow_copy

boolean

Whether this video is a shallow copy of another video. A shallow copy uses video files controlled by another video, usually on another workspace.

Videos that are shallow copies can't use all features available for normal videos. For example, it's not possible to upload a new version of the video.

Another difference is that deleting the video will not delete any video files. If the video asset that is the source of the copy is deleted, the files will no longer be available for this asset.

shallow_copy_source_id

string

If the video is a shallow copy, this field contains the ID of the source video entity.

Note: There are cases where it is not possible to identify the source and in those cases this value will be null.

multiple_audio_tracks

boolean

If true, this video has several different audio tracks available for the player. For example, there may be audio tracks in different languages.

audio_only

boolean

If true, this video has no video track but only audio tracks.

version

integer <int32>

Tracks the number of times a new source file was uploaded for this video asset. For each time a new source file is uploaded, the value increases by one.

object (ThumbnailResponse)

Link to the VTT file used by the Thumbnails plug-in. See Thumbnails to learn more.

Array of objects (AnimatedPreviewModel)

The animated previews for the video.

upload_url

string

If input method DIRECT was select, this field contains the signed URL that will be used to upload the file.

401

Unauthorized

422

Unprocessable Entity

post/videos

Request samples

Payload
Shell
JavaScript
Java
Python

application/json

{"video": {"input": {"method": "DIRECT"
},
"name": "My video",
"description": "A new video for my business.",
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"ad_insertion_points": [{"offset_from_start_in_ms": 20000,
"description": "mid-roll"
}
],
"no_ads": true,
"ad_keywords": "special_ads"
}
}

Response samples

200
401
422

application/json

{"video": {"id": "2aa3343e-2fb5-42c3-8671-b52c24b7c3e2",
"name": "My video",
"description": "A new video for my business.",
"duration_in_ms": 0,
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"ad_insertion_points": [{"offset_from_start_in_ms": 20000,
"description": "mid-roll"
}
],
"no_ads": true,
"ad_keywords": "special_ads",
"created_at": "2025-01-01T12:33:22Z",
"updated_at": "2024-01-01T12:33:22Z",
"state": "FINISHED",
"encoding_progress": 0,
"upload_progress": 0,
"error_message": "string",
"deactivated": false,
"images": [{"type": "thumbnail",
"url": "https://example.com/image.jpg"
}
],
"encodings": [{"audio_bitrate_in_kbps": 2300,
"audio_channel": 2,
"audio_codec": "aac",
"audio_sample_rate": 44100,
"height": 1080,
"width": 1920,
"video_file_url": "https://flowplayer.com/video.mp4",
"video_container": "mp4",
"video_codec": "h264",
"total_bitrate_in_kbps": 1023,
"created_at": "2019-08-24T14:15:22Z",
"size_in_bytes": 8325555
}
],
"drm": {"com.widevine.alpha": {"license_server": "string",
"certificate": "string"
},
"com.apple.fps.1_0": {"license_server": "string",
"certificate": "string"
},
"com.microsoft.playready": {"license_server": "string",
"certificate": "string"
}
},
"shallow_copy": true,
"shallow_copy_source_id": "string",
"multiple_audio_tracks": true,
"audio_only": true,
"version": 0,
"thumbnails": {"src": "string"
},
"animated_previews": [{"url": "string",
"type": "string",
"height": 1080,
"width": 1920
}
],
"upload_url": "string"
}
}

Fetch all videos

This operation shows details for all videos available in Wowza Video.

Request

query Parameters

page

integer <int32>

Default: 1

Returns a paginated view of results from the HTTP request. Specify a positive integer to indicate which page of the results should be displayed. The default is 1.

per_page

integer <int32>

Default: 20

For use with the page parameter. Indicates how many records should be included in a page of results. A valid value is any positive integer. The default and maximum value is 1000.

created_at

string

Filter the response based on an asset's timespan. The filter can be specified in following formats:

Spec	Description
`YYYY-MM-DD'T'HH:mm:ss`	Returns all assets with created_at after the specified date

Example: created_at=2024-01-01T00:00:00+0000,2024-02-01T00:00:00+0000

updated_at

string

Filter the response based on an asset's timespan. The filter can be specified in following formats:

Spec	Description
`YYYY-MM-DD'T'HH:mm:ss`	Returns all assets with updated_at after the specified date

Example: updated_at=2024-01-01T00:00:00+0000,2024-02-01T00:00:00+0000

published_at

string

Filter the response based on an asset's timespan. The filter can be specified in following formats:

Spec	Description
`YYYY-MM-DD'T'HH:mm:ss`	Returns all assets with published_at after the specified date

Example: published_at=2024-01-01T00:00:00+0000,2024-02-01T00:00:00+0000

state

string

The current state of the video. The state reflects the current status of the video files for the video asset. Possible states listed below:

State	Description
UPLOADING	The source file is currently being uploaded or waiting to be downloaded by our API.
WAITING_FOR_ENCODER	The source file was successfully downloaded by the platform and is in queue to be encoded.
PROCESSING	Source file for the asset is encoding. The current encoding progress can be found on `encoding_progress` property.
FINISHED	The encoding is done and the encoded files can be fetched. In this state it's possible to embed the video.
ERROR	If the platform, for some reason, could not download the source file or failed during the encoding process. `error_messsage` property can give more information about why it errored.
DELETED	The video files have been deleted. Usually the video asset have been deleted when this state is reached and because of that it's very uncommon to see assets with this state.

Example: state=FINISHED

query

string

Search multiple text fields in a search that is case insensitive and does not require full matches. URL encode the value of the query to ensure that it can be processed. There are free URL encoders online.

It searches name, description, tags searches all your custom fields for matching terms. You can search specific fields by specifying them after a colon (:); if you have multiple search terms you can use pipe (|) to separate the search terms.

Some examples:

Query	Description
`query=foo`	Searches all fields for `foo`.

Example: query=foo:name,custom_fields

sort_column

string

Enum: "created_at" "name" "published_at" "duration"

sort_direction

string

Enum: "desc" "asc"

origin_id

string

The unique alphanumeric string that identifies the live stream or the real-time stream from which the video originated.

Returns all the videos associated with the same ID.

Example: origin_id=edfg8k34

Response Schema: application/json

	Array of objects (VideoListModel) The list of videos
	object (Pagination)

401

Unauthorized

get/videos

Request samples

Response samples

200
401

application/json

{"videos": [{"id": "2aa3343e-2fb5-42c3-8671-b52c24b7c3e2",
"name": "My video",
"description": "A new video for my business.",
"duration_in_ms": 0,
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"no_ads": true,
"ad_keywords": "special_ads",
"created_at": "2024-01-01T12:33:22Z",
"updated_at": "2024-01-01T12:33:22Z",
"state": "FINISHED"
}
],
"pagination": {"payload_version": 0,
"total_records": 100,
"page": 1,
"per_page": 10,
"total_pages": 2,
"page_first_index": 10,
"page_last_index": 10
}
}

Fetch a video

This operation shows details for a single, specified video.

Request

path Parameters

id

required

string

Unique identifier for the video.

Example: 51cd5c07-1583-4f5e-bd81-f1aa11510ea9

Responses

200

Success

Response Schema: application/json

object (video)

id

string

The unique identifier for the video.

name

string

The video name. Can be displayed in the player. If not specified, it will default to the input file's name.

description

string

The video description. Can be displayed in the player.

duration_in_ms

integer <int64>

Duration of the video in milliseconds.

unpublish

boolean

Default: true

If true, the unpublish_date is respected and the video will not be available after unpublish_date. If false, the video will not be unpublished.

unpublished_at

string <date-time>

Date and time, in ISO-8601 format, when video no longer is available for publishing. After this date the video is not visible in the player if using ovp-plugin to request the video.

published

boolean

This field, together with publish_date and unpublish_date, determines if this video will be visible in public listings such as MRSS-feeds, endscreens, and playlists. If true and publish_date and unpublish_date allows, the video will be visible.

published_at

string <date-time>

Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using ovp-plugin to request the video.

tags

Array of strings

An array of tags.

category_id

string

Default: "<The account's default category>"

The unique identifier for the category that the video belongs to.

Array of objects

A list of ad insertion points specified for a video. Ad insertion points are pre-defined locations in a video where advertisements are placed during playback. Ads can be inserted at pre-roll (at the beginning of the video), mid-roll (during the video), or post-roll (at the end of the video) position(s).

Note: Ad insertion points are only applicable for client-side ad insertion. If you create mid-roll ad insertion points for a video, for example, they overwrite any mid-roll ad positions created using the Video Ad Serving Template ad schedule form. This is because the ad insertion points created using the Wowza Video 2.0 API are time-specific and more accurate than the percentages chosen in the Video Ad Serving Template ad schedule page.

no_ads

boolean

When set to true, no ads will be displayed during this video. Note: This feature only works for Iframe embeds.

ad_keywords

string

Used for replacing the ad_keywords macro in the VAST-tag in any Player that plays the video.

created_at

string <date-time>

Date and time, in ISO-8601 format, when video was created.

updated_at

string <date-time>

Date and time, in ISO-8601 format, when video was updated.

state

string

The current state of the video. The state reflects the current status of the video files for the video asset. Possible states listed below:

State	Description
UPLOADING	The source file is currently being uploaded or waiting to be downloaded by our API.
WAITING_FOR_ENCODER	The source file was successfully downloaded by the platform and is in queue to be encoded.
PROCESSING	Source file for the asset is encoding. The current encoding progress can be found on `encoding_progress` property.
FINISHED	The encoding is done and the encoded files can be fetched. In this state it's possible to embed the video.
ERROR	If the platform, for some reason, could not download the source file or failed during the encoding process. `error_messsage` property can give more information about why it errored.
DELETED	The video files have been deleted. Usually the video asset have been deleted when this state is reached and because of that it's very uncommon to see assets with this state.

encoding_progress

number <double>

Progress of video encoding, in percentage. The the max value, 100, is reached when all video files have been encoded.

upload_progress

number <double>

Progress of source file upload, in percentage. If the value is 100 the source file is uploaded.

error_message

string

If the platform failed to encode the source file, a message describing the error reason will be presented in this property.

deactivated

boolean

Default: false

If true, this video has been deactivated and is no longer available for embedding. This usually happens if the account was cancelled or trial limits were exceeded.

Array of objects (ImageModel)

Images used together with the video in the platform and the player.

For platform video images specified in create and update requests, these are uploaded and delivered through the platform. For remote assets the specified image URLs are just passed along to the player using the URL specified in the request.

Array of objects (EncodingModel)

Array containing all available video files and their metadata.

object (DRMConfigModel)

Contains all DRM configurations for one video.

shallow_copy

boolean

Whether this video is a shallow copy of another video. A shallow copy uses Video files controlled by another Video, usually on another Workspace.

Videos that are shallow copies can't use all features available for normal videos. For example, it's not possible to upload a new version of the video.

Another difference is that deleting the video will not delete any video files. If the video asset that is the source of the copy is deleted, the files will no longer be available for this asset.

shallow_copy_source_id

string

If the video is a shallow copy, this field contains the ID of the source Video entity.

Note: There are cases where it is not possible to identify the source and in those cases this value will be null.

multiple_audio_tracks

boolean

If true, this video has several different audio tracks available for the player. For example, there may be audio tracks in different languages.

audio_only

boolean

If true, this video has no video track but only audio tracks.

version

integer <int32>

Tracks the number of times a new source file was uploaded for this video asset. For each time a new source file is uploaded, the value increases by one.

object (ThumbnailResponse)

Link to the VTT file used by the Thumbnails plug-in. See Thumbnails to learn more.

Array of objects (AnimatedPreviewModel)

The animated previews for the video.

object

The origin of the video.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

get/videos/{id}

Request samples

Shell
JavaScript
Java
Python

// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "GET" \
  "${WV_HOST}/api/v2.0/videos/2aa3343e-2fb5-42c3-8671-b52c24b7c3e2"

Response samples

200
401
403
404
410

application/json

{"video": {"id": "2aa3343e-2fb5-42c3-8671-b52c24b7c3e2",
"name": "My video",
"description": "A new video for my business.",
"duration_in_ms": 0,
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"ad_insertion_points": [{"offset_from_start_in_ms": 20000,
"description": "mid-roll"
}
],
"no_ads": true,
"ad_keywords": "special_ads",
"created_at": "2024-01-01T12:33:22Z",
"updated_at": "2024-01-01T12:33:22Z",
"state": "FINISHED",
"encoding_progress": 0,
"upload_progress": 0,
"error_message": "string",
"deactivated": false,
"images": [{"type": "thumbnail",
"url": "https://example.com/image.jpg"
}
],
"encodings": [{"audio_bitrate_in_kbps": 2300,
"audio_channel": 2,
"audio_codec": "aac",
"audio_sample_rate": 44100,
"height": 1080,
"width": 1920,
"video_file_url": "https://flowplayer.com/video.mp4",
"video_container": "mp4",
"video_codec": "h264",
"total_bitrate_in_kbps": 1023,
"created_at": "2019-08-24T14:15:22Z",
"size_in_bytes": 8325555
}
],
"drm": {"com.widevine.alpha": {"license_server": "string",
"certificate": "string"
},
"com.apple.fps.1_0": {"license_server": "string",
"certificate": "string"
},
"com.microsoft.playready": {"license_server": "string",
"certificate": "string"
}
},
"shallow_copy": true,
"shallow_copy_source_id": "string",
"multiple_audio_tracks": true,
"audio_only": true,
"version": 0,
"thumbnails": {"src": "string"
},
"animated_previews": [{"url": "string",
"type": "string",
"height": 1080,
"width": 1920
}
],
"origin": {"id": "wqrs0k75",
"type": "live_stream",
"uptime_id": "hvpcp3kn"
}
}
}

Update a video's metadata

This operation updates a video's metadata. To replace the video file, use the PUT /video/ID.

Request

path Parameters

id

required

string

Unique identifier for the video.

Example: 51cd5c07-1583-4f5e-bd81-f1aa11510ea9

Request Body schema: application/json

object (video)

name	string The video name. Can be displayed in the player. If not specified, it will default to the input file's name.
description	string The video description. Can be displayed in the player.
unpublish	boolean Default: true If `true` the `unpublished_at` is respected and the video will not be available after `unpublished_at`. If `false` the video will not be unpublished.
unpublished_at	string <date-time> Date and time, in ISO-8601, format when video no longer is available for publishing. After this date, the video is not visible in the player if using `ovp-plugin` to request the video.
published	boolean Determines, together with `published_at` and `unpublished_at`, if this video will be visible in public listings such as MRSS-feeds, endscreens and playlists. If `true`, and if `published_at` and `unpublished_at` allows, the video will be visible.
published_at	string <date-time> Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using `ovp-plugin` to request the video.
tags	Array of strings An array of tags.
category_id	string Default: "<The account's default category>" The unique identifier for the category that the video belongs to.
	Array of objects A list of ad insertion points specified for a video. Ad insertion points are pre-defined locations in a video where advertisements are placed during playback. Ads can be inserted at pre-roll (at the beginning of the video), mid-roll (during the video), or post-roll (at the end of the video) position(s). Note: Ad insertion points are only applicable for client-side ad insertion. If you create mid-roll ad insertion points for a video, for example, they overwrite any mid-roll ad positions created using the Video Ad Serving Template ad schedule form. This is because the ad insertion points created using the Wowza Video 2.0 API are time-specific and more accurate than the percentages chosen in the Video Ad Serving Template ad schedule page.
no_ads	boolean When set to `true`, no ads will be displayed during this video. Note: This feature only works for Iframe embeds.
ad_keywords	string Used for replacing the `ad_keywords` macro in the VAST-tag in any player that plays the video.

Responses

200

Success

Response Schema: application/json

object (video)

id

string

The unique identifier for the video.

name

string

The video name. Can be displayed in the player. If not specified, it will default to the input file's name.

description

string

The video description. Can be displayed in the player.

duration_in_ms

integer <int64>

Duration of the video in milliseconds.

unpublish

boolean

Default: true

If true, the unpublish_date is respected and the video will not be available after unpublish_date. If false, the video will not be unpublished.

unpublished_at

string <date-time>

Date and time, in ISO-8601 format, when video no longer is available for publishing. After this date the video is not visible in the player if using ovp-plugin to request the video.

published

boolean

This field, together with publish_date and unpublish_date, determines if this video will be visible in public listings such as MRSS-feeds, endscreens, and playlists. If true and publish_date and unpublish_date allows, the video will be visible.

published_at

string <date-time>

Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using ovp-plugin to request the video.

tags

Array of strings

An array of tags.

category_id

string

Default: "<The account's default category>"

The unique identifier for the category that the video belongs to.

Array of objects

A list of ad insertion points specified for a video. Ad insertion points are pre-defined locations in a video where advertisements are placed during playback. Ads can be inserted at pre-roll (at the beginning of the video), mid-roll (during the video), or post-roll (at the end of the video) position(s).

Note: Ad insertion points are only applicable for client-side ad insertion. If you create mid-roll ad insertion points for a video, for example, they overwrite any mid-roll ad positions created using the Video Ad Serving Template ad schedule form. This is because the ad insertion points created using the Wowza Video 2.0 API are time-specific and more accurate than the percentages chosen in the Video Ad Serving Template ad schedule page.

no_ads

boolean

When set to true, no ads will be displayed during this video. Note: This feature only works for Iframe embeds.

ad_keywords

string

Used for replacing the ad_keywords macro in the VAST-tag in any Player that plays the video.

created_at

string <date-time>

Date and time, in ISO-8601 format, when video was created.

updated_at

string <date-time>

Date and time, in ISO-8601 format, when video was updated.

state

string

The current state of the video. The state reflects the current status of the video files for the video asset. Possible states listed below:

State	Description
UPLOADING	The source file is currently being uploaded or waiting to be downloaded by our API.
WAITING_FOR_ENCODER	The source file was successfully downloaded by the platform and is in queue to be encoded.
PROCESSING	Source file for the asset is encoding. The current encoding progress can be found on `encoding_progress` property.
FINISHED	The encoding is done and the encoded files can be fetched. In this state it's possible to embed the video.
ERROR	If the platform, for some reason, could not download the source file or failed during the encoding process. `error_messsage` property can give more information about why it errored.
DELETED	The video files have been deleted. Usually the video asset have been deleted when this state is reached and because of that it's very uncommon to see assets with this state.

encoding_progress

number <double>

Progress of video encoding, in percentage. The the max value, 100, is reached when all video files have been encoded.

upload_progress

number <double>

Progress of source file upload, in percentage. If the value is 100 the source file is uploaded.

error_message

string

If the platform failed to encode the source file, a message describing the error reason will be presented in this property.

deactivated

boolean

Default: false

If true, this video has been deactivated and is no longer available for embedding. This usually happens if the account was cancelled or trial limits were exceeded.

Array of objects (ImageModel)

Images used together with the video in the platform and the player.

For platform video images specified in create and update requests, these are uploaded and delivered through the platform. For remote assets the specified image URLs are just passed along to the player using the URL specified in the request.

Array of objects (EncodingModel)

Array containing all available video files and their metadata.

object (DRMConfigModel)

Contains all DRM configurations for one video.

shallow_copy

boolean

Whether this video is a shallow copy of another video. A shallow copy uses Video files controlled by another Video, usually on another Workspace.

Videos that are shallow copies can't use all features available for normal videos. For example, it's not possible to upload a new version of the video.

Another difference is that deleting the video will not delete any video files. If the video asset that is the source of the copy is deleted, the files will no longer be available for this asset.

shallow_copy_source_id

string

If the video is a shallow copy, this field contains the ID of the source Video entity.

Note: There are cases where it is not possible to identify the source and in those cases this value will be null.

multiple_audio_tracks

boolean

If true, this video has several different audio tracks available for the player. For example, there may be audio tracks in different languages.

audio_only

boolean

If true, this video has no video track but only audio tracks.

version

integer <int32>

Tracks the number of times a new source file was uploaded for this video asset. For each time a new source file is uploaded, the value increases by one.

object (ThumbnailResponse)

Link to the VTT file used by the Thumbnails plug-in. See Thumbnails to learn more.

Array of objects (AnimatedPreviewModel)

The animated previews for the video.

object

The origin of the video.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

patch/videos/{id}

Request samples

Payload
Shell
JavaScript
Java
Python

application/json

{"video": {"name": "My video",
"description": "A new video for my business.",
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"ad_insertion_points": [{"offset_from_start_in_ms": 20000,
"description": "mid-roll"
}
],
"no_ads": true,
"ad_keywords": "special_ads"
}
}

Response samples

application/json

{"video": {"id": "2aa3343e-2fb5-42c3-8671-b52c24b7c3e2",
"name": "My video",
"description": "A new video for my business.",
"duration_in_ms": 0,
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"ad_insertion_points": [{"offset_from_start_in_ms": 20000,
"description": "mid-roll"
}
],
"no_ads": true,
"ad_keywords": "special_ads",
"created_at": "2024-01-01T12:33:22Z",
"updated_at": "2024-01-01T12:33:22Z",
"state": "FINISHED",
"encoding_progress": 0,
"upload_progress": 0,
"error_message": "string",
"deactivated": false,
"images": [{"type": "thumbnail",
"url": "https://example.com/image.jpg"
}
],
"encodings": [{"audio_bitrate_in_kbps": 2300,
"audio_channel": 2,
"audio_codec": "aac",
"audio_sample_rate": 44100,
"height": 1080,
"width": 1920,
"video_file_url": "https://flowplayer.com/video.mp4",
"video_container": "mp4",
"video_codec": "h264",
"total_bitrate_in_kbps": 1023,
"created_at": "2019-08-24T14:15:22Z",
"size_in_bytes": 8325555
}
],
"drm": {"com.widevine.alpha": {"license_server": "string",
"certificate": "string"
},
"com.apple.fps.1_0": {"license_server": "string",
"certificate": "string"
},
"com.microsoft.playready": {"license_server": "string",
"certificate": "string"
}
},
"shallow_copy": true,
"shallow_copy_source_id": "string",
"multiple_audio_tracks": true,
"audio_only": true,
"version": 0,
"thumbnails": {"src": "string"
},
"animated_previews": [{"url": "string",
"type": "string",
"height": 1080,
"width": 1920
}
],
"origin": {"id": "wqrs0k75",
"type": "live_stream",
"uptime_id": "hvpcp3kn"
}
}
}

Re-upload a video

This operation initiates a re-upload of a video.

Request

path Parameters

id

required

string

Unique identifier for the video.

Example: 51cd5c07-1583-4f5e-bd81-f1aa11510ea9

Request Body schema: application/json

object (video)

DirectInputRequest (object) or FetchInputRequest (object) (InputVideoRequest)

Specifies the input method for uploading the video.

There are two methods to choose from: DIRECT or FETCH.

Expand the input description, by clicking the > next to the input label, then click each tab to learn about the methods.

Learn more:

One of:

Specifies the input method for uploading the video.

There are two methods to choose from: DIRECT or FETCH.

Expand the input description, by clicking the > next to the input label, then click each tab to learn about the methods.

Learn more:

method

required

string

Method that video file will be provided. Indicates that you'll upload a video from local storage. Use the upload_url parameter in the response to do the actual upload of the video.

Value: "DIRECT"

Responses

200

Success

Response Schema: application/json

object (video)

id

string

The unique identifier for the video.

name

string

The video name. Can be displayed in the player. If not specified, it will default to the input file's name.

description

string

The video description. Can be displayed in the player.

duration_in_ms

integer <int64>

Duration of the video in milliseconds.

unpublish

boolean

Default: true

If true, the unpublish_date is respected and the video will not be available after unpublish_date. If false, the video will not be unpublished.

unpublished_at

string <date-time>

Date and time, in ISO-8601 format, when video no longer is available for publishing. After this date, the video is not visible in the player if using ovp-plugin to request the video.

published

boolean

This field, together with publish_date and unpublish_date, determines if this video will be visible in public listings such as MRSS-feeds, endscreens and playlists. If true, and publish_date and unpublish_date allows, the video will be visible.

published_at

string <date-time>

Date and time, in ISO-8601 format, when video is available for publishing. Before this date the video is not visible in the player if using ovp-plugin to request the video.

tags

Array of strings

An array of tags.

category_id

string

Default: "<The account's default category>"

The unique identifier for the category that the video belongs to.

Array of objects

A list of ad insertion points specified for a video. Ad insertion points are pre-defined locations in a video where advertisements are placed during playback. Ads can be inserted at pre-roll (at the beginning of the video), mid-roll (during the video), or post-roll (at the end of the video) position(s).

Note: Ad insertion points are only applicable for client-side ad insertion. If you create mid-roll ad insertion points for a video, for example, they overwrite any mid-roll ad positions created using the Video Ad Serving Template ad schedule form. This is because the ad insertion points created using the Wowza Video 2.0 API are time-specific and more accurate than the percentages chosen in the Video Ad Serving Template ad schedule page.

no_ads

boolean

When set to true, no ads will be displayed during this video. Note: This feature only works for Iframe embeds.

ad_keywords

string

Used for replacing the ad_keywords macro in the VAST-tag in any player that plays the video.

created_at

string <date-time>

Date and time, in ISO-8601 format, when video was created.

updated_at

string <date-time>

Date and time, in ISO-8601 format, when video was updated.

state

string

The current state of the video. The state reflects the current status of the video files for the video asset. Possible states listed below:

State	Description
UPLOADING	The source file is currently being uploaded or waiting to be downloaded by our API.
WAITING_FOR_ENCODER	The source file was successfully downloaded by the platform and is in queue to be encoded.
PROCESSING	Source file for the asset is encoding. The current encoding progress can be found on `encoding_progress` property.
FINISHED	The encoding is done and the encoded files can be fetched. In this state it's possible to embed the video.
ERROR	If the platform, for some reason, could not download the source file or failed during the encoding process. `error_messsage` property can give more information about why it errored.
DELETED	The video files have been deleted. Usually the Video asset have been deleted when this state is reached and because of that it's very uncommon to see assets with this state.

encoding_progress

number <double>

Progress of video encoding, in percentage. The max value, 100, is reached when all video files have been encoded.

upload_progress

number <double>

Progress of source file upload, in percentage. If the value is 100, the source file is uploaded.

error_message

string

If the platform failed to encode the source file, a message describing the error reason will be presented in this property.

deactivated

boolean

Default: false

If true, this video has been deactivated and is no longer available for embedding. This usually happens if the account was cancelled or trial limits were exceeded.

Array of objects (ImageModel)

Images used together with the video in the platform and the player.

For platform video images specified in create and update requests, these are uploaded and delivered through the platform. For remote assets, the specified image URLs are passed along to the player using the URL specified in the request.

Array of objects (EncodingModel)

Array containing all available video files and their metadata.

object (DRMConfigModel)

Contains all DRM configurations for one video.

shallow_copy

boolean

Whether this video is a shallow copy of another video. A shallow copy uses video files controlled by another video, usually on another workspace.

Videos that are shallow copies can't use all features available for normal videos. For example, it's not possible to upload a new version of the video.

Another difference is that deleting the video will not delete any video files. If the video asset that is the source of the copy is deleted, the files will no longer be available for this asset.

shallow_copy_source_id

string

If the video is a shallow copy, this field contains the ID of the source video entity.

Note: There are cases where it is not possible to identify the source and in those cases this value will be null.

multiple_audio_tracks

boolean

If true, this video has several different audio tracks available for the player. For example, there may be audio tracks in different languages.

audio_only

boolean

If true, this video has no video track but only audio tracks.

version

integer <int32>

Tracks the number of times a new source file was uploaded for this video asset. For each time a new source file is uploaded, the value increases by one.

object (ThumbnailResponse)

Link to the VTT file used by the Thumbnails plug-in. See Thumbnails to learn more.

Array of objects (AnimatedPreviewModel)

The animated previews for the video.

upload_url

string

If input method DIRECT was select, this field contains the signed URL that will be used to upload the file.

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

put/videos/{id}

Request samples

Payload
Shell
JavaScript
Java
Python

application/json

{"video": {"input": {"method": "DIRECT"
}
}
}

Response samples

application/json

{"video": {"id": "2aa3343e-2fb5-42c3-8671-b52c24b7c3e2",
"name": "My video",
"description": "A new video for my business.",
"duration_in_ms": 0,
"unpublish": true,
"unpublished_at": "2025-01-01T12:33:22Z",
"published": true,
"published_at": "2024-01-01T12:33:22Z",
"tags": ["foo",
"bar"
],
"category_id": "<The account's default category>",
"ad_insertion_points": [{"offset_from_start_in_ms": 20000,
"description": "mid-roll"
}
],
"no_ads": true,
"ad_keywords": "special_ads",
"created_at": "2025-01-01T12:33:22Z",
"updated_at": "2024-01-01T12:33:22Z",
"state": "FINISHED",
"encoding_progress": 0,
"upload_progress": 0,
"error_message": "string",
"deactivated": false,
"images": [{"type": "thumbnail",
"url": "https://example.com/image.jpg"
}
],
"encodings": [{"audio_bitrate_in_kbps": 2300,
"audio_channel": 2,
"audio_codec": "aac",
"audio_sample_rate": 44100,
"height": 1080,
"width": 1920,
"video_file_url": "https://flowplayer.com/video.mp4",
"video_container": "mp4",
"video_codec": "h264",
"total_bitrate_in_kbps": 1023,
"created_at": "2019-08-24T14:15:22Z",
"size_in_bytes": 8325555
}
],
"drm": {"com.widevine.alpha": {"license_server": "string",
"certificate": "string"
},
"com.apple.fps.1_0": {"license_server": "string",
"certificate": "string"
},
"com.microsoft.playready": {"license_server": "string",
"certificate": "string"
}
},
"shallow_copy": true,
"shallow_copy_source_id": "string",
"multiple_audio_tracks": true,
"audio_only": true,
"version": 0,
"thumbnails": {"src": "string"
},
"animated_previews": [{"url": "string",
"type": "string",
"height": 1080,
"width": 1920
}
],
"upload_url": "string"
}
}

Delete a video

This operation deletes a video and all its related files.

Request

path Parameters

id

required

string

Unique identifier for the video

Example: 51cd5c07-1583-4f5e-bd81-f1aa11510ea9

Responses

204

No Content

401

Unauthorized

403

Forbidden

404

Not Found

410

Gone

422

Unprocessable Entity

delete/videos/{id}

Request samples

Shell
JavaScript
Java
Python

// Using cURL
curl -H "Authorization: Bearer ${WV_JWT}" \
  
  -H "Content-Type: application/json" \
  -X "DELETE" \
  "${WV_HOST}/api/v2.0/videos/2aa3343e-2fb5-42c3-8671-b52c24b7c3e2"

Response samples

401
403
404
410
422

application/json

{"Example Response 1": {"meta": {"status": 401,
"code": "ERR-401-NoApiKey",
"title": "No API Key Error",
"message": "No API key sent in header.",
"description": "",
"links": [ ]
}
},
"Example Response 2": {"meta": {"status": 401,
"code": "ERR-401-NoAccessKey",
"title": "No Access Key Error",
"message": "No access key sent in header.",
"description": "",
"links": [ ]
}
},
"Example Response 3": {"meta": {"status": 401,
"code": "ERR-401-InvalidApiKey",
"title": "Invalid Api Key Error",
"message": "Invalid API key.",
"description": "",
"links": [ ]
}
},
"Example Response 4": {"meta": {"status": 401,
"code": "ERR-401-InvalidAccessKey",
"title": "Invalid Access Key Error",
"message": "Invalid access key.",
"description": "",
"links": [ ]
}
},
"Example Response 5": {"meta": {"status": 401,
"code": "ERR-401-BadAccountStatus",
"title": "Bad Account Status Error",
"message": "Your account's status doesn't allow this action.",
"description": "",
"links": [ ]
}
},
"Example Response 6": {"meta": {"status": 401,
"code": "ERR-401-FeatureNotEnabled",
"title": "Feature Not Enabled Error",
"message": "This feature isn't enabled.",
"description": "",
"links": [ ]
}
},
"Example Response 7": {"meta": {"status": 401,
"code": "ERR-401-TrialExceeded",
"title": "Bad Billing Status Error",
"message": "Your billing status needs attention. You can't start or add live streams until your billing status is updated.",
"description": "",
"links": [ ]
}
},
"Example Response 8": {"meta": {"status": 401,
"code": "ERR-401-ExpiredToken",
"title": "JWT is expired",
"message": "Token has exired.",
"description": "",
"links": [ ]
}
},
"Example Response 9": {"meta": {"status": 401,
"code": "ERR-401-InvalidToken",
"title": "JWT is invalid",
"message": "Token is invalid.",
"description": "",
"links": [ ]
}
}
}