Reference Documentation

Basic actions

Getting channel's details

Parameters

Response

Key-value pairs under a "channel" key. Example:

{
	"channel": {
		"id": "1111",
		"title": "Channel title",
		"description": "Description of channel",
		"tags": [
			"tag1",
			"tag2"
		],
		"url": "channel-title",
		"status": "offair",
		"last_broadcast_at": 1400000000,
		"tinyurl": "http://ustre.am/asdasd1",
		"stream": {
			"hls": "http://iphone-streaming.ustream.tv/uhls/1111/streams/live/iphone/playlist.m3u8",
			"dhls": "http://1111-channel-hls.ums.ustream.tv/playlist/directhls/channel/1111/playlist.m3u8?sgn=123",
		},
		"stats": {
			"viewer_total": 10000000,
			"viewer": 1000
		},
		"thumbnail": {
			"live": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/channel_192x108:1.png"
		},
		"owner": {
			"id": "1234",
			"username": "api-user",
			"picture": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/user_48x48:1.png"
		},
		"locks": []
	}
}

Minimal response example:

{
	"channel": {
		"id": "1111",
		"title": "Channel title",
		"owner": {
			"id": "1234",
			"username": "api-user",
			"picture": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/user_48x48:1.png"
		},
		"picture": {
			"90x90": "https://ustvstaticcdn1-a.akamaihd.net/images/defaults/channel_90x90:1.png",
			"66x66": ...
		},
		"locks": {
			"hash": {
				"type": "advanced",
				"auth_method": "custom"
			}
		}
	}
}

Explanation of some values:

Error codes

Creating a channel

Create a new channel for the current account.

Prerequisites

The caller must have an access token capable initializing channel creation. To obtain a token, the client must request one from the authorization server.

Example initialization of a web-server token-acquiring flow:

https://authentication.video.ibm.com/authorize?response_type=code&client_id=A...Z&redirect_uri=http://...

Example initialization of an implicit token-acquiring flow:

https://authentication.video.ibm.com/authorize?response_type=token&client_id=A...Z&redirect_uri=http://...

See more examples

Channel creation

Parameters

The body of the request should contain the channel title, and optionally it can contain the description and tags. The Content-Type of the request should be application/x-www-form-urlencoded.

Example:

POST users/self/channels.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Channel

The token in the request above is only an example.

Response

{
	"channel": {
		"id":"13091307",
		"title":"Whatever Test 1234",
		"url":"whatever-test-1234",
		"tiny_url":"http://ustre.am/SVE7"
	}
}

Possible negative responses

• 401 Unauthorized: The provided Access Token is missing, revoked, expired or malformed
• 409 Conflict: The channel title or the channel URL is already in use
• 400 Bad Request: The channel title is invalid
• 503 Service Unavailable: There is a temporary error on the server which makes it impossible to serve the request

Edit channel details

Edit a channel's title, description and tags.

Parameters

Response

On success a response with HTTP status 204 No Content is returned.

Error codes

Deleting a channel

Permanently delete a channel from the current account.

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Listing the user's channels

Get a detailed list of the user's channels, including live status, thumbnail, and mobile and broadcast URLs

Parameters

Response

A list of key-value pairs under a "channels" key containing the following information:

The paging information can be found under the "paging" key. Example:

{
	"paging": {
		"previous": {
			"href": "https://api.video.ibm.com/users/self/channels.json?pagesize=PAGESIZE&p=PREVIOUS_PAGE"
		},
		"actual": {
			"href": "https://api.video.ibm.com/users/self/channels.json?pagesize=PAGESIZE&p=PAGE"
		},
		"next": {
			"href": "https://api.video.ibm.com/users/self/channels.json?pagesize=PAGESIZE&p=NEXT_PAGE"
		}
	}
}

List channel all metadata values

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Set channel metadata value

Parameters

Examples

Make sure the values are always properly URL encoded.

value=test%20string

value=55.4

value=2020-01-02T15%3A20%3A59%2B0100

value=true

value=a%2Cb%2Cc%2Cd

value[url]=https%3A%2F%2Fvideo.ibm.com%2F&value[text]=IBM%20Video%20Streaming

value[]=1&value[]=2

Response

On success save a response with HTTP status 204 is returned.

Error codes

Remove channel metadata value

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Get the display settings of the custom metadata fields

Response

On success a response with HTTP status 200 is returned.

Set the display setting of a custom metadata field

Parameters

Response

On success a response with HTTP status 204 is returned.

Error codes

Delete the display setting of a custom metadata field

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Device Passwords

Get device passwords

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Explanation of some values:

Response example

{
  "device_passwords": [
    {
      "device_name": "Sample Device 1",
      "user_name": "xnwj3mseuka",
      "created_at": 1497441340,
      "valid_from": 1497443340,
      "valid_until": null
    },
    {
      "device_name": "Sample Device 2",
      "user_name": "ymvbk9bu7f8",
      "created_at": 1497341340,
      "valid_from": 1497341880,
      "valid_until": 1497381880
    }
  ],
  "paging": []
}

Paging information can be found under the "paging" key. Example:

"paging": {
	"previous": "https://api.video.ibm.com/users/self/device-passwords.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.video.ibm.com/users/self/device-passwords.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
}

Error codes

Create device password

Parameters

The body of the request must contain the device name and a "valid_from" Unix timestamp.

Response

On success a response with HTTP status 200 OK is returned.

Explanation of some values:

Response example

{
  "device_name": "Sample Device 4",
  "user_name": "jgun36pdc79",
  "password": "jgcxathqhyqcdxp",
  "valid_from": 1497571200,
  "valid_until": 1500249600
}

Error codes

Delete device password

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Security

Password protection

When enabled, viewers must enter a password to view the show. This feature is currently disabled in both the iOS and Android apps.

Supported HTTP methods:

Parameters

GET and DELETE requests have no parameters.
The parameters for the PUT request:

Response

For DELETE and PUT an empty response is returned.
The result for the GET request:

Error codes

Viewer authentication

Viewer Authentication lets you implement custom authentication for authenticating viewers of live and recorded videos served by IBM Video Streaming.

Read detailed documentation

Set up viewer authentication

Parameters

Response

HTTP response codes returned when the action is successful:

Specific error codes returned when the action failed:

Get viewer authentication settings

Parameters

This request has no parameters.

Response

On success, key-value pairs are returned under a "hashlock" key.

Example:

{
    "hashlock": {
        "type": "advanced",
        "url": "https://align.ustream.tv/auth/123",
        "message": null,
        "button_caption": null,
        "popup_width": "0",
        "popup_height": "0"
    }
}
        

Specific error codes returned when the action failed:

Remove viewer authentication

Parameters

This request has no parameters.

Response

On success the 200 OK HTTP response code is returned.

Specific error codes returned when the action failed:

Embed restriction

By default all IBM Video Streaming channels can be embedded anywhere across the internet. By restricting the embed URLs, you can control the viewing experience and limit distribution to your own preferred partners.

Get embed lock status

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200

Error codes

Edit embed lock

Parameters

Response

On success a response with HTTP status 204 No Content is returned.

Error codes

Get embed lock URL whitelist

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200

Error codes

Add URL to embed lock URL whitelist

Parameters

You can only add one URL per API call.

Response

On success a response with HTTP status 201 Created is returned.

Error codes

Empty the embed lock URL whitelist

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Sharing control

By turning this feature on the sharing feature will be removed from the viewer.

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error Codes

Whitelabel Broadcasting

Branding control

With co-branding, you can display your brand prominently in the player. With full branding, you can even remove the default IBM Video Streaming watermark. No-branding allows removing the IBM Video Streaming watermark and go with no watermark at all.

Set branding type

Parameters

The type parameter must be passed in the HTTP body, not in the URL.

Available branding types

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Disable branding

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Update logo settings

Only 0 is supported as LOGO_ID currently.

Parameters

The type parameter must be passed in the HTTP body, not in the URL.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Uploading logo

Only 0 is supported as LOGO_ID currently.

Request

The logo must be passed in the HTTP body. Supported image types are image/jpeg, image/png, image/gif, recommended size is maximum 288 x 96 pixels. Maximum file size is 10MB

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Channel page control

Your channel and videos will not be found anywhere on ustream.tv. Viewers will only be able to watch embedded players on external websites. If you want the channel to appear only on your own website, make sure to restrict URL embeds to your site as well.

Get page lock setting

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200

Error codes

Edit page lock

Parameters

Response

On success a response with HTTP status 204 No Content is returned.

Error codes

Hide viewer numbers

By setting this feature the viewer number of a live channel will not be visible in the viewer.

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Channel design

Channel page background

Get

Get current background color

Parameters

This request has no parameters.

Response

Key-value pairs under a "background" key.

Error codes

Edit background color

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Remove settings

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Channel picture

Set channel picture

Parameters

Response

On success a response with HTTP status 204 No Content is returned.

Error codes

Remove channel picture

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Channel featured videos

Channel featured videos is a list of videos that can be shown on the channel page, under the featured videos tab.

List the channel featured videos

Parameters

Response

A list of key-value pairs under a "videos" key.

⚠️ The "media_urls" field below is being deprecated. For video download URLs please see the Downloading videos section. ⚠️

Example:

{
"videos": [{
		"id": "111",
		"title": "Title of video",
		"description": "Description of video",
		"url": "http://www.ustream.tv/recorded/111",
		"length": "12345.123456",
		"created_at": 1399388736,
		"added_at": 1399388736,
		"file_size": "120000",
		"views": 0,
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"media_urls": {
			"flv": "http://tcdn.ustream.tv/video/111"
		},
		"links": {
			"channel": {
				"href": "https://api.video.ibm.com/channels/1.json",
				"id": "1"
			}
		}
	},
	...
	]
}

Minimal response example:

{
"video": {
		"id": "111",
		"links": {
			"channel": {
				"href": "https://api.video.ibm.com/channels/1.json",
				"id": "1"
			}
		}
	}
}

Explanation of some values:

The paging information can be found under the "paging" key. Example:

{
"paging": {
		"previous": "https://api.video.ibm.com/channels/CHANNEL_ID/featured-videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
		"next": "https://api.video.ibm.com/channels/CHANNEL_ID/featured-videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
		"page_count": 8,
		"item_count": 38
	}
}

Error codes

Update featured videos of the channel

Parameters

Example:

POST /channels/CHANNEL_ID/featured-videos.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

video_ids[]=111&video_ids[]=222

The token in the request above is only an example.

Successful response

The response will contain the following collection limit headers:

Error codes

Stream settings

Multi quality streaming

By turning this feature on your stream will be transcoded to several versions with different quality settings.

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Recording

Start/stop recording

During broadcast clients can control recorder on an owned channel. There's no direct feedback on the results of the operation.

Parameters

Response

On success a response with HTTP status "202 Accepted" is returned.

On the stop command the response body will contain information about the resulting video (id and API resource uri)

Example usage:

POST /channels/42/recorder.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

command=stop

Example reponse (for stop command):

{
	"video": {
		"id": 11111,
		"url": "https://api.video.ibm.com/videos/11111.json"
	}
}

Getting recording status

During broadcast you can ask for that information using the GET HTTP method on the same resource.

Example reponse:

{
	"video": {
		"id": "11111",
		"url": "https://api.video.ibm.com/videos/11111.json"
	}
}

Autorecord

Videos can be automatically created when broadcasting. The behaviour can be controlled by this resource.

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Getting record time limit

Gets the maximum allowed length of recorded videos for the channel.

Parameters

This request has no parameters.

Response

Error codes

Video

Listing the videos of a channel

Get a detailed list of the videos of a channel

Parameters

Response

A list of key-value pairs under a "videos" key.

⚠️ The "media_urls" field below is being deprecated. For video download URLs please see the Downloading videos section. ⚠️

Example:

{
	"videos": [
		{
			"id": "111",
			"title": "Title of video",
			"description": "Description of video",
			"url": "http://www.ustream.tv/recorded/111",
			"length": "12345.123456",
			"created_at": 1399388736,
			"added_at": 1399388736,
			"file_size": "120000",
			"views": 0,
			"thumbnail": {
				"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_192x108": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_112x63": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_128x72": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_256x144": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_320x180": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_640x360": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_1920x1080": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
			},
			"media_urls": {
				"flv": "http://tcdn.ustream.tv/video/111"
			},
			"links": {
				"channel": {
					"href": "https://api.video.ibm.com/channels/1.json"
				}
			},
			"caption_matches": [
				{
					"start_sec": 31.01,
					"end_sec": 35.7,
					"caption": "of are actually tying your shoes incorrectly yeah yeah"
				},
				{
					"start_sec": 46.81,
					"end_sec": 48.85,
					"caption": "for me very expensive pair of shoes"
				},
				{
					"start_sec": 49.09,
					"end_sec": 51.88,
					"caption": "but those shoes came with round nylon laces"
				}
			]
		},
		...
	]
}

Explanation of some values:

The paging information can be found under the "paging" key. Example:

{
	"paging": {
		"previous": "https://api.video.ibm.com/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
		"next": "https://api.video.ibm.com/channels/CHANNEL_ID/videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
	}
}

Error codes

Listing the videos of the user

Get a detailed list of the videos of the user

Parameters

For parameters and example response, please see the previous section, "Listing the videos of a channel", as it is the same in this case.

Video details

Get video details

Parameters

Response

Key-value pairs under a "video" key.

⚠️ The "media_urls" field below is being deprecated. For video download URLs please see the Downloading videos section. ⚠️

Example:

{
	"video": {
		"id": "111",
		"title": "Title of video",
		"description": "Description of video",
		"url": "http://www.ustream.tv/recorded/111",
		"length": "12345.123456",
		"created_at": 1399388736,
		"added_at": 1399388736,
		"file_size": "120000",
		"views": 0,
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"media_urls": {
			"flv": "http://tcdn.ustream.tv/video/111"
		},
		"stream": {
			"dhls": "http://111-recorded-hls.ums.ustream.tv/playlist/directhls/recorded/111/playlist.m3u8?sgn=123",
		},
		"links": {
			"channel": {
				"href": "https://api.video.ibm.com/channels/1.json",
				"id": "1"
			}
		}
	}
}

Minimal response example:

{
	"video": {
		"id": "111",
		"links": {
			"channel": {
				"href": "https://api.video.ibm.com/channels/1.json",
				"id": "1"
			}
		}
	}
}

Explanation of some values:

Error codes

Edit video details

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Downloading videos

You can download your own videos using this API resource. It provides info on the downbloadable version of your video. You have to provide an access token since it only works for videos you own.

The query parameter VIDEO_FORMAT could be mp4 or flv.

Response

Key-value pairs under a "downloadable" key with details of the status of the downloadable item. Example:

{
    "downloadable": {
        "download_url":"https://download.domain/example_download_path?download_parameters",
        "expires_at":1471363639,
        "status":"available"
    }
}

The property called download_url holds the download URL could be used to download the video file. It could be null if the downloadable version is not available.

The expires_at property contains a Unix timestamp of the moment when the downloadable version will expire. For never expiring downloadable videos this property will be null.

status represents the state of the downloadable video, it could be:

• available if the video is ready to download.
• unavailable if the downloadable version is not (yet) available.
• pending if the process of generation downloadable version is in progress.

Example call

GET /videos/123456/downloadable/mp4.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 782f6544405a22636f3d5d3b63c2573673bf3950

{
    "downloadable": {
        "download_url":"https://download.domain/example_download_path?download_parameters",
        "expires_at":1471363639,
        "status":"available"
    }
}

Requesting a downloadable version of a video

In some cases the downloadable version of a video is not always available. You have to request us to generate a temporary video file for download. The workflow is the following:

1. Use this call to request a downloadable file
2. Poll the same API resource for status updates
3. Use the value of the download_url property as soon as it is available

You have 24 hours to download the video file right after it's available. Please refer the property expires_at for the proper timing.

Requesting a downloadable version is only an emtpy POST on the downloadable video resource. You have to provide an access token since it only works for videos you own.

The query parameter VIDEO_FORMAT could be mp4 or flv .

If everything works as expected, you'll instantly get the same response format as the GET version provides, but the property status will be pending or available.

Example call

POST /videos/123456/downloadable/mp4.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 782f6544405a22636f3d5d3b63c2573673bf3950

{
    "downloadable": {
        "download_url":null,
        "expires_at":null,
        "status":"pending"
    }
}

Uploading videos

Videos can be uploaded by FTP. To upload a file you must do the following steps:

1. Initiate an upload process by an API call. In the response you can find the details of the FTP connect.
2. Upload the video.
3. When the upload is finished, send a "file in place" signal, which tells to our server that it can start process the file.
4. Call the API to check the status of the processing.

Initializing an upload

Parameters

Response

Key-value pairs with details of the ftp access. Example:

{
	"protocol":"ftp",
	"host":"sjc03-vod-upload02.services.video.ibm.com",
	"port":21,
	"path":"/1_12345_12345678901234",
	"user":"1_12345_1234567890",
	"password":"ftppw",
	"videoId":"52177361",
	"url":"ftp://1_1234_1234567890:ftppw@sjc03-vod-upload02.services.video.ibm.com/1_12345_12345678901234"
}

Error codes

Uploading the video file

Using the credentials in the response above, you can upload your video file to our servers. Once you log in to the FTP server, you should put your file to the root, under a name that matches with the path value of the response, followed by the extension.

The url part of the response makes it easier to transfer files, with a single FTP command. For example if you have a file called test.mov, you can use the following FTP command to upload it:

ftp -u ftp://1_1234_1234567890:ftppw@sjc03-vod-upload02.services.video.ibm.com/1_12345_12345678901234 test.mov

Or using the cURL command:

curl ftp://1_1234_1234567890:ftppw@sjc03-vod-upload02.services.video.ibm.com/1_12345_12345678901234 -v -T test.mov

Supported file extensions are: mp4, mov, flv.

Don't forget to set your FTP client to binary file transfer mode, before uploading the video file.

Sending "file in place" signal

Parameters

Response

On success a response with HTTP status 202 Accepted is returned.

Error codes

Check status of processing

Parameters

This request has no parameters.

Response

A key-value pair with details of the status. Example:

{
	"status":"transferred"
}

Available statuses

• initiated
• transferred
• queued
• pending
• transcoding
• complete
• error

Error codes

Deleting a video

Permanently delete a video from the current account.

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Video expiration

A video gets deleted when expires. These videos can be saved by setting the time of the expiration.

Getting video expiration

Parameters

This request has no parameters.

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Setting video expiration

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

List all video metadata values

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Set video metadata value

Parameters

Examples

See at the Set channel metadata value section

Response

On success save a response with HTTP status 204 is returned.

Error codes

Remove video metadata value

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Video thumbnail

You can set a video thumbnail by uploading a picture or selecting a frame. The picture should be less than 10 MB in size and smaller than 4000x4000px.

Uploading a thumbnail

You can upload a thumbnail via multipart requests (multipart/form-data). The field name must be "thumbnail". JPG, PNG and GIF file formats are supported.

Example request with cURL:

curl \
	-X POST 'https://api.video.ibm.com/videos/123456/thumbnail.json' \
	-H 'Authorization: Bearer abcdef123456' \
	-F 'thumbnail=@thumbnail.jpg;type=image/jpeg'

You can use the -v or the --trace thumbnail.jpg options to debug your request.

Response

On success a response with HTTP status 204 No content is returned.

Selecting a frame

Parameters

Response

On success a response with HTTP status 204 No content is returned.

Video labels

A video can have multiple labels. With these API calls you can add and remove labels to/from a video.

Creating a new label

Parameters

Response

A list of key-value pairs under a "label" key. Example:

{
	"label": {
		"18010": {
			"label_id": 18010,
			"label_name": "labelname",
			"label_color": "color-5"
		}
	}
  }

Listing labels

Parameters

None.

Response

A list of key-value pairs under a "labels" key. Example:

{
	"labels": {
		"18010": {
		"label_id": 18010,
		"label_name": "labelname",
		"label_color": "color-5"
		},
		...
	}
}

Modifying a label

Parameters

Response

On success a response with HTTP status 204 No content is returned.

Deleting a label

Parameters

None.

Response

On success a response with HTTP status 204 No content is returned.

Adding labels to a video

Parameters

Response

On success a response with HTTP status 204 No content is returned.

Removing labels from a video

Parameters

Response

On success a response with HTTP status 204 No content is returned.

Getting the labels of a video

Parameters

None.

Response

A list of key-value pairs under a "labels" key. Example:

{
	"labels": {
		"18010": {
		"label_id": 18010,
		"label_name": "labelname",
		"label_color": "color-5"
		},
		...
	}
}

Video caption

List all captions of a video.

Parameters

None.

Response

A list of key-value pairs under a "captions" key. Example:

{
    "captions": [
        {
            "is_default": true,
            "is_visible": false,
            "language": "en-00",
            "status": "active",
            "video_id": "10001"
        },
        {
            "is_default": false,
            "is_visible": false,
            "language": "en-UK",
            "status": "processing",
            "video_id": "10001"
        }
    ]
}

Error codes

Show caption details

Response

Key-value pairs under a "caption" key. Example:

{
	"caption": {
		"is_default": true,
		"is_visible": false,
		"language": "en-00",
		"status": "active",
		"video_id": "10001"
	}
}

Explanation of some values:

Error codes

Modify caption details

Modify caption details for a given language

Parameters

Example:

PUT videos/VIDEO_ID/captions/en-00.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer xxxxxxxxxxxxxx
Content-Type: application/x-www-form-urlencoded

is_visible=1&is_default=0

The token in the request above is only an example.

Response

On success a response with response HTTP status 200 is returned. Example:

{
	"caption": {
		"is_default": true,
		"is_visible": false,
		"language": "en-00",
		"status": "active",
		"video_id": "10001"
	}
}

Explanation of some values:

Error codes

Download vtt file

Response

The file content in WebVTT format. Example:

WEBVTT

00:09.000 --> 00:11.000
We are in New York City

Error codes

Upload a caption

Create a new caption for the given video

Example:

PUT videos/VIDEO_ID/captions/en-00/vtt HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer xxxxxxxxxxxxxx
Content-Type: text/vtt

WEBVTT

00:09.000 --> 00:11.000
We are in New York City

The token in the request above is only an example.

Response

Error codes

List possible languages

Parameters

None.

Response

A list of key-value pairs under a "languages" key. Example:

{
    "languages": [
        {
            "code": "en-00",
            "name": "English"
        },
        {
            "code": "en-US",
            "name": "English (US)"
        },
        {
            "code": "en-UK",
            "name": "English (UK)"
        }
    ]
}

Video trim

You can set video playback start and end point in seconds. Trimming does not affect the original video file.

Set trim

Please note that unsaved auto-recorded videos will become saved when trimming them.

Parameters

Response

On success a response with HTTP status 204 No content is returned.

Error codes

Get trim

Parameters

None.

Response

On success a response with HTTP status 200 OK is returned.

{
	"trim": {
		"start": 323,
		"end": 252
  	}
}

Remove trim

Parameters

None.

Response

On success a response with HTTP status 200 OK is returned.

Video copy

Save a part of on existing video as a new video. The new video will be available on same channel as the original one and it will be unpublished by default.

Create copy

Copy is an async process, you will get a request id in the response.

Parameters

Response

On success a response with HTTP status 202 Accepted is returned.

Error codes

Check copy status

Response

On success a response with HTTP status 200 OK is returned.

Video chapters

Get video chapters

Response

A list of key-value pairs under a "chapters" key.

Example:

{
	"chapters": [
    	{
            "id": "1",
            "title": "First chapter",
            "position": 10
    	},
    	{
            "id": "2",
            "title": "Second chapter",
            "position": 60
    	}
	]
}

Explanation of some values:

Error codes

Add new chapter to the video

Response

On success a response with HTTP status 201 Created is returned.

Error codes

Delete all chapters of a video

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Get chapter info

Response

Key-value pairs under a "chapter" key.

Example:

{
	"chapter": {
		"id": "1",
		"title": "First chapter",
		"position": 10
	}
}

Explanation of some values:

Error codes

Modify video chapter

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Delete video chapter

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Playlists

Playlist settings

You can check whether playlists are enabled or disabled on the channel page.

Response

A successful response contains the "is_enabled" key.

Example:

{
    "success": true,
    "is_enabled": true
}

Error codes

Enabling or disabling playlists on a channel

By turning this feature on, playlists will be visible on your channel page.

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Listing the playlists of a channel

Parameters

Response

A list of key-value pairs under a "playlists" key. Example:

{
	"playlists": [
		{
			"id": "111",
			"title": "Title of a playlist",
			"total_duration": "176.256",
			"thumbnail": {
				"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_192x108": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_112x63": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_128x72": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_256x144": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_320x180": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_640x360": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
				"image_1920x1080": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
			},
			"created_at": 1484127917,
			"updated_at": 1486569501,
			"channel_id": 11223344
		},
		...
	]
}

Explanation of some values:

The paging information can be found under the "paging" key. Example:

"paging": {
	"previous": "https://api.video.ibm.com/channels/CHANNEL_ID/playlists.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.video.ibm.com/channels/CHANNEL_ID/playlists.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
	"page_count": 8,
	"item_count": 38
}

Error codes

Creating a playlist

Parameters

Example:

POST playlists.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Playlist&is_enabled=1

The token in the request above is only an example.

Successful response

The response will contain the following headers:

Error codes

Playlist details

Getting the details of a playlist.

Response

Key-value pairs under a "playlist" key. Example:

{
"playlist": {
		"id": "111",
		"title": "Title of a playlist",
		"total_duration": "176.256",
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_192x108": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_112x63": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_128x72": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_256x144": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_320x180": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_640x360": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg",
			"image_1920x1080": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"created_at": 1484127917,
		"updated_at": 1486569501,
		"channel_id": 11223344
	}
}

Explanation of some values:

Error codes

Modifying a playlist

Modify an existing playlist.

Parameters

The request body must contain the playlist title ("title" field).

Example:

PUT playlists/PLAYLIST_ID.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

title=API+Testing+Playlist+edited

The token in the request above is only an example.

Successful response

Error codes

Deleting a playlist

Delete an existing playlist.

Example:

DELETE playlists/PLAYLIST_ID.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

The token in the request above is only an example.

Successful response

Error codes

Playlist videos

List the videos of a playlist

Parameters

Response

A list of key-value pairs under a "videos" key.

⚠️ The "media_urls" field below is being deprecated. For video download URLs please see the Downloading videos section. ⚠️

Example:

{
"videos": [{
		"id": "111",
		"title": "Title of video",
		"description": "Description of video",
		"url": "http://www.ustream.tv/recorded/111",
		"length": "12345.123456",
		"created_at": 1399388736,
		"added_at": 1399388736,
		"file_size": "120000",
		"views": 0,
		"thumbnail": {
			"default": "https://ustvstaticcdn1-a.akamaihd.net/111.jpg"
		},
		"media_urls": {
			"flv": "http://tcdn.ustream.tv/video/111"
		},
		"links": {
			"channel": {
				"href": "https://api.video.ibm.com/channels/1.json",
				"id": "1"
			}
		}
	},
	...
	]
}

Minimal response example:

"video": {
	"id": "111",
	"links": {
		"channel": {
			"href": "https://api.video.ibm.com/channels/1.json",
			"id": "1"
		}
	}
}

Explanation of some values:

The paging information can be found under the "paging" key. Example:

"paging": {
	"previous": "https://api.video.ibm.com/playlists/PLAYLIST_ID/videos.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
	"next": "https://api.video.ibm.com/playlists/PLAYLIST_ID/videos.json?pagesize=PAGE_SIZE&page=NEXT_PAGE",
	"page_count": 8,
	"item_count": 38
}

Error codes

Playlist video

Get the details of a video in a playlist

Response

Key-value pairs under a "video" key.

Example:

{
  "video": {
    "id": "92858030",
    "title": "SampleVideo 1280x720 30mb",
    "number_of_thumbnails": 1,
    "picture_revision": 2,
    "channel_id": "22818603",
    "video_views": 10,
    "thumbnail": "http://static-cdn1.ustream.tv/i/video/picture/0/1/92/92858/92858030/1_22818603_92858030,192x108,b,1:2.jpg",
    "created_at": 1479718322,
    "added_at": 1479718322,
    "order": 1
  }
}

Explanation of some values:

Error codes

Add video to playlist

Successful response

The response will contain the following collection limit headers:

Error codes

Delete a video from the playlist

Successful response

The response will contain the following collection limit headers:

Error codes

Reposition video on the playlist

Parameters

The body of the call must contain the video position. The Content-Type of the request should be application/x-www-form-urlencoded.

Example:

PUT playlists/PLAYLIST_ID/videos/VIDEO_ID/position.json HTTP/1.1
Host: api.video.ibm.com
Authorization: Bearer 3c2573673b782f6544405a22636f3d5d3b6f3950
Content-Type: application/x-www-form-urlencoded

position=3

The token in the request above is only an example.

Successful response

Error codes

Event

Listing the upcoming events of a channel

Get a detailed list of the events of a channel

Parameters

Response

A list of key-value pairs under an "events" key. Example:

{
	"events": [
		{
			"id": "111",
			"title": "Title of the event",
			"description": "Description of the event",
			"start": 1399388736,
			"duration": 900,
		},
		...
	]
}

Explanation of some values:

The paging information can be found under the "paging" key. Example:

{
	"paging": {
		"previous": "https://api.video.ibm.com/CHANNEL_ID/upcoming-events.json?pagesize=PAGE_SIZE&page=PREVIOUS_PAGE",
		"next": "https://api.video.ibm.com/channels/CHANNEL_ID/upcoming-events.json?pagesize=PAGE_SIZE&page=NEXT_PAGE"
	}
}

Error codes

Custom metadata

List metadata fields

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Create new metadata field

Parameters

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Delete metadata field

Response

On success a response with HTTP status 200 OK is returned.

Error codes

Ingest settings

If you wish to use a non-IBM Video Streaming provided broadcaster application or appliance (like Flash Live Media Encoder, Wirecast, Tricaster, etc.), you will need a stream key or channel key to authenticate with IBM Video Streaming proving that broadcasting to that particular channel is allowed. Also you should get the ingest point where your device or application should connect.

Getting ingest settings

Response

On success a response with HTTP status 200 OK is returned.

Error codes