The Asset API contains the following endpoints:
| Endpoint | Description |
|---|---|
|
GET /api2/asset/delete
|
Deletes one or more assets from your library. |
|
GET /api2/asset/changes
|
Returns a list of changes that have been made to assets. |
|
GET /api2/asset/get
|
Retrieves one or more assets from your library. |
|
GET /api2/asset/list
|
Searches for assets. |
|
GET /api2/asset/getthumbs
|
Returns a Base64-encoded representation from the lowest bitrate variant of the asset for each frame within a time range. |
|
GET /api2/asset/getframe
|
Returns a Base64-encoded representation of the requested frame. |
|
GET /api2/asset/update
|
Modifies an asset in your library. |
Retrieves one or more assets from any of your libraries.
A maximum of 1000 assets may be retrieved per request.
An asset will only be reported a single time per request. Duplicate requests for the same asset are ignored.
Request syntax:
Request parameters:
Pass the following parameters through the msg parameter:
A valid request must identify one or more assets by including only one of the following request parameters.
| Request Parameter |
Type |
Description |
|---|---|---|
|
id |
String |
Specify a single asset by its asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab.. |
|
external_id |
String |
Specify a single asset by its external ID. |
|
ids |
List |
Specify one or more assets by their asset IDs. |
|
external_ids |
List |
Specify one or more assets by their external IDs. |
Sign the request with your API key.
The following sample request retrieves an asset whose external ID is id1234. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/get', external_id='id1234'))
{
"asset": {
"orig_filename": null,
"rays": 8,
"require_drm": 0,
"require_studio_drm": 0,
"slices": 22,
"autoexpire": 0,
'break_offsets': [{
'break_type': 'AD BREAK',
'duration': 19.202916666666667,
'offset': 17.024
}, {
'break_type': 'BOUNDARY',
'duration': 20.352,
'name': 'c4',
'offset': 24.96
}, {
'break_type': 'AD BREAK',
'duration': 29.953729166666665,
'offset': 55.424
}
],
"created": 1345730768265,
"job_type": "vod",
"libraries": [],
"test_player_url": "https://content.uplynk.com/player5/Hak3zjnPLSW5o0j8GMpzRMsa.html",
"test_players": [{
"desc": "Monitoring Test Player",
"id": "Hak3zjnPLSW5o0j8GMpzRMsa",
"url": "https://content.uplynk.com/player5/Hak3zjnPLSW5o0j8GMpzRMsa.html"
}, {
"desc": "Affiliate Test Player",
"id": "3fqeYp0yrG5Pk4bDqazn79",
"url": "https://content.uplynk.com/player5/3fqeYp0yrG5Pk4bDqazn79sa.html"
}
],
"state": "ready",
"duration": 88.88598639455783,
"embed_player_url": "https://content.uplynk.com/player5/2aZeCWBZd0FVXmU95BGKnjea.html",
"external_id": "id1234",
"id": "5915d84829405cb4db1bc3f71c10fc83",
"thumb_url": "http://storage.uplynk.com/slices/.../00000014.jpg",
"desc": "foux du fu fa fa",
"mp4_url": "http://storage.uplynk.com/slices/.../8e37519b10c8408d879d619760baaee0_g.mp4",
"ttml_url": "http://storage.uplynk.com/slices/.../8e37519b10c8408d879d619760baaee0_g.mp4.ttml"
},
"error": 0
}
Modifies an asset in your library.
Request syntax:
Request body parameters:
Pass the following parameters through the msg parameter:
A valid request must identify an asset by including either the id or external_id request parameter. Pass both of these parameters to assign an external ID to the asset.
| Request Parameter |
Type |
Description |
|---|---|---|
|
String |
Identifies an asset by its asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab.. |
|
|
String |
Assign an external ID to the asset identified by the id parameter. If the id parameter is omitted, then it identifies an asset by its external ID. If you are assigning an external ID to an asset, please make sure that it is a unique value. If multiple assets are assigned the same external ID, then an arbitrary one will be selected when accessing it via external ID. |
|
|
desc |
String |
Assigns a name to the asset. |
|
test_player_url |
Any |
Specify any value to generate a new test player URL. This parameter solely adds a new test player. Expire a test player via the CMS. |
|
embed_player_url |
Any |
Specify any value to generate a new embed player URL. |
|
require_drm |
Integer |
Determines whether playback requires a signed playback URL. Valid values are:
|
|
require_studio_drm |
Integer |
Determines whether Studio DRM will be enforced. Valid values are:
Once Studio DRM is activated on your account, Studio DRM encryption is automatically applied to all new assets. This parameter does not alter this behavior. |
|
meta |
Dictionary |
Adds and/or overwrites an asset's metadata. Specify a key-value pair for each desired field. Duplicate fields will be overwritten. Clear the asset's metadata by specifying an empty dictionary (i.e., {}). |
|
poster_img |
String |
Assigns a poster image to the asset. Specify a Base64-encoded string for an image that is smaller than 3MB before encoding. Reset the asset's poster image by setting this parameter to an empty string (i.e., ''). |
|
autoexpire |
String |
Defines a timestamp, in milliseconds, after which the asset will be deleted automatically. Set this parameter to 0 to indicate that the asset should not auto-expire. |
Sign the request with your API key.
Returns the same response as Get Asset(s) by ID.
The following sample request updates an asset whose asset ID is 5915d84829405cb4db1bc3f71c10fc83. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/update',
id='5915d84829405cb4db1bc3f71c10fc83',
test_player_url=1,
desc='New Desc',
meta='{"key1":"value1", "key2":"value2"}',
poster_img='iVBORw0KGgoAAAANSUhEUgAAAikAAAIoCAIAAAAjrezsAALE6ElEQVR42.....'))
{
"asset": {
"orig_filename": null,
"rays": 8,
"require_drm": 0,
"require_studio_drm": 0,
"slices": 22,
"autoexpire": 0,
"created": 1345730768265,
"job_type": "vod",
"libraries": [],
"meta": {"key1":"value1",
"key2":"value2"},
"test_player_url": "https://content.uplynk.com/player5/Hak3zjnPLSW5o0j8GMpzRMsa.html",
"test_players": [
{"desc": "Monitoring Test Player",
"id": "Hak3zjnPLSW5o0j8GMpzRMsa",
"url": "https://content.uplynk.com/player5/Hak3zjnPLSW5o0j8GMpzRMsa.html"},
{"desc": "Affiliate Test Player",
"id": "3fqeYp0yrG5Pk4bDqazn79",
"url": "https://content.uplynk.com/player5/3fqeYp0yrG5Pk4bDqazn79sa.html"}],
"state": "ready",
"duration": 88.88598639455783,
"embed_player_url": "https://content.uplynk.com/player5/2aZeCWBZd0FVXmU95BGKnjea.html",
"external_id": "foux",
"id": "5d84829405cb4db1bc3f71915c10fc83",
"thumb_url": "http://storage.uplynk.com/slices/.../00d4cfbe2c2b46fc92a2c818b9bd1f9b.jpg",
"desc": "New Desc",
"poster_url": 'http://storage.uplynk.com/slices/.../00d4cfbe2c2b46fc92a2c818b9bd1f9b.jpg"
},
"error": 0
}
Searches for your assets or assets shared with you.
Request syntax:
Request properties:
Pass the following parameters through the msg parameter:
| Property |
Type |
Description |
|---|---|---|
|
ignore_shared_libraries |
Boolean |
Set to true to exclude content from shared libraries. Excluding shared libraries improves performance. |
|
limit |
Integer |
Defines the maximum number of assets that may be included in the response. Specify a value from 1 to 100. Default value: 100
|
|
order |
String |
Sort your search results using the following syntax: Key information:
Examples: Sort search results from shortest to longest duration: order=duration
Sort search results from longest to shortest duration and then sort assets with the same duration by name in alphabetical order: order=-duration,desc
|
|
query |
String |
Search for assets whose name, asset ID, or external ID contains at least one of the specified keyword(s). Use search operators to define the scope of your search and special characters to fine-tune your search results. |
|
search Deprecated |
String |
This deprecated property will undergo end-of-life on 3/31/2023. Use the query property instead. Perform a substring search for assets by name, asset ID, or external ID. This value should be URL-encoded. |
|
skip |
Integer |
Defines the number of search results that will be skipped. Use the skip and limit parameters to generate paginated search results. |
Sign the request with your API key.
Response body parameters are described below.
| Response Parameter |
Type |
Description |
|---|---|---|
|
assets |
List |
Contains a list of your assets. Returns the same response as /asset/get. |
|
shared_assets |
List |
Contains a list of assets shared with your account. Returns the same response as /asset/get. |
The following sample request retrieves the three newest assets whose name, asset ID, and/or external ID contain abc. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/list', search='abc', order='-created', limit=3))
{
"assets": [
{
"created": 1315943723095,
"job_type": "vod",
"id": "635100d66a38436abcee5e9b0f4e04cd",
"desc": "test.mov",
...
},
{
"created": 1300723042924,
"id": "cf938111bbdf4138a8cbe5ec6d800d83",
"desc": "abc 1234 test",
...
},
{
"created": 1296079971683,
"id": "2a68df86e65f4e02acfd2d3e14c0edef",
"desc": "another ABCDEFG test",
...
}
],
"error": 0
}
Deletes one or more assets from your library.
Request syntax:
Request parameters:
Pass the following parameters through the msg parameter:
A valid request must identify one or more assets by including the ids and/or external_ids parameter(s).
| Request Parameter |
Type |
Description |
|---|---|---|
|
ids |
List |
Identifies one or more assets to be deleted by asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab.. |
|
external_ids |
List |
Identifies one or more assets to be deleted by external ID. |
Sign the request with your API key.
A response body parameter is described below.
| Response Parameter |
Type |
Description |
|---|---|---|
|
deleted |
List |
A list of assets that were deleted. Each item in the list contains id and external_id members. |
The following sample request deletes three assets identified by an asset ID and two external IDs. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/delete', ids=['0a671113bebb4192bf679db9ee146051'],
external_ids=['ad10115', 'challenge_s01e03']))
{
"deleted": [
{
"external_id": "clip7",
"id": "0a671113bebb4192bf679db9ee146051"
},
{
"external_id": "challenge_s01e03",
"id": "54e40044a5f84050a483a5ce91cedab1"
},
{
"external_id": "ad10115",
"id": "9c4e00aab263489aa7fd275a0c5cc478"
}
],
"error": 0
}
Returns a list of changes that have been made to assets from a certain point in time onward.
Key information:
The response includes changes that occur:
This means that a subsequent request will include the last change reported within the previous request.
Asset information provided in the response reflects the state of the asset when the endpoint was requested.
Example:
If an asset was created and updated within the requested time range, then both of those changes would be included in the response. However, the assets response parameter will only describe the latest version of the asset. This information will reflect any changes that may have been applied to the asset after the end of the requested time range.
Request syntax:
Request parameters:
Pass the following parameters through the msg parameter:
| Request Parameter |
Type |
Description |
|---|---|---|
|
start Required |
Integer |
Defines the starting point for which changes will be reported. Syntax: Unix time in milliseconds
|
Sign the request with your API key.
Response body parameters are described below.
| Response Parameter |
Type |
Description |
|---|---|---|
|
start |
Integer |
Indicates the value defined in the start request body parameter. |
|
end |
Integer |
Indicates the ending point for the changes included in the response. Use this value as the starting point for subsequent calls. |
|
changes |
List |
Describes each change within the above time period by:
|
|
assets |
Dictionary |
Contains information that describes the assets in the change list. Each item in this dictionary maps an asset ID to information about the asset as of the time at which this endpoint was requested. The information provided in this parameter is not specific to a change reported within the changes list. |
The following sample request retrieves changes to assets starting from 1391714449648 (Unix time in milliseconds). The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/changes', start=1391714449648))
{
"changes": [
[
1391796562910,
"update",
"1ca770087e7a46a7aec4f8aebc198aff"
],
[
1391796578879,
"delete",
"1ca770087e7a46a7aec4f8aebc198aff"
]
],
"assets": {
"1ca770087e7a46a7aec4f8aebc198aff": {
"orig_filename": null,
"rays": 7,
"require_drm": 1,
"require_studio_drm": 0,
"created": 1391104683934,
"deleted": 1391796578879,
"lastmod": 1391796562910,
"autoexpire": 0,
"slices": 10,
"job_type": "live",
"duration": 40.651999999999994,
"id": "1ca770087e7a46a7aec4f8aebc198aff",
"desc": "Live Capture",
...
}
},
"start": 1391714449648,
"end": 1391800857638,
"error": 0
}
Returns a Base64-encoded representation of the specified frame from the highest bitrate variant of the specified asset.
Request syntax:
Request parameters:
Pass the following parameters through the msg parameter:
| Request Parameter |
Type |
Description |
|---|---|---|
|
id Required |
Integer |
Identifies an asset by its asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab.. |
|
ts Required |
Integer | String |
Identifies a frame by its timestamp. Syntax (Integer): Milliseconds
Syntax (String): hh:mm:ss.ms
|
Sign the request with your API key.
A response body parameter is described below.
| Response Parameter |
Type |
Description |
|---|---|---|
|
img |
String |
The Base64-encoded representation of the requested frame. |
The following sample requests demonstrate the different syntax that may be used to retrieve the frame that can be found 91.415 seconds into the video. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/getframe', id='5fa5c4bc8ff34261b7fbafba5b5e6347', ts=91415)) # 91.415 seconds
print(Call('/api2/asset/getframe', id='5fa5c4bc8ff34261b7fbafba5b5e6347', ts='00:01:31.415')) # 91.415 seconds
{
'img': 'iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAIAAAB...'
}
Returns a Base64-encoded representation from the lowest bitrate variant of the asset for each frame within the time range defined by the start and stop parameters.
Request syntax:
Request parameters:
Pass the following parameters through the msg parameter:
A valid request must identify an asset by including either the id or external_id request parameter.
| Request Parameter |
Type |
Description |
|---|---|---|
|
id |
Integer |
Identifies an asset by its asset IDThis unique ID identifies an asset. View this ID by navigating to the Content tab, selecting the desired asset, and then viewing the GUID option from the Details tab.. |
|
external_id |
String |
Identifies an asset by its external ID. |
|
start Required |
Integer / String |
Identifies the start of the range. Syntax (Integer): Milliseconds
Syntax (String): hh:mm:ss.ms
|
|
stop |
Integer / String |
Identifies the end of the range. If omitted, it will default to start + 1 second. Do not specify a time range greater than 1 second. Syntax (Integer): Milliseconds
Syntax (String): hh:mm:ss.ms
|
Sign the request with your API key.
A response body parameter is described below.
| Response Parameter |
Type |
Description |
|---|---|---|
|
imgs |
String |
A list of Base64-encoded representations of the requested frames. |
The following sample requests demonstrate the different syntax that may be used to retrieve frames between 91.415 and 92.415 seconds into the video. The Call() function, which is imported from uplynk_api2_auth module, prepares the message body and digital signature.
from uplynk_api2_auth import Call
print(Call('/api2/asset/getthumbs', id='5fa5c4bc8ff34261b7fbafba5b5e6347', start=91415)) # 91.415 seconds
print(Call('/api2/asset/getthumbs', external_id='id1234', start='01:31.415')) # 91.415 seconds
{
'imgs': ['iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAIAAAB...',
'iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAIAAAB...',
...]
}
Please use the /api2/cloudslicer/jobs/create_export endpoint to generate a downloadable MP4 from an asset.