https://www.brightcove.com/en/ Brightcove Video Cloud Media API Reference

WARNING: This API has been deprecated and should not be used for new projects. Support for write methods were discontinued on June 30, 2017, and read methods will be discontinued on December 31, 2017. Click here for more information.

Brightcove Video Cloud: Media API Reference

The Media API allows you to interact with your Video Cloud library. The API includes Read and Write modules for both videos and playlists. In addition, this reference describes a number of related objects.

For reference information about the objects returned by or passed into the Media API, see the Media Object Reference. In addition to the usage examples included in this reference, see these more extensive examples that demonstrate how to use the Media API.

The Media Write API is available only for Video Cloud Pro and Enterprise customers. If you are interested in upgrading your Video Cloud account, please contact Brightcove for more information.

API Types

The Media Read APIs are RESTful. All requests are GET.

The Media Write APIs requests are POST.

For write requests, the data submitted to the media write API must be in JSON format, encoded as a form parameter named "json". The JSON document should include a "method" field and a "params" field, and the examples you publish should show the whole body of the POST request:

json=
{"method":"update_video","params":{"video":{"id":"1969867342001","shortDescription":"A happy little bird","Name":"Bird_Titmouse","startDate":1363983574000,"endDate":null,"tags":["bird","nature","air"]},"token":"ZY4Ls9Hq6LCBgleGDTaFRDLWWBC8uoXQHkhGuDebKvjFPjHb3iT-4g.."}}

Service URLs

The service URL for the Media Read APIs is:

http://api.brightcove.com/services/library

For the Media Write APIs, the service URL is as follows.

For all regions exceptJapan:

http://api.brightcove.com/services/post

Rate limiting

The Media API is intended to be used as a tool for integrating your CMS or other backend systems with Video Cloud. It is not built for high-volume runtime access.

Read methods

Access frequency for read requests should be limited to 5 total requests per second from one or more devices, and for long-running requests (returning large datasets), no more than 10 concurrent requests are permitted.

Write methods

Write requests are single-threaded, so you should wait for a response to a request before submitting another one.

Authorization Tokens

All Media API calls require a token. Video Cloud issues tokens to accounts that are enabled to use the API. There are separate tokens for read methods and write methods in the API. You append your token to the call as a URL parameter, such as token=[tokenString], where tokenString is your URL-encoded token. Note: Media API tokens generally end with one or more dots (.). Be sure to include the dots when you use the API tokens - it's easy to lose them when you cut and paste. You can view and manage your API tokens on the Account Settings: API Management page in Video Cloud Studio, which provides a buttons for emailing tokens or copying them to your clipboard. For more information about tokens, see Managing Media API Tokens.

Protecting your API tokens on the wire

To guard against attempts to sniff out your tokens, consider making your API requests via HTTPS, rather than HTTP. All you need to do to use HTTPS is to make your API call with the https:// protocol, instead of http://, which instructs the browser to encrypt the transaction, including your token. There are performance drawbacks to using HTTPS, because the server and browser need to encrypt and decrypt the traffic.

Request Parameters

For the Read APIs, all parameters are passed as URL parameters. For example:

For the Write APIs, all parameters are passed in the request body as JSON-RPC. For Example:

{ "method": "update_video",
    "params": {
        "token": "...", "video" : {
            "id" : 1234,
            "name" : "new name"
        }
    }
}

Date/Time Data

All date/time data returned by the Media API is in milliseconds of epoch time. It is independent of your time zone or the time zone set for your Video Cloud account in the Account Settings. If you need to present data in a way specific to a time zone, you will need to convert the epoch date/time to a local date/time. See the Epoch Converter site for tools for date and time conversion.

Disabled videos

A video in your account many be disabled for several reasons:

  • it has been deleted
  • it has been set to inactive
  • it has been scheduled for a future date

Most of the Media API search methods, such a search_videos and find_video_by_id, will not return disabled videos. To return inactive videos or videos scheduled for a future date, you can use find_modified_videos or one of the _unfiltered methods. Note: the _unfiltered methods are not enabled by default. To enable them, submit a request to Brightcove Support

The only method that will return deleted videos is find_modified_videos. You can see a working sample here.

Analytics Data

Data returned for videos includes two pieces of basic analytics data:

  • playsTotal: how many times the Video has been played since its creation
  • playsTrailingWeek: how many times the Video has been played within the past seven days, exclusive of today (calculated based on UTC time)

NOTE: this data is derived from the Analytics API, but it is not real-time data. The value returned by the Media API is updated daily and reflects daily data. In addition, these values come from the analytics historical data collection, which a processed and adjusted version of the real-time data, so in some cases you may find recent data missing from the values reported by the Media API, as that data has not be processed yet. See the Analytics API FAQ for more information.

Best practices

Write requests

Write requests are single threaded - concurrent requests are not allowed from the same account, and if a write request is received while another is still being processed, it will fail.

In addition, you should limit write requests that send data of any kind (videos, images, caption files, etc.) to no more than 20 per minute. Otherwise you will likely see timeouts or processing delays.

Large Data Sets

If you are retrieving all the videos in your account, or a large number of videos, there are some things you must be aware of:

  1. You may be tempted to use the largest allowed page_size (100), but it's better to retrieve videos in batches of 25 or less to minimize the possibility of API requests timing out
  2. As you are paging through large data sets, it is possible that the video data may be updated during the operation, which could cause items to shift in responses:
    • You might see an item repeated on successive pages
    • An item might be missed, as it has shifted to a previous response set

    To account for the first possibility, your app should de-dupe the complete item list after you have finished retrieving videos. To handle the second possibility, you need to compare the total number of items retrieved (after de-duping) to the number you were expecting, and then rerun the requests, sorting the results by last_modified_date (descending) - you shouldn't need to retrieve more than one batch to pick up missed items.

  3. You can decrease the likelihood of the scenarios in the previous item by sorting the returned results appropriately. If you do not explicitly set the sort_by parameter, results are sorted by relevance based on a complex algorithm that looks combinations of keywords, tags, and custom field values. If you are searching for videos based on multiple keywords, tags, and/or custom fields, sort by relevance is exactly what you want. However, if you are just trying to retrieve all or a large set of your videos, setting the sort_by parameter explicitly will give you more control over the order of the returned items.

Video Read APIs

Video Cloud Media APIs provide read access to the videos in a publisher's media library using HTTP calls.Read API calls are made as GET requests to //api.brightcove.com/services/library. Arguments are appended as URL params. For example:

Methods

search_videos(token:String, all:List, any:List, none:List, sort_by:List, exact:Boolean, page_size:Integer, page_number:Integer, get_item_count:Boolean, video_fields:List, custom_fields:List, media_delivery:Enum, output:Enum): ItemCollection

Searches videos according to the criteria provided by the user.The criteria are constructed using field/value pairs specified in the command. Consider using the search_videos method for video searches rather than using the other find_video oread methods. The search_videos method offers more flexible search and sorting options than the find_video methods, and is especially more flexible than the find_videos_by_text and find_videos_by_tags methods. For specifications of the search_videos method, see: Using search_videos.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
all (optional) Specifies the field:value pairs for search criteria that MUST be present in the index in order to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription.
any (optional) Specifies the field:value pairs for search criteria AT LEAST ONE of which must be present to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription.
none (optional) Specifies the field:value pairs for search criteria that MUST NOT be present to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription.
sort_by (optional) Specifies the field to sort by, and the direction to sort in. This is specified as: sortFieldName:direction If the direction is not provided, it is assumed to be in ascending order Specify the direction as ASC for ascending or DESC for descending. You can sort by the following fields: DISPLAY_NAME, REFERENCE_ID, PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, START_DATE, PLAYS_TRAILING_WEEK, PLAYS_TOTAL. By default, items are sorted by relevance (best match); items of equal relevance are sorted alphabetically by the video name.Example: sort_by=PUBLISH_DATE:DESC
exact (optional) Boolean If true, disables fuzzy search and requires an exact match of search terms. A fuzzy search does not require an exact match of the indexed terms, but will return a hit for terms that are closely related. The fuzzy search works only on English and Japanese text.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText,tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP,rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json (the default), mrss (RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and CreatingFeeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of videos, ordered as specified by the sort_by argument. If no sort_by argument is supplied, ordered by relevance.

Usage

Return videos that include the word "gibbous" in the display name. The collection returned includes the names and short descriptions of the first 3 videos, ordered by modified date:

Examples

For specifications of the search_videos method, see:

search_videos_unfiltered(token:String, all:List, any:List, none:List, sort_by:List, exact:Boolean, page_size:Integer, page_number:Integer, get_item_count:Boolean, video_fields:List, custom_fields:List, media_delivery:Enum, output:Enum): ItemCollection

Searches videos according to the criteria provided by the user.The criteria are constructed using field/value pairs specified in the command. As an _unfiltered method, search_videos_unfiltered will return inactive, deleted, scheduled videos as well as those that are currently playable. There is no filtering by video status, but if you search for &all=item_state:0, you will only get ACTIVE videos, or &all=item_state:1, and you will only get INACTIVE videos. Note: _unfiltered methods are not enabled for your account by default. To enable them, you must submit a Support requests.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
all (optional) Specifies the field:value pairs for search criteria that MUST be present in the index in order to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription.
any (optional) Specifies the field:value pairs for search criteria AT LEAST ONE of which must be present to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription.
none (optional) Specifies the field:value pairs for search criteria that MUST NOT be present to return a hit in the result set. The format is fieldName:value. If the field's name is not present, it is assumed to be displayName, shortDescription, and longDescription.
sort_by (optional) Specifies the field to sort by, and the direction to sort in. This is specified as: sortFieldName:direction If the direction is not provided, it is assumed to be in ascending order Specify the direction as ASC for ascending or DESC for descending. You can sort by the following fields: DISPLAY_NAME, REFERENCE_ID, PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, START_DATE, PLAYS_TRAILING_WEEK, PLAYS_TOTAL. By default, items are sorted by relevance (best match); items of equal relevance are sorted alphabetically by the video name.Example: sort_by=PUBLISH_DATE:DESC
exact (optional) Boolean If true, disables fuzzy search and requires an exact match of search terms. A fuzzy search does not require an exact match of the indexed terms, but will return a hit for terms that are closely related. The fuzzy search works only on English and Japanese text.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText,tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP,rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json (the default), mrss (RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and CreatingFeeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of videos, ordered as specified by the sort_by argument. If no sort_by argument is supplied, ordered by relevance.

Usage

Return videos that include the word "gibbous" in the display name. The collection returned includes the names and short descriptions of the first 3 videos, ordered by modified date:
//api.brightcove.com/services/library?command=search_videos_unfiltered&all=display_name:gibbous&video_fields=name,shortDescription&page_size=3&get_item_count=true&sort_by=MODIFIED_DATE:DESC&token=[token]

Examples

For specifications of the search_videos_unfiltered method, see:

find_all_videos(token:String, page_size:Integer, page_number:Integer, sort_by: SortByType, sort_order: SortOrderType, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set,media_delivery:Enum, output:Enum): ItemCollection

Note: we strongly recommend using search_videos instead of find_all_videos. search_videos calls without search terms will return all videos much more efficiently and with more options for sorting results.

Find all videos in the Video Cloud media library for this account. This method has the limitation of returning only videos available for play, and does not include videos marked as inactive, currently in the upload process, or outside the scheduled play time. See Searching for Unavailable Videos with the Media API for information about solutions to these limitations.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
sort_by (optional) SortByType The field by which to sort the results. A SortByType: One of PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, PLAYS_TOTAL, PLAYS_TRAILING_WEEK.
sort_order (optional) SortOrderType How to order the results: ascending (ASC) or descending (DESC).
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json (the default), mrss (RSS with Media RSS and Video Cloud extensions), and tm (for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of videos matching the specified search criteria.

Usage

Get all videos sorted by most popular: //api.brightcove.com/services/library?command=find_all_videos&sort_by=plays_total&sort_order=DESC&token=[token] Get the names and IDs of recently published videos: //api.brightcove.com/services/library?command=find_all_videos&sort_by=publish_date&video_fields=name,id&token=[token] Get the 5 most popular videos from the last 7 days (starting yesterday): //api.brightcove.com/services/library?command=find_all_videos&sort_by=plays_trailing_week&page_size=5&sort_order=DESC&token=[token]

Examples

For more examples of the find_all_videos method:

find_video_by_id(token:String, video_id:long, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): Video

Finds a single video with the specified ID. See Accessing Video Content with the Media API for various examples of the find_video_by_id method.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
video_id long The ID of the video you would like to retrieve.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
Video The Video you requested, with the specified fields populated, or null, if there is no video with that ID.

Usage

Get the video with the specified ID: //api.brightcove.com/services/library?command=find_video_by_id&video_id=123&token=[token] Get the long description of the video with its ID: //api.brightcove.com/services/library?command=find_video_by_id&video_id=123&video_fields=longDescription&token=[token]

Examples

For more examples of the find_video_by_id method:

find_related_videos(token:String, video_id:Long, reference_id:String, page_size:Integer, page_number:Integer, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Finds videos related to the given video. Combines the name and short description of the given video and searches for any partial matches in the name, short description, long description, tags, and custom fields of all videos in the Video Cloud media library for this account. More precise ways of finding related videos include tagging your videos by subject and using the find_videos_by_tags method to find videos that share the same tags: or creating a playlist that includes that you know are related. Consider using the search_videos method, which offers more flexible search and sorting options.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
video_id (optional) Long The ID of the video we'd like related videos for.
reference_id (optional) String The publisher-assigned reference ID of the video we'd like related videos for.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 200; if you do not set this argument, or if you set it to an integer > 200, your results will come back as if you had set page_size=200.
page_number (optional) Integer The zero-indexed number of the page to return.
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of videos, ordered by relevance to the provided video. More related videos are ranked higher. If no videos match, the call returns a page of videos ordered by the date they were added to your account, so you will never get an empty result set.

Usage

Show total number of related videos to video of given ID and display first 3 //api.brightcove.com/services/library?command=find_related_videos&video_id=123&page_size=3&get_item_count=true&token=[token] Get the names of related videos 6-10 (page 2) //api.brightcove.com/services/library?command=find_related_videos&video_id=123&page_size=5&page_number=1&video_fields=name&token=[token]

Examples

An example of the find_related_videos method:

find_videos_by_ids(token:String, video_ids:List, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Find multiple videos, given their IDs.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
video_ids List The list of video IDs for the videos we want to retrieve.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection an ItemCollection that contains the video objects corresponding to the video IDs given. Note: if you pass in IDs that belong to videos that are either not active or not playable because of schedule constraints, then the ItemCollection will contain null elements for the IDs that are filtered out.

Usage

Get the names and tags of the videos with the specified IDs: //api.brightcove.com/services/library?command=find_videos_by_ids&video_ids=123,456,789&video_fields=name,tags&token=[token] Get the URLs of videos related to the videos with specified IDs: //api.brightcove.com/services/library?command=find_videos_by_ids&video_ids=123,456&video_fields=linkURL&token=[token]

Examples

An example of the find_videos_by_ids method:

find_video_by_reference_id(token:String, reference_id:String, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): Video

Find a video based on its publisher-assigned reference ID.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
reference_id String The publisher-assigned reference ID for the video we're searching for.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
Video The video whose reference ID matches the one given.

Usage

Get the total number of plays for the video with this reference ID: //api.brightcove.com/services/library?command=find_video_by_reference_id&video_fields=playsTotal&reference_id=123&token=[token]

Examples

An example of the find_video_by_reference_id method:

find_videos_by_reference_ids(token:String, reference_ids:List, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Find multiple videos based on their publisher-assigned reference IDs.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
reference_ids List The list of reference IDs for the videos we'd like to retrieve. This value is limited to 150 characters. The value cannot contain commas; to work around this issue, avoid using commas in reference_id values.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditionsor captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad).See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection The collection of videos specified by the reference IDs provided. Note: if you pass in IDs that belong to videos that are either not active or not playable because of schedule constraints, then the ItemCollection will contain null elements for the IDs that are filtered out.

Usage

Get the video IDs of the videos with these reference IDs: //api.brightcove.com/services/library?command=find_videos_by_reference_ids&reference_ids=123,456,789&video_fields=id&token=[token]

Examples

An example of the find_videos_by_reference_ids method:

find_videos_by_user_id(token:String, user_id:String, page_size:Integer, page_number:Integer, sort_by: SortByType, sort_order: SortOrderType, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Deprecated. Read about approaches to user-generated content. retrieves the videos uploaded by the specified user id. This method can be used to find videos submitted using the old consumer-generated media (CGM) module in Brightcove 2.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
user_id String The ID of the user whose videos we'd like to retrieve.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
sort_by (optional) SortByType The field by which to sort the results. A SortByType: One of PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, PLAYS_TOTAL, PLAYS_TRAILING_WEEK.
sort_order (optional) SortOrderType How to order the results: ascending (ASC) or descending (DESC).
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name,shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection An ItemCollection representing the requested page of Videos uploaded by the specified user, in the order specified.

Usage

Get the top 3 most popular videos and total # of videos by a user: //api.brightcove.com/services/library?command=find_videos_by_user_id&user_id=123&page_size=3&sort_by=plays_total&sort_order=DESC&get_item_count=true&token=[token] Get the names of the first 5 videos by a user: //api.brightcove.com/services/library?command=find_videos_by_user_id&user_id=123&page_size=3&sort_by=publish_date&sort_order=ASC&token=[token] Get the video names of the most popular videos by this user this week: //api.brightcove.com/services/library?command=find_videos_by_user_id&user_id=123&sort_by=plays_trailing_week&sort_order=DESC&video_fields=name&token=[token]

find_videos_by_campaign_id(token:String, campaign_id:long, page_size:Integer, page_number:Integer, sort_by: SortByType, sort_order: SortOrderType, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Deprecated. Read about approaches to user-generated content. gets all the videos associated with the given campaign ID. Campaigns are a feature of the old consumer-generated media (CGM) module in Brightcove 2.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
campaign_id long The ID of the campaign you'd like to fetch videos for.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
sort_by (optional) SortByType The field by which to sort the results. A SortByType: One of PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, PLAYS_TOTAL, PLAYS_TRAILING_WEEK.
sort_order (optional) SortOrderType How to order the results: ascending (ASC) or descending (DESC).
get_item_count (optional) Boolean If true, also return how many total results there are in this campaign; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection The requested subset of all videos for the given campaign.

Usage

Get the names of all videos of a campaign: //api.brightcove.com/services/library?command=find_videos_by_campaign_id&campaign_id=123&video_fields=name&token=[token] Get the most popular videos this week by a campaign: //api.brightcove.com/services/library?command=find_videos_by_campaign_id&campaign_id=123&sort_by=plays_trailing_week&sort_order=DESC&token=[token]

find_modified_videos(token:String, from_date:Date, filter:List, page_size:Integer, page_number:Integer, sort_by: SortByType, sort_order: SortOrderType, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Gets all the videos that have been modified since the given time. Any change in metadata, including replacing or retranscoding the video, will count as a modification. For more examples of the find_modified_videos method, see Finding Videos That Have Changed with the Media API.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
from_date Date The date, specified in minutes since January 1st, 1970 00:00:00 GMT, of the oldest Video which you would like returned.
filter (optional) List A comma-separated list of filters, specifying which categories of videos you would like returned.Valid filter values are PLAYABLE, UNSCHEDULED, INACTIVE, and DELETED.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 25; if you do not set this argument, or if you set it to an integer > 25, your results will come back as if you had set page_size=25.
page_number(optional) Integer The zero-indexed number of the page to return.
sort_by (optional) SortByType The field by which to sort the results. A SortByType: One of PUBLISH_DATE, CREATION_DATE, MODIFIED_DATE, PLAYS_TOTAL, PLAYS_TRAILING_WEEK.
sort_order (optional) SortOrderType How to order the results: ascending (ASC) or descending (DESC).
get_item_count (optional) Boolean If true, also return how many total results there are in this campaign; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection All videos that have been modified since the given time.

Usage

Get the ID of all videos that have been modified or deleted since March 3rd, 2003. //api.brightcove.com/services/library?command=find_modified_videos&from_date=17444520&filter=PLAYABLE,DELETED&video_fields=id&token=[token]

Examples

For more examples of the find_modified_videos method:

find_videos_by_text(token:String, text:String, page_size:Integer, page_number:Integer, get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Deprecated.Consider using the search_videos method, which offers more flexible search and sorting options. For specifications of the search_videos method, see: Searching for Videos with the Media API.

Searches through all the videos in this account, and returns a collection of videos whose name, short description, or long description contain a match for the specified text. Unlike some other Read methods, this method does not provide parameters for sorting the result set. The result set is sorted by relevance.

The find_videos_by_text method returns substring matches - words from your search string plus a wildcard (*) at the end; thus, if your search string is "war", the result set will include results such as "warrior", "warfare", and "warbler." Substrings that don't match the beginning of a word are not returned; thus, if your search string is "war", the result set would not include results such as "swarthy" or "inward".

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
text String The text we're searching for.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of videos whose name, short description, or long description contain a match for the text specified.

Usage

Get the third page (matches 11-15) of matching videos with the text 'Ocelot': //api.brightcove.com/services/library?command=find_videos_by_text&text=Ocelot&page_size=5&page_number=2&token=[token] Get the publish date, ID, and name of matching videos with the text 'Ocelots Bobcats and Lions': //api.brightcove.com/services/library?command=find_videos_by_text&text=Ocelots%20Bobcats%20and%20Lions&video_fields=id,name,publishedDate&token=[token]

find_videos_by_tags(token:String, and_tags:List, or_tags:List, page_size:Integer, page_number:Integer, sort_by: SortByType, sort_order: SortOrderType,get_item_count:Boolean, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Deprecated.Consider using the search_videos method, which offers more flexible search and sorting options. For specifications of the search_videos method, see: Searching for Videos with the Media API.

Performs a search on all the tags of the videos in this account, and returns a collection of videos that contain the specified tags. Note: tags are not case-sensitive. This method does not provide parameters for sorting the result set.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
and_tags List Limit the results to those that contain all of these tags.
or_tags List Limit the results to those that contain at least one of these tags.
page_size (optional) Integer Number of items returned per page. A page is a subset of all of the items that satisfy the request. The maximum page size is 100; if you do not set this argument, or if you set it to an integer > 100, your results will come back as if you had set page_size=100.
page_number (optional) Integer The zero-indexed number of the page to return.
sort_by (optional) SortByType The field by which to sort the results. Results can be sorted by any SortByType(CREATION_DATE, PUBLISHED_DATE, MODIFIED_DATE, PLAYS_TOTAL, and PLAYS_TRAILING_WEEK).
sort_order (optional) SortOrderType How to order the results: ascending (ASC) or descending (DESC).
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of videos whose tags match the tags specified.

Usage

Get videos that have either of the tags Apes or Monkeys: //api.brightcove.com/services/library?command=find_videos_by_tags&or_tags=Apes,Monkeys&token=[token] Get the names of videos that have all of the tags Mountain, Lion, and Attack: //api.brightcove.com/services/library?command=find_videos_by_tags&and_tags=Mountain,Lion,Attack&video_fields=name&token=[token] Get videos that have both of the tags Killer and Shark along and also have one of the tags Attack or Hugs, sorted by popularity: //api.brightcove.com/services/library?command=find_videos_by_tags&and_tags=Killer,Shark&or_tags=Attack,Hug&sort_by=plays_total&sort_order=DESC&token=[token]

Examples

For more examples of the find_videos_by_tags method:

find_video_by_id_unfiltered(token:String, video_id:long, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum): Video

Finds a single video with the specified ID. Unlike find_video_by_id, this unfiltered version also returns videos that are unscheduled, inactive, or deleted. See Searching for Unavailable Videos with the Media API for more information about the find_video_by_id_unfiltered method.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
video_id long TheID of the video you want to retrieve.
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.

Returns

type description
Video The Video you requested, with the specified fields populated, or null, if there is no video with that ID.

Usage

Get the video with the specified ID: //api.brightcove.com/services/library?command=find_video_by_id_unfiltered&video_id=123&token=[token] Get the long description of the video with a given ID: //api.brightcove.com/services/library?command=find_video_by_id_unfiltered&video_id=123&video_fields=longDescription&token=[token]

Examples

An example of the find_video_by_id_unfiltered method:

find_videos_by_ids_unfiltered(token:String, video_ids:List, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum): ItemCollection

Find multiple videos, given their IDs. Unlike find_videos_by_ids, this unfiltered version also returns videos that are unscheduled, inactive, or deleted. See Searching for Unavailable Videos with the Media API for more information about the find_videos_by_id_unfiltered method.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
video_ids List The list of video IDs for the videos we want to retrieve.
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTPURL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.

Returns

type description
ItemCollection an ItemCollection that contains the video objects corresponding to the video IDs given.

Usage

Get the names & tags of the videos with the specified IDs: //api.brightcove.com/services/library?command=find_videos_by_ids_unfiltered&video_ids=123,456,789&video_fields=name,tags&token=[token] Get the URLs of videos related to the videos with specified IDs: //api.brightcove.com/services/library?command=find_videos_by_ids_unfiltered&video_ids=123,456&video_fields=linkURL&token=[token]

Examples

An example of the find_videos_by_ids method:

find_video_by_reference_id_unfiltered(token:String, reference_id:String, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum): Video

Find a video based on its publisher-assigned reference ID. Unlike find_video_by_reference_id, this unfiltered version also returns videos that are unscheduled, inactive, or deleted. See Searching for Unavailable Videos with the Media API for more information about the find_video_by_reference_id_unfiltered method.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
reference_id String The publisher-assigned reference ID for the video we're searching for.
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id,name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength,videoFullLength. Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.

Returns

type description
Video The video whose reference ID matches the one given.

Usage

Get the total number of plays for the video with this reference ID: //api.brightcove.com/services/library?command=find_video_by_reference_id_unfiltered&video_fields=playsTotal&reference_id=123&token=[token]

Examples

An example of the find_video_by_reference_id method:

find_videos_by_reference_ids_unfiltered(token:String, reference_ids:List, fields:Set, video_fields:EnumSet, custom_fields:Set, media_delivery:Enum): ItemCollection

Find multiple videos based on their publisher-assigned reference IDs. Unlike find_videos_by_reference_ids, this unfiltered version also returns videos that are unscheduled, inactive, or deleted. See Searching for Unavailable Videos with the Media API for more information about the find_videos_by_reference_ids_unfiltered method.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
reference_ids List The list of reference IDs for the videos we'd like to retrieve. This value is limited to 150 characters. The value cannot contain commas; to work around this issue, avoid using commas in reference_id values.
fields (optional)
(deprecated)
Set Note: this parameter is deprecated in favor of the video_fields parameter. A comma-separated list of the fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). Note: in order to return the IOSRenditions, cuePoints, or captioningyou mustspecify those field explicitly - they are not included in the default fields. See the full list of fields for additional values.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.

Returns

type description
ItemCollection The collection of videos specified by the reference IDs provided.

Usage

Get the video IDs of the videos with these reference IDs: //api.brightcove.com/services/library?command=find_videos_by_reference_ids_unfiltered&reference_ids=123,456,789&video_fields=id&token=[token]

Playlist Read APIs

Methods for getting playlists from a publisher's media library using HTTP calls.

Methods

find_all_playlists(token:String, page_size:Integer, page_number:Integer, sort_by: SortByType, sort_order: SortOrderType, get_item_count:Boolean, fields:Set, video_fields:EnumSet, playlist_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Find all playlists in this account.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
page_size (optional) Integer Number of playlists returned per page. A page is a subset of all of the playlists that satisfy the request. The maximum page size is 50; if you do not set this argument, or if you set it to an integer > 50, your results will come back as if you had set page_size=50.
page_number (optional) Integer The zero-indexed number of the page to return.
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this is deprecated in favor of video_fields and playlist_fields. A comma-separated list of the fields you wish to have populated in the playlists or videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
playlist_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Playlists contained in the returned object. If you omit this parameter, all playlist fields are returned. If you specify any values for playlist_fields, you must include videos as one of the playlist_fields values in order to return any values specified by video_fields.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of Playlists that is the specified subset of all the playlists in this account.

Usage

Get the name and ID of all playlists, oldest first. The total number of playlists is also returned. //api.brightcove.com/services/library?command=find_all_playlists&playlist_fields=name,id&sort_by=publish_date&sort_order=ASC&get_item_count=true&token=[token] Get the names, IDs, and short descriptions of the 5 newest playlists //api.brightcove.com/services/library?command=find_all_playlists&sort_by=publish_date&sort_order=DESC&playlist_fields=id,name,shortDescription&page_size=5&token=[token]

Examples

For more examples of the find_all_playlists method:

find_playlist_by_id(token:String, playlist_id:long, fields:Set, video_fields:EnumSet, playlist_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): Playlist

Finds a particular playlist based on its ID.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
playlist_id long The ID of the playlist requested.
fields (optional)
(deprecated)
Set Note: this is deprecated in favor of video_fields and playlist_fields. A comma-separated list of the fields you wish to have populated in the playlists or videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
playlist_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Playlists contained in the returned object. If you omit this parameter, all playlist fields are returned. If you specify any values for playlist_fields, you must include videos as one of the playlist_fields values in order to return any values specified by video_fields.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
Playlist The playlist requested, or null, if there is no playlist with that ID.

Usage

Get the name and short description of a playlist: //api.brightcove.com/services/library?command=find_playlist_by_id&playlist_id=123&playlist_fields=name,shortDescription&token=[token] Get the playlist IDs and Video IDs of the videos in the specified playlist: //api.brightcove.com/services/library?command=find_playlist_by_id&playlist_id=123&playlist_fields=videos,videoIds&token=[token]

Examples

For more examples of the find_playlist_by_id method:

find_playlists_by_ids(token:String, playlist_ids:List, fields:Set, video_fields:EnumSet, playlist_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Retrieve a set of playlists based on their IDs.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
playlist_ids List The IDs of the playlists you would like retrieved.
fields (optional)
(deprecated)
Set Note: this is deprecated in favor of video_fields and playlist_fields. A comma-separated list of the fields you wish to have populated in the playlists or videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
playlist_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Playlists contained in the returned object. If you omit this parameter, all playlist fields are returned. If you specify any values for playlist_fields, you must include videos as one of the playlist_fields values in order to return any values specified by video_fields.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection The specified playlists, in the order of the IDs you passed in. If no playlist exists for an ID, null is returned in its place.

Usage

Get the names of the specified playlists: //api.brightcove.com/services/library?command=find_playlists_by_ids&playlist_ids=123,456,789&playlist_fields=name&token=[token]

find_playlist_by_reference_id(token:String, reference_id:String, fields:Set, video_fields:EnumSet, playlist_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): Playlist

Retrieve a playlist based on its publisher-assigned reference ID.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
reference_id String The reference ID of the playlist we'd like to retrieve.
fields (optional)
(deprecated)
Set Note: this is deprecated in favor of video_fields and playlist_fields. A comma-separated list of the fields you wish to have populated in the playlists or videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
playlist_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Playlists contained in the returned object. If you omit this parameter, all playlist fields are returned. If you specify any values for playlist_fields, you must include videos as one of the playlist_fields values in order to return any values specified by video_fields.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
Playlist The playlist that has the given reference ID.

Usage

Get the ID of a playlist based on the reference ID: //api.brightcove.com/services/library?command=find_playlist_by_reference_id&reference_id=131&field=id&token=[token] Get the playlist ID, as well as the video ID and name from the reference ID: //api.brightcove.com/services/library?command=find_playlist_by_reference_id&reference_id=1414&playlist_fields=id,name,videoIds&token=[token]

find_playlists_by_reference_ids(token:String, reference_ids:List, fields:Set, video_fields:EnumSet, playlist_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Retrieve multiple playlists based on their publisher-assigned reference IDs.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
reference_ids List The reference IDs of the playlists we'd like to retrieve. Avoid using commas in your reference IDs.
fields (optional)
(deprecated)
Set Note: this is deprecated in favor of video_fields and playlist_fields. A comma-separated list of the fields you wish to have populated in the playlists or videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
playlist_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Playlists contained in the returned object. If you omit this parameter, all playlist fields are returned. If you specify any values for playlist_fields, you must include videos as one of the playlist_fields values in order to return any values specified by video_fields.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection A collection of the specified playlists, in the order of the reference IDs you passed in. If no playlist exists for a reference id, null is returned in its place.

Usage

Get the names, short descriptions, and thumbnail URLs of the specified playlists //api.brightcove.com/services/library?command=find_playlists_by_reference_ids&reference_ids=1414,1412,400&playlist_fields=name,shortDescription,thumbnailURL&token=[token]

find_playlists_for_player_id(token:String, player_id:long, page_size:Integer, page_number:Integer, get_item_count:Boolean, fields:Set, video_fields:EnumSet, playlist_fields:EnumSet, custom_fields:Set, media_delivery:Enum, output:Enum): ItemCollection

Given the ID of a player, returns all the playlists assigned to that player.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
player_id long The player ID whose playlists we want to return.
page_size (optional) Integer Number of playlists returned per page. A page is a subset of all of the playlists that satisfy the request. The maximum page size is 50; if you do not set this argument, or if you set it to an integer > 50, your results will come back as if you had set page_size=50.
page_number (optional) Integer The zero-indexed number of the page to return.
get_item_count (optional) Boolean If true, also return how many total results there are; Note: if you omit this argument or set it to false, the returned value will be -1.
fields (optional)
(deprecated)
Set Note: this is deprecated in favor of video_fields and playlist_fields. A comma-separated list of the fields you wish to have populated in the playlists or videos contained in the returned object. If you omit this parameter, the method returns the following fields of the Videos:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions).
video_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Videos contained in the returned object. If you omit this parameter, the method returns the following fields of the video:id, name, shortDescription, longDescription, creationDate, publishedDate , lastModifiedDate, linkURL, linkText, tags, videoStillURL, thumbnailURL, referenceId, length, economics, playsTotal, playsTrailingWeek. If you use a token with URL access, this method also returns FLVURL, HLSURL, renditions, IOSRenditions, dashManifestUrl, dashRenditions, FLVFullLength, videoFullLength, WVMRenditions (for Widevine renditions). See the full list of fields for additional values.
playlist_fields (optional) EnumSet A comma-separated list of the fields you wish to have populated in the Playlists contained in the returned object. If you omit this parameter, all playlist fields are returned. If you specify any values for playlist_fields, you must include videos as one of the playlist_fields values in order to return any values specified by video_fields.
custom_fields (optional) Set A comma-separated list of the custom fields you wish to have populated in the videos contained in the returned object. If you omit this parameter, no custom fields are returned, unless you include the value customFields in the video_fields parameter.
media_delivery (optional) Enum This is a MediaDeliveryTypeEnum with a value of http, http_ios or default. It is meaningful only if used together with the video_fields=FLVURL, videoFullLength, IOSRenditions, or renditions parameters. If universal delivery service is enabled for your account, set this optional parameter to http to return video by HTTP, rather than streaming. For Apple HTTP Live Streaming videos, set this optional parameter to http_ios to return the HTTP URL of the master index file as the videoFullLength parameter. For more information, see Delivering Videos with Apple HTTP Live Streaming.
output Enum The default output is JSON, but you can get the output in XML, using RSS or MRSS. Use the output argument with the read methods to specify the format of the output. Valid values of the output argument are: json the default), mrss RSS with Media RSS and Video Cloud extensions), and tm for distribution through TubeMogul OneLoad). See RSS Output from the Media API and Creating Feeds for TubeMogul OneLoad with the Media API for code examples.

Returns

type description
ItemCollection The collection of playlists requested.

Usage

Get the names, thumbnail URLs, and short descriptions of the first 3 playlists for the player ID: //api.brightcove.com/services/library?command=find_playlists_for_player_id&player_id=349&page_size=3&playlist_fields=name,shortDescription,thumbnailURL&token=[token] Get the first 5 playlists assigned to the player with this player ID, plus the total number of assigned playlists: //api.brightcove.com/services/library?command=find_playlists_for_player_id&player_id=52&page_size=5&get_item_count=true&token=[token]

Examples

For more examples of the find_playlists_for_player_id method:

Video Write APIs

A set of APIs you can use to create, modify, or delete videos in your Media Library. Once a video is created using the Write APIs, it is fully accessible using the Read APIs and the Video Cloud Studio Media module.

Methods

create_video(token:String, video: Video, filename:String, maxsize:Long, file:InputStream, file_checksum:String, encode_to:String, create_multiple_renditions:Boolean, h264_no_processing:Boolean, preserve_source_rendition:Boolean):Long

Use this method to create a single video in your Video Cloud Media Library. You can either upload a new video file, or use the remote assets approach, in which you pass a reference to a video file on your own CDN. For information about remote assets, see Creating Videos with Remote Assets Using the Media API.

Note: When you are uploading a file, the JSON request body must come before the file part in the request, or the request will fail.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
video Video The metadata for the video you want to create. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Video object.
filename (optional) String The name of the file that is being uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
maxsize (optional) Long The maximum size that the file will be. This is used as a limiter to know when something has gone wrong with the upload. The maxsize is same as the size of the file you uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
file InputStream An input stream associated with the video file you're uploading. This takes the form of a file part, in a multipart/form-data HTTP request. This input stream and the filename and maxsize parameters are automatically inferred from that file part.
file_checksum (optional) String An optional MD5 hash of the file. The checksum can be used to verify that the file checked into your Video Cloud Media Library is the same as the file you uploaded. Checksums should use lowercase letters, not uppercase letters.
encode_to (optional) FLV or MP4 If the file requires transcoding, use this parameter to specify the target encoding. Valid values are MP4 or FLV, representing the H264 and VP6 codecs respectively. Note: transcoding of FLV files to another codec is not currently supported. This parameter is optional and defaults to FLV.
create_multiple_renditions (optional) Boolean If the file is a supported transcodable type, this optional flag can be used to control the number of transcoded renditions. If true, multiple renditions at varying encoding rates and dimensions are created. Setting this to false will cause a single transcoded rendition to be created at the standard encoding rate and dimensions. The default value is false.
preserve_source_rendition (optional) Boolean If the video file is H.264 encoded and if create_multiple_renditions=true, then multiple renditions are created and in addition the H.264 source is retained as an additional rendition.
h264_no_processing (optional) Boolean Use this option to prevent H.264 source files from being transcoded. This parameter cannot be used in combination with create_multiple_renditions. It is optional and defaults to false.

Returns

type description
Long The ID of the video that's been created.

Examples

For more examples of the create_video method:

add_captioning(token:String, caption_source:CaptionSource, filename:String, maxsize:Long, file:InputStream, file_checksum:String, video_id:Long, video_reference_id:String):Captioning

Assigns Captioning to a video via uploading a caption file or providing URL of caption file. Deletes any Captioning previously assigned to a video.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
caption_source The metadata for the CaptionSource you want to create. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Video object.
filename (optional) String The name of the file that is being uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
maxsize (optional) Long The maximum size that the file will be. This is used as a limiter to know when something has gone wrong with the upload. The maxsize is same as the size of the file you uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
file (optional) InputStream An input stream associated with the video file you're uploading. This takes the form of a file part, in a multipart/form-data HTTP request. This input stream and the filename and maxsize parameters are automatically inferred from that file part.
file_checksum (optional) String An optional MD5 hash of the file. The checksum can be used to verify that the file checked into your Video Cloud Media Library is the same as the file you uploaded. Checksums should use lowercase letters, not uppercase letters.
video_id Long The ID of the video to delete Captioning from. You must specify either video_id or video_reference_id.
video_reference_id String The publisher-generated reference ID of the video to delete the Captioning from. You must specify either video_id or video_reference_id.

Returns

type description
Captioning Metadata for Captioning of the Video

Throws

type description
RequiredParameterException token not provided, or either video_id or video_reference_id not provided
InvalidAPITokenException invalid token or not in publisher whitelist
IllegalValueException video_id or video_reference_id not found

delete_captioning(token:String, video_id:Long, video_reference_id:String):void

Deletes any Captioning previously assigned to a video.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
video_id Long The ID of the video to delete Captioning from. You must specify either video_id or video_reference_id.
video_reference_id String The publisher-generated reference ID of the video to delete the Captioning from. You must specify either video_id or video_reference_id.

Returns

type description
void successful delete

Throws

type description
RequiredParameterException token not provided, or either video_id or video_reference_id not provided
InvalidAPITokenException invalid token or not in publisher whitelist
IllegalValueException video_id or video_reference_id not found

update_video(token:String, video: Video)

Use this method to modify the metadata for a single video in your Video Cloud Media Library.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
video Video The metadata for the video you want to update. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Video object.

Returns

type description
Video

Examples

For more examples of the update_video method:

delete_video(token:String, video_id:Long, reference_id:String, cascade:Boolean, delete_shares:Boolean):void

Deletes a video.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
video_id (optional) Long The ID of the video you want to delete. You must specify either a video_id or a reference_id.
reference_id (optional) String The publisher-assigned reference ID of the video you want to delete. You must specify either a video_id or a reference_id.
cascade (optional) Boolean Set this to true if you want to delete this video even if it is part of a manual playlist or assigned to a player. The video will be removed from all playlists and players in which it appears, then deleted.
delete_shares (optional) Boolean Set this to true if you want also to delete shared copies of this video. Note: this will delete all shared copies from your account, as well as from all accounts with which the video has been shared, regardless of whether or not those accounts are currently using the video in playlists or players.

Returns

type description
void

Examples

For more examples of the delete_video method:

get_upload_status(token:String, video_id:Long, reference_id:String): UploadStatusEnum

Call this function in an HTTP POST request to determine the status of an upload. Note: there is a brief delay from the moment you submit a create_video method call and the moment the transaction for that method call is complete. During that interval, a get_upload_status method call will return an error message saying, "Illegal value - Cannot find any video", because the video has not yet been assigned an ID and begun uploading. Also note that the status "Complete" will be returned as soon as one playable rendition has been created. "Complete" is not a reliable indicator that all renditions have been created.

Arguments

name type description
token String The Write API authentication token required to use this method.
video_id (optional) Long The ID of the video whose status you want to get. You must specify either a video_id or a reference_id.
reference_id (optional) String The publisher-assigned reference ID of the video whose status you want to get. You must specify either a video_id or a reference_id.

Returns

type description
UploadStatusEnum an UploadStatusEnum that specifies the current state of the upload.

Examples

For more examples of the get_upload_status method:

share_video(token:String, video_id:Long, auto_accept:Boolean, force_reshare:Boolean, sharee_account_ids:Long[]):Long

Shares the specified video with a list of sharee accounts. For more information, see Media Sharing with the Media API.

Arguments

name type description
token String The Write API authentication token required to use this method.
video_id Long The ID for video that will be shared.
auto_accept (optional) Boolean If the target account has the option enabled, setting this flag to true will bypass the approval process, causing the shared video to automatically appear in the target account's library. If the target account does not have the auto-approval option enabled, or this flag is unspecified or false, then the shared video will be queued up to be approved by the target account before appearing in their library.
force_reshare (optional) Boolean Setting force_reshare to true indicates that if the shared video already exists in the target account's library, it should be overwritten by the video in the sharer's account.
sharee_account_ids Long[] List of Account IDs to share video with.

Returns

type description
Long[] Array of new video IDs (one for each account ID).

Examples

For more examples of the share_video method:

unshare_video(token:String, video_id:Long, sharee_account_ids:Long[]):Long[]

Deletes the specified previously shared video from a list of sharee accounts. If a shared version of the specified video does not exist in a sharee account, no action is taken. For more information, see Media Sharing with the Media API.

Arguments

name type description
token String The Write API authentication token required to use this method.
video_id Long The ID for video that will be shared. The video be owned by the account making the call.
sharee_account_ids Long[] List of Account IDs from which to stop sharing the video.

Returns

type description
Long[] Array of sharee account IDs for accounts previously containing shared videos specifically removed by this method.

Limitations

Available only to publishers with Media API access and Media Sharing enabled. Presently, this includes Pro and Enterprise customers by default.

add_image(token:String, image: Image, filename:String, maxsize:Long, file:InputStream, file_checksum:String, video_id:Long, video_reference_id:String, resize:Boolean): Image

Add a new thumbnail or video still image to a video, or assign an existing image to another video.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
image Image The metadata for the image you want to create (or update). This takes the form of a JSON object of name/value pairs, each of which corresponds to a property of the Image object.
filename (optional) String The name of the file that's being uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
maxsize (optional) Long The maximum size that the file will be. This is used as a limiter to know when something has gone wrong with the upload. The maxsize is same as the size of the file you uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
file (optional) InputStream An input stream associated with the image file you're uploading. This takes the form of a file part, in a multipart/form-data HTTP request. This input stream and the filename and maxsize parameters are automatically inferred from that file part.
file_checksum (optional) String An optional MD5 hash of the file. The checksum can be used to verify that the file checked into your Video Cloud Media Library is the same as the file you uploaded.
video_id (optional) Long The ID of the video you want to assign an image to. You must specify either a video_id or a video_reference_id.
video_reference_id (optional) String The publisher-assigned reference ID of the video you want to assign an image to. You must specify either a video_id or a video_reference_id.
resize (optional) Boolean Set this to false if you don't want your image to be automatically resized to the default size for its type. By default images will be resized.

Returns

type description
Image

Examples

For more examples of the add_image method:

add_logo_overlay(token:String, logooverlay:LogoOverlay, filename:String, maxsize:Long, file:InputStream, file_checksum:String, video_id:Long, video_reference_id:String):LogoOverlay

Add a logo overlay image to a video. For code examples, see Adding Logo Overlays to Videos with the Media API.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
logooverlay LogoOverlay The metadata for the logo overlay you want to create (or update). This takes the form of a JSON object of name/value pairs, each of which corresponds to a property of the LogoOverlay object.
filename (optional) String The name of the file that's being uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
maxsize (optional) Long The maximum size that the file will be. This is used as a limiter to know when something has gone wrong with the upload. The maxsize is same as the file you uploaded. You don't need to specify this in the JSON if it is specified in the file part of the POST.
file (optional) InputStream An input stream associated with the image file you're uploading. This takes the form of a file part, in a multipart/form-data HTTP request. This input stream and the filename and maxsize parameters are automatically inferred from that file part.
file_checksum (optional) String An optional MD5 hash of the file. The checksum can be used to verify that the file checked into your Video Cloud Media Library is the same as the file you uploaded.
video_id (optional) Long The ID of the video you want to assign a logo overlay to. You must specify either a video_id or a video_reference_id.
video_reference_id (optional) String The publisher-assigned reference ID of the video you want to assign a logo overlay to. You must specify either a video_id or a video_reference_id.

Returns

type description
LogoOverlay

Examples

For more examples of the add_logo_overlay method:

remove_logo_overlay(token:String, video_id:Long, video_reference_id:String):void

Removes a logo overlay previously assigned to a video.

Arguments

name type description
token String The Write API authentication token required to use this method. A string, generally ending in . (dot).
video_id (optional) Long The ID of the video to remove the logo overlay from. You must specify either a video_id or a video_reference_id.
video_reference_id (optional) String The publisher-assigned reference ID of the video to remove the logo overlay from. You must specify either a video_id or a video_reference_id.

Returns

type description
void

Examples

For more examples of the remove_logo_overlay method:

Playlist Write APIs

Methods for creating, updating, and deleting playlists.

Methods

create_playlist(token:String, playlist: Playlist):Long

Creates a playlist. This method must be called using an HTTP POST request and JSON parameters. If the playlistType property in the Playlist object you submit is explicit, that means it's a manual playlist. If the playlistType property is not explicit, that means it's a smart playlist. For more details and examples, see Creating and Updating Playlists with the Media API.

Arguments

name type description
token String The write method authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
playlist Playlist The metadata for the playlist you want to create. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Playlist object. Populate the videoIds property of the playlist, not the videos property. Note: you must refer to videos in the playlist by their video ID, not their reference ID.

Returns

type description
Long The ID of the Playlist you created.

Examples

For an example of the create_playlist method:

update_playlist(token:String, playlist: Playlist): Playlist

Updates a playlist, specified by playlist ID or reference ID. Either a playlist ID or a reference ID must be supplied. If you are updating the value of the reference ID, then both the playlist ID and reference ID must be supplied. This method must be called using an HTTP POST request and JSON parameters. For more details and examples, see Creating and Updating Playlists with the Media API

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
playlist Playlist The metadata for the playlist you want to update. This takes the form of a JSON object of name/value pairs, each of which corresponds to a settable property of the Playlist object. Populate the videoIds property of the playlist, not the videos property. Note: you must refer to videos in the playlist by their video ID, not their reference ID.

Returns

type description
Playlist

Examples

For an example of the update_playlist method:

delete_playlist(token:String, playlist_id:Long, reference_id:String, cascade_options:CascadeOptionsEnum, cascade:Boolean):void

Deletes a playlist, specified by playlist ID or reference ID.

Arguments

name type description
token String The authentication token provided to authorize using the Media APIs. A string, generally ending in . (dot).
playlist_id (optional) Long The ID for the playlist to delete. Either a playlist ID or a reference ID must be supplied.
reference_id (optional) String The publisher-assigned reference ID of the playlist you want to delete. Either a playlist ID or a reference ID must be supplied.
cascade_options (optional)
(deprecated)
CascadeOptionsEnum This parameter is deprecated.
cascade (optional) Boolean Set this to true if you want to delete this playlist even if it is referenced by players. The playlist will be removed from all players in which it appears, then deleted.

Returns

type description
void

Examples

For an example of the delete_playlist method:

See also the Media Objects Reference and the Error Message Reference.

Media Objects

Below you will find details for the objects that are accessible using the Media API:

Note: Boolean data type values must be entered as true or false. You will find field size restrictions in the object definitions below.

Video

The Video object is an aggregate of metadata and asset information associated with a video. A Video has the following properties:

A strategy for finding the most suitable URL for iOS or where HLS renditions are preferred, is to request the HLSURL and FLVURL video fields with the media_delivery=http. Then, look at the response object. If the HLSURL is not blank, then use it. Otherwise, if the FLVURL ends in .m3u8, then use it. Otherwise, if the video is MP4, then use the FLVURL. If none of these apply, then choose another video.

Property name Type Read only? Description
name string no The title of the Video, limited to 255 characters. The name is a required property when you create a video.
id long yes A number that uniquely identifies this Video, assigned by Video Cloud when the Video is created.
referenceId string no A user-specified id that uniquely identifies the Video, limited to 150 characters. A referenceId can be used as a foreign-key to identify this video in another system. Note: that the find_videos_by_reference_ids method cannot handle a referenceId that contain commas, so you may want to avoid using commas in referenceId values. Reference IDs must always be unique. You can reuse a referenceId value only after removing it from the current video or deleting the video it is assigned to.
accountId long yes A number, assigned by Video Cloud, that uniquely identifies the account to which the Video belongs.
shortDescription string no A short description describing the Video, limited to 250 characters. The shortDescription is a required property when you create a video.
longDescription string no A longer description of this Video, limited to 5000 characters.
FLVURL string yes[1] The URL of the video file for this Video (the default URL). This property is the URL to one of the renditions of the video title. This property applies, no matter whether the video's encoding is FLV (VP6) or MP4 (H.264). See Accessing Video Content with the Media API. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
HLSURL string yes[1] The URL of the HLS master playlist if the video is not remote and null. This property will be non-null if and only if the length of the iosRenditions field is greater than zero. This means that the HLS renditions were generated when the video was transcoded by Video Cloud. HLS remote assets will not have an HLSURL or iosRenditions. Note: this property can be accessed with the Media API only with a URL read or write token. This property applies, no matter whether the video's encoding is FLV (VP6) or MP4 (H.264). See Accessing Video Content with the Media API. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
dashManifestUrl string yes[1] The location of the server manifest (.mpd); Typically the dashManifestUrl is all that is needed to begin playback. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
renditions array yes[1] An array of Renditions that represent the multi-bitrate streaming renditions available for this Video. A Video should have not more than 10 Renditions. Note: this property can be accessed with the Media API only with a URL read or write token. See Accessing Video Content with the Media API.
IOSRenditions array yes[1] An array of objects containing the properties of the HLS renditions for the video. To retrieve IOSRenditions, you must set media_delivery to http_ios.
HDSRenditions array yes[1] An array of HDSRendition objects for each of the HDS renditions for the Video
dashRenditions array yes[1] returns an array of RenditionAssetDTO objects containing data about each of the DASH renditions that are a part of the video
hdsManifestUrl string yes[1] URL for the manifest for the HDS renditions
WVMRenditions array yes[1] An array of rendition objects for each of the Widevine renditions for the Video
smoothRenditions array yes[1] An array of rendition objects for each of the smooth (PlayReady) renditions for the Video
smoothManifestUrl string yes[1] The URL for manifest for the smooth renditions
videoFullLength rendition yes[1] A single Rendition that represents the video file for the Video. This is the default rendition for the video. Note: this property can be accessed with the Media API only with a URL read or write token. See Accessing Video Content with the Media API.
digitalMaster object yes The digital master of this video.
creationDate date yes The date this Video was created, represented as the number of milliseconds since the UNIX epoch.
publishedDate date yes The date this Video was last made active, represented as the number of milliseconds since the UNIX epoch.
lastModifiedDate date yes The date this Video was last modified, represented as the number of milliseconds since the UNIX epoch.
version int yes Version is the number of times a video has been edited (by a user or internal processes).
itemState string no An ItemStateEnum. One of the values: ACTIVE, INACTIVE, DELETED or PENDING. You can set this property only to ACTIVE, INACTIVE, or PENDING; you cannot delete a video by setting its itemStateto DELETED. The value of PENDING indicates a shared video that has not been activated.
startDate date no The first date this Video is available to be played, represented as the number of milliseconds since the UNIX epoch.
endDate date no The last date this Video is available to be played, represented as the number of milliseconds since the UNIX epoch.
linkURL string no An optional URL to a related item, limited to 255 characters.
linkText string no The text displayed for the linkURL, limited to 255 characters.
tags array no An array of Strings representing the tags assigned to this Video. Each tag can be not more than 128 characters, and a video can have no more than 1200 tags.
videoStillURL string yes[1] The URL to the video still image associated with this Video. Video stills are 480x360 pixels. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
videoStill object yes An object containing the properties of the video still associated with the video.
thumbnailURL string yes[1] The URL to the thumbnail image associated with this Video. Thumbnails are 120x90 pixels. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
thumbnail object yes An object containing the properties of the thumbnail associated with the video.
logoOverlay object yes An object containing the properties of the logo overlay associated with the video.
length long yes The length of this video in milliseconds. For a live stream, the value will be -1.
customFields object no A map of names and values for custom fields set up for videos in your account. Here is more information and examples.
economics string no An EconomicsEnum. Either FREE or AD_SUPPORTED. AD_SUPPORTED means that ad requests are enabled for the Video.
adKeys string no A string representing the ad key/value pairs assigned to the video. Key/value pairs are formatted as key=value and are separated by ampersands (&). For example:
"adKeys": "category=sports&live=true"
geoRestricted boolean no True indicates that the video is geo-restricted.
geoFiltered boolean no True indicates that the video is geo-restricted.
geoFilteredCountries array no An array of the ISO-3166 two-letter codes of the countries to enforce geo-restriction rules on. Use lowercase for the country codes.
geoFilterExclude boolean no If true, the video can be viewed in all countries except those listed in geoFilteredCountries; if false, the video can be viewed only in the countries listed in geoFilteredCountries.
cuePoints array no An array of the CuePoints objects assigned to this Video.
captioning array no An object containing URLs for all captions files assigned to the video.
playsTotal int yes How many times the Video has been played since its creation.
playsTrailingWeek int yes How many times the Video has been played within the past seven days, exclusive of today. (Clculated based on UTC time)
sharedByExternalAcct boolean yes True if this video was shared from some other account.
sharedToExternalAcct boolean yes True if this video was shared into some other account.

Playlist

The Playlist object is a collection of Videos. A Playlist has the following properties:

Property name Type Read only? Description
id long yes A number that uniquely identifies the Playlist. This id is automatically assigned when the Playlist is created.
referenceId string no A user-specified id, limited to 150 characters, that uniquely identifies this Playlist. Note: the find_playlists_by_reference_ids method cannot handle referenceId s that contain commas, so you may want to avoid using commas in referenceId values.
accountId long yes A number that uniquely identifies the account to which this Playlist belongs, assigned by Video Cloud.
name string no The title of this Playlist, limited to 100 characters. The name is a required property when you create a playlist.
shortDescription string no A short description describing the Playlist, limited to 250 characters.
videoIds array no An array of the ids of the Videos that are encapsulated in the Playlist. This property is populated only for manual playlists, since smart playlists compile their list of videos at runtime.
videos array yes An array of the Video objects that are encapsulated in the Playlist.
playlistType string no

For a manual playlist, set this to EXPLICIT. For a smart playlist, indicate how to order the playlist by setting this to one of the following choices: OLDEST_TO_NEWEST (by activated date)
NEWEST_TO_OLDEST (by activated date)
START_DATE_OLDEST_TO_NEWEST
START_DATE_NEWEST_TO_OLDEST ALPHABETICAL (by video name)
PLAYS_TOTAL
PLAYS_TRAILING_WEEK

The playlistType is a required property when you create a playlist.

filterTags array no An array of the tags that apply to this smart playlist. For example:

"filterTags":["Sitka","ticks"]
tagInclusionRule string no For a smart playlist, defines whether the video must contain all or contain one or more of the values in filterTags. Use AND for "contains all" and OR for "contains one or more." Not available in Read API methods.
thumbnailURL string yes The URL of the thumbnail associated with this Playlist. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.

Rendition[2]

The Rendition object represents one of the multi-bitrate streaming renditions of a video with an MP4 or FLV container (see the iOS Rendition object for renditions with an M2TS container). A Video should have not more than 10 total rendition and iosrendition objects. For more information, see Using multi-bitrate streaming and Creating videos for multi-bitrate streaming.

Property name Type Read only? Description
displayName string yes[1] The name of the rendition dynamically created when you upload a video. You can view this name in the Video Files tab in Video Cloud.
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType string no Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
  • LIVE_STREAMING
  • DEFAULT
See the ControllerType enum for more values and information.
encodingRate int yes[1] The rendition's encoding rate, in bits per second. Note: This value can only be set for remote assets.
frameHeight int yes[1] The rendition's display height, in pixels. Note: This value can be set for remote assets.
frameWidth int yes[1] The rendition's display width, in pixels. Note: This value can be set for remote assets.
id long yes The rendition ID automatically generated by Video Cloud.
referenceid string no The rendition reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
remoteStreamName string no [Optional - required for streaming remote assets only] A stream name for Flash streaming appended to the value of the remoteUrl property.
size long yes[1] Required. The file size of the rendition, in bytes. Note: This value can be set for remote assets.
uploadTimestampMillis long yes The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string yes[1] The URL of the rendition file. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
videoCodec string no Required. Valid values are SORENSON, ON2, and H264.
videoContainer string no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values are FLV and MP4 (for M2TS renditions see the iOS Rendition Object). See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the video asset in milliseconds.

IOS Rendition[2]

The IOSRendition object represents one of the multi-bitrate streaming renditions of a video with container type M2TS, meaning an HLS stream playable on iOS devices. A Video should have not more than 10 total rendition and iosrendition objects. For more information, see Using multi-bitrate streaming and Creating videos for multi-bitrate streaming.

Property name Type Read only? Description
displayName string yes[1] The name of the rendition dynamically created when you upload a video. You can view this name in the Video Files tab in Video Cloud.
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType string no Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
  • LIVE_STREAMING
  • DEFAULT
See the ControllerType enum for more values and information.
encodingRate int yes[1] The rendition's encoding rate, in bits per second. Note: This value can be set for remote assets.
frameHeight int yes[1] The rendition's display height, in pixels. Note: This value can be set for remote assets.
frameWidth int yes[1] The rendition's display width, in pixels. Note: This value can be set for remote assets.
id long yes The rendition ID generated automatically by Video Cloud
referenceid string no The rendition reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
size long yes[1] Required. The file size of the rendition, in bytes. Note: This value can be set for remote assets.
uploadTimestampMillis long yes The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string no The url for the m3u8 stream. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
videoCodec string no Required. Valid value is H264.
videoContainer string no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values is M2TS. See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the video asset in milliseconds.

WVM Rendition[2]

The WVMRendition object represents a rendition object that is widevine protected.

Property name Type Read only? Description
displayName string yes[1] The name of the rendition dynamically created when you upload a video. You can view this name in the Video Files tab in Video Cloud.
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType string no Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
  • LIVE_STREAMING
  • DEFAULT
See the ControllerType enum for more values and information.
encodingRate int yes[1] The rendition's encoding rate, in bits per second. Note: This value can be set for remote assets.
frameHeight int yes[1] The rendition's display height, in pixels. Note: This value can be set for remote assets.
frameWidth int yes[1] The rendition's display width, in pixels. Note: This value can be set for remote assets.
id long yes The rendition ID automatically generated by Video Cloud.
referenceid string no The rendition reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
remoteStreamName string no [Optional - required for streaming remote assets only] A stream name for Flash streaming appended to the value of the remoteUrl property.
size long yes[1] Required. The file size of the rendition, in bytes. Note: This value can be set for remote assets.
uploadTimestampMillis long yes The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string no The url for the m3u8 stream. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
videoCodec string no Required. Valid value is H264.
videoContainer string no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values is M2TS. See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the video asset in milliseconds.

VideoFullLength[2]

The videoFullLength object represents the default rendition for your video.

The VideoFullLength object is replacing the deprecated FLVFullLength object, which will be kept around for existing applications.

Property name Type Read only? Description
displayName string yes[1] The name of the rendition dynamically created when you upload a video. You can view this name in the Video Files tab in Video Cloud.
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType string no Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
  • LIVE_STREAMING
  • DEFAULT
See the ControllerType enum for more values and information.
encodingRate int yes[1] The rendition's encoding rate, in bits per second. Note: This value can be set for remote assets.
frameHeight int yes[1] The rendition's display height, in pixels. Note: This value can be set for remote assets.
frameWidth int yes[1] The rendition's display width, in pixels. Note: This value can be set for remote assets.
id long yes The rendition ID automatically generated by Video Cloud.
referenceid string no The rendition reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
remoteStreamName string no [Optional - required for streaming remote assets only] A stream name for Flash streaming appended to the value of the remoteUrl property.
size long yes[1] Required. The file size of the rendition, in bytes. Note: This value can be set for remote assets.
uploadTimestampMillis long yes The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string yes[1] The URL of the rendition file. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
videoCodec string no Required. Valid values are SORENSON, ON2, and H264.
videoContainer string no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values are FLV and MP4 (for M2TS renditions see the iOS Rendition Object). See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the video asset in milliseconds.

FLVFullLength (deprecated)[2]

The FLVFullLength object represents a rendition that is equal to the VideoFullLength object.

The VideoFullLength object is replacing the deprecated FLVFullLength object, which will be kept around for existing applications.

Property name Type Read only? Description
displayName string yes The name of the rendition dynamically created when you upload a video. You can view this name in the Video Files tab in Video Cloud.
audioOnly boolean no If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType string no Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
  • LIVE_STREAMING
  • DEFAULT
See the ControllerType enum for more values and information.
displayName string no The name of the asset, which will be displayed in the Media module.
encodingRate int yes The rendition's encoding rate, in bits per second. Note: This value can be set for remote assets.
frameHeight int yes The rendition's display height, in pixels. Note: This value can be set for remote assets.
frameWidth int yes The rendition's display width, in pixels. Note: This value can be set for remote assets.
id long yes The rendition ID automatically generated by Video Cloud.
referenceid string no The rendition reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension. If the file is served using Flash streaming, use the remoteStreamName attribute to provide the stream name.
remoteStreamName string no [Optional - required for streaming remote assets only] A stream name for Flash streaming appended to the value of the remoteUrl property.
size long yes Required. The file size of the rendition, in bytes. Note: This value can be set for remote assets.
uploadTimestampMillis long yes The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
url string yes The URL of the rendition file. Note: For ingested assets, URLs are subject to change without notice. Do not hard-code them into your applications, but rather use the Media API to pull them dynamically. For remote assets, Brightcove will not change the URLs.
videoCodec string no Required. Valid values are SORENSON, ON2, and H264.
videoContainer string no The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values are FLV and MP4 (for M2TS renditions see the iOS Rendition Object). See Supported Video Codecs and Containers for more information.
videoDuration long no Required. The length of the video asset in milliseconds.

DigitalMaster[2]

The DigitalMaster object represents a special rendition that will not have urls. This is the source file that was uploaded and is read-only.

Property name Type Read only? Description
displayName string yes The name of the rendition dynamically created when you upload a video. You can view this name in the Video Files tab in Video Cloud.
audioOnly boolean yes If true, this rendition is audio-only and has no video content. Audio-only renditions can be used for mobile streaming over low-bandwidth connections. It is recommended that videos in iOS applications should include a 64 kbps audio-only rendition.
controllerType string yes Depending on your CDN, one of the following values:
  • AKAMAI_STREAMING
  • AKAMAI_SECURE_STREAMING
  • AKAMAI_LIVE
  • AKAMAI_HD
  • AKAMAI_HD_LIVE
  • LIMELIGHT_LIVE
  • LIMELIGHT_MEDIAVAULT
  • LIVE_STREAMING
  • DEFAULT
See the ControllerType enum for more values and information.
encodingRate int yes The rendition's encoding rate, in bits per second. Note: This value can be set for remote assets.
frameHeight int yes The rendition's display height, in pixels. Note: This value can be set for remote assets.
frameWidth int yes The rendition's display width, in pixels. Note: This value can be set for remote assets.
id long yes The rendition ID automatically generated by Video Cloud.
referenceid string yes The rendition reference ID.
size long yes The file size of the rendition, in bytes. Note: This value can be set for remote assets.
uploadTimestampMillis long yes The date/time that the video was uploaded to Video Cloud, in Epoch milliseconds form.
videoCodec string yes Valid values are SORENSON, ON2, and H264.
videoContainer string yes The format of the wrapper that provides metadata and describes how the video and audio are stored in the file. Valid values are FLV and MP4 (for M2TS renditions see the iOS Rendition Object). See Supported Video Codecs and Containers for more information.
videoDuration long yes The length of the video asset in milliseconds.

Image

This object represents metadata about an image file in your account. Images are associated with videos as thumbnail images, video still images, or logo overlays. An image can be a JPEG, GIF, or PNG-formatted image. Note: when creating a new image asset, the only property that is required is type. If you are not uploading a file, the remoteUrl property is also required. For more information, see Adding Images to Videos with the Media API and Adding Logo Overlays to Videos with the Media API.

Property name Type Read only? Description
id long yes A number that uniquely identifies the Image. This id is automatically assigned by Video Cloud when the Image is created.
referenceId string no A user-specified id that uniquely identifies this Image.
type imageTypeEnum no THUMBNAIL, VIDEO_STILL, or LOGO_OVERLAY. The type is writable and required when you create an Image; it cannot subsequently be changed.
remoteUrl string no The URL of a remote image file. This property is required if you are not uploading a file for the image asset.
displayName string no The name of the asset, which will be displayed in the Media module.

Thumbnail

The Thumbnail object is an image asset and contains the size and dimension information for the thumbnail image.

Note: the Thumbnail, VideoStill, VideoPreBumper and VideoPreview objects contain the same properties. The type property value identifies the kind of data in the object.

Property name Type Read only? Description
name string no Required. A name for the cue point so that you can refer to it.
displayName string no The name of the asset, which will be displayed in the Media module.
id long yes The thumbnail ID.
referenceId string no The thumbnail reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension.
type string no THUMBNAIL

VideoStill

The VideoStill object is an image asset and contains the size and dimension information for the video still image.

Note: the Thumbnail, VideoStill, VideoPreBumper and VideoPreview objects contain the same properties. The type property value identifies the kind of data in the object.

Property name Type Read only? Description
name string no Required. A name for the cue point so that you can refer to it.
displayName string no The name of the asset, which will be displayed in the Media module.
id long yes The videoStill ID.
referenceId string no The videoStill reference ID.
remoteUrl string no Required, for remote assets. The complete path to the file hosted on the remote server. If the file is served using progressive download, then you must include the file name and extension for the file. You can also use a URL that re-directs to a URL that includes the file name and extension.
type string no VIDEO_STILL

CuePoint

The CuePoint object is a marker set at a precise time point in the duration of a video. You can use cue points to trigger mid-roll ads or to separate chapters or scenes in a long-form video. For more information, see Adding Cue Points to Videos and Setting CuePoints with the Media API.

Property name Type Read only? Description
name string no Required. A name for the cue point so that you can refer to it - returns null if none
id long yes A number that uniquely identifies this cue point object, assigned by VideoCloud when this object is created.
videoId int yes The id of the video that the cue point is set for.
time int no Required. The time of the cue point, measured in milliseconds from the beginning of the video.
forceStop boolean no If true, the video stops playback at the cue point. This setting is valid only for AD type cue points.
type int no Required. An integer code corresponding to the type of cue point: either 0 (= ad) or 1 (= code). An ad cue point is used to trigger mid-roll ad requests. A code cue point can be used to indicate a chapter or scene break in the video.
typeEnum string no The type of cue point, either AD or CODE
metadata string no A string that can be passed along with a CODE cue point. Not more than 512 characters.

LogoOverlay

The LogoOverlay object represents a logo overlay assigned to a video. The logo overlay is displayed over a portion of the video display for the entire duration of the video. For more information, see Creating Logo Overlays and Adding Logo Overlays to Videos with the Media API. You can also set a default logo overlay for your account. If you have a logo overlay set at the account level and also set a logo overlay for a video, the logo overlay set for the video will display and the account level logo overlay will not display.

Property name Type Read only? Description
id long yes A number that uniquely identifies the LogoOverlay. This id is automatically assigned by Video Cloud when the LogoOverlay is created.
image Image no An Image object, defined by its id or referenceId, with type=LOGO_OVERLAY.
tooltip string no Optional. A text that is displayed when the viewer mouses over the logo overlay.
linkURL string no Optional. A URL to go to if the viewer clicks on the logo overlay.
alignment string no Optional. A LogoOverlayAlignmentEnum representing the orientation of the logo overlay relative to the video display. One of the following values: TOP_LEFT, BOTTOM_LEFT, TOP_RIGHT, or BOTTOM_RIGHT. The default is BOTTOM_RIGHT.

CaptionSource

A source that provides captions for a video.

Property name Type Read only? Description
complete boolean yes A Boolean indicating whether a CaptionSource is usable.
displayName string no The name of the caption source, which will be displayed in the Media module.
id long yes A number that uniquely identifies this CaptionSource object, assigned by Video Cloud when this object is created.
isRemote boolean yes A Boolean indicating whether or not this CaptionSource is hosted on a remote server, as opposed to hosted by Brightcove.
url string no The complete path to the file.

Captioning

The Captioning object represents all closed captioning files and metadata assigned to a video.

Property name Type Read only? Description
id long yes A number that uniquely identifies this Captioning object, assigned by VideoCloud when this object is created.
caption_sources set no A set of sources which provide caption. Only one CaptionSource is supported at this time.

ItemCollection

A collection of paged items. This class encapsulates a list of an item of a certain type, and also stores paging information.

Property name Type Read only? Description
total_count long yes The total number of videos in the collection.
items list yes The actual items that this collection contains.
page_number int yes Which page of the results this ItemCollection represents.
page_size int yes How many items a page consists of.

Notes

  • [1] This property is WRITABLE for remote assets only; for videos you upload to Video Cloud, it is READ-ONLY.
  • [2] The Rendition, IOSRendition, WVMRendition, videoFullLength, FLVFullLength, VideoPreBumper and DigitalMaster objects contain the same properties. The videoContainer and videoCodec property values identify the kind of data in the object.

Enum Types

Below you will find details for variables that have predefined constants:

Note: ENUMS are predefined constants that are used in practice as string values (ex: playlistType = "EXPLICIT").

ControllerType

The value of the controllerType field in the Rendition object can depend on how you are delivering content and what CDN you are using. Here are the possible values:

Name Type Access Description
AKAMAI_STREAMING Enum read-only Akamai CDN, not live, without TTL
AKAMAI_SECURE_STREAMING Enum read-only Akamai CDN, not live, with TTL
AKAMAI_SECURE_STREAMING_LIVE Enum read-only Akamai CDN, live, with TTL
AKAMAI_LIVE Enum read-only Akamai CDN, live, without DVR
AKAMAI_HD Enum read-only Akamai HD
AKAMAI_HD_LIVE Enum read-only Live with DVR (whether your account's main CDN is Akamai or not)
AKAMAI_HD2 Enum read-only Akamai HD2, not live
AKAMAI_HD2_LIVE Enum read-only Akamai HD2, live
LIMELIGHT_LIVE Enum read-only Limelight CDN, live
LIMELIGHT_MEDIAVAULT Enum read-only Limelight CDN, using Limelight's Media Vault service option
LIVE_STREAMING Enum read-only CDNs other than Akamai or LimeLight
TELEFONICA_STREAMING Enum read-only Telefonica CDN, not live, without TTL
TELEFONICA_REMOTE Enum read-only Telefonica CDN
TELEFONICA_PD Enum read-only Telefonica CDN, progressive download
DEFAULT Enum read-only Uses the default process to load and play the content in the rendition

Economics

Name Type Access Description
FREE Enum read-only Ads are not enabled for this object.
AD_SUPPORTED Enum read-only Ads are enabled for this object.

ItemState

Name Type Access
ACTIVE Enum read-only
INACTIVE Enum read-only
PENDING Enum read-only
DELETED Enum read-only

ImageType

Name Type Access Description
VIDEO_STILL Enum read-only a video still
SYNDICATION_STILL Enum read-only
THUMBNAIL Enum read-only a thumbnail image
BACKGROUND Enum read-only a background image
LOGO Enum read-only
LOGO_OVERLAY Enum read-only a logo overlay

LogoOverlayAlignment

Name Type Access
TOP_RIGHT Enum read-only
TOP_LEFT Enum read-only
BOTTOM_RIGHT (default) Enum read-only
BOTTOM_LEFT Enum read-only

MediaDelivery

Name Type Description
default Enum Return video by default delivery mechanism for the account, either progressive download or streaming.
http Enum If universal delivery service is enabled for your account, return video by HTTP, rather than streaming.
http_ios Enum Return the HTTP URL of the master index file of a Apple HTTP Live Streaming rendition. For more information, see Delivering Videos with Apple HTTP Live Streaming.

PlaylistType

The type of playlist.

Name Type Access Description
EXPLICIT Enum read-only A manual playlist, the videos of which were added individually.
OLDEST_TO_NEWEST Enum read-only A smart playlist, ordered from oldest to newest, by activated date.
NEWEST_TO_OLDEST Enum read-only A smart playlist, ordered from newest to oldest, by activated date.
ALPHABETICAL Enum read-only A smart playlist, ordered alphabetically.
PLAYS_TOTAL Enum read-only A smart playlist, ordered by total plays.
PLAYS_TRAILING_WEEK Enum read-only A smart playlist, ordered by most plays in the past week.

PublicPlaylist.Fields

An enum iterating all the fields of this Playlist object, for efficient specification of what fields you want populated.

Name Type Access
id Enum read-only
referenceId Enum read-only
name Enum read-only
shortDescription Enum read-only
videoIds Enum read-only
videos Enum read-only
thumbnailURL Enum read-only
filterTags Enum read-only
playlistType Enum read-only
accountId Enum read-only

PublicVideo.Fields

An enum iterating all the fields of this object, for efficient specification of what fields you want populated.
(must only be separated by commas, no spaces)

Name Type Access
id Enum read-only
name Enum read-only
shortDescription Enum read-only
longDescription Enum read-only
creationDate Enum read-only
publishedDate Enum read-only
lastModifiedDate Enum read-only
startDate Enum read-only
endDate Enum read-only
captioning Enum read-only
linkURL Enum read-only
linkText Enum read-only
tags Enum read-only
videoStillURL Enum read-only
thumbnailURL Enum read-only
referenceId Enum read-only
length Enum read-only
economics Enum read-only
itemState Enum read-only
playsTotal Enum read-only NOTE: this data is derived from the Analytics API, but it is not real-time data. The value returned by the Media API is updated daily and reflects daily data.
playsTrailingWeek Enum read-only NOTE: this data is derived from the Analytics API, but it is not real-time data. The value returned by the Media API is updated daily and reflects daily data.
version Enum read-only
cuePoints Enum read-only
submissionInfo Enum read-only
customFields Enum read-only
releaseDate Enum read-only
FLVURL Enum read-only
HLSURL Enum read-only
iOSRenditions Enum read-only
renditions Enum read-only
WVMRenditions Enum read-only
geoFiltered Enum read-only
geoRestricted Enum read-only
geoFilterExclude Enum read-only
excludeListedCountries Enum read-only
geoFilteredCountries Enum read-only
allowedCountries Enum read-only
accountID Enum read-only
FLVFullLength Enum read-only
videoFullLength Enum read-only

SortByType

Ways that entities within the returned set can be ordered. Note: this does not apply to the search_videos method; it is used in the find_all_videos, find_videos_by_user_id, find_videos_by_campaign_id, find_modified_videos, find_videos_by_tags, and find_all_playlists methods.

Name Type Access Description
DISPLAY_NAME
(video only)
Enum read-only Name of the title.
REFERENCE_ID
(video only)
Enum read-only Reference ID of the title.
PLAYS_TOTAL
(video only)
Enum read-only Number of times this title has been viewed. NOTE: this data is derived from the Analytics API, but it is not real-time data. The value returned by the Media API is updated daily and reflects daily data.
PLAYS_TRAILING_WEEK
(video only)
Enum read-only Number of times this title has been viewed in the past 7 days (excluding today)
START_DATE
(video only)
Enum read-only Date title is scheduled to be available.
PUBLISH_DATE Enum read-only Date title was published.
CREATION_DATE Enum read-only Date title was created.
MODIFIED_DATE Enum read-only Date title was last modified.

SortOrderType

Directions that entities within the return set can be ordered.

Name Type Access Description
ASC Enum read-only Ascending
DESC Enum read-only Descending

UploadStatus

Note: there is a brief delay from the moment you submit a create_video method call and the moment the transaction for that method call is complete. During that interval, a get_upload_status method call will return an error message saying, "Illegal value - Cannot find any video", because the video has not yet been assigned an ID and begun uploading.

Name Type Access Description
UPLOADING Enum read-only File is still uploading.
PROCESSING Enum read-only Upload complete; being processed.
COMPLETE Enum read-only Upload and processing complete.
ERROR Enum read-only Error in upload or processing.

VideoCodec

Name Type Access
UNDEFINED Enum read-only
NONE Enum read-only
SORENSON Enum read-only
ON2 Enum read-only
H264 Enum read-only

VideoType

Name Type Access Description
FLV_PREVIEW Enum read-only A brief preview video.
FLV_FULL Enum read-only A full-length video.
FLV_BUMPER Enum read-only A video bumper.
DIGITAL_MASTER Enum read-only A master rendition.