Customer Sign In

upLynk

Integration APIs: Asset

Overview

The asset APIs can be used for basic information retrieval about assets in your upLynk account and to modify those assets.

/api2/asset/get

Retrieves a specific asset from your library.

Request parameters
idstring(optional*) the asset's ID
external_idstring(optional*) the asset's external ID
idslist(optional*) a list of assets' IDs to be returned as a list of assets
external_idslist(optional*) a list of assets' external IDs to be returned as a list of assets

* One of id, external_id, ids, external_ids must be specified.

Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
Call('/api2/asset/get', external_id='id1234')

{
    "asset": {
        "orig_filename": null,
        "rays": 8,
        "require_drm": 0,
        "slices": 22,
        "autoexpire": 0,
        "created": 1345730768265,
        "job_type": "vod",
        "libraries": [],
        "test_player_url": "http://content.uplynk.com/player/Hak3zjnPLSW5o0j8GMpzRMsa.html",
        "test_players": [
            {"desc": "Monitoring Test Player",
             "id": "Hak3zjnPLSW5o0j8GMpzRMsa",
             "url": "http://content.uplynk.com/player/Hak3zjnPLSW5o0j8GMpzRMsa.html"},
            {"desc": "Affiliate Test Player",
             "id": "3fqeYp0yrG5Pk4bDqazn79",
             "url": "http://content.uplynk.com/player/3fqeYp0yrG5Pk4bDqazn79sa.html"}],
        "state": "ready",
        "duration": 88.88598639455783,
        "embed_player_url": "http://content.uplynk.com/player/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
}
                

/api2/asset/update

Modifies an asset in your library.

Request parameters
idstring(optional*) the ID of the asset to modify
external_idstring(optional*) A new external_id for the asset. Note: if you retrieved the asset by external ID, you cannot also update the external ID at the same time.
descstring(optional) A description for the asset
test_player_urlany(optional) Specifying any value for this parameter will cause a new test player URL to be generated. Note that this does not expire any existing test players; it adds a new test player to the list of test players. To expire a test player please use the CMS web interface.
embed_player_urlany(optional) Specifying any value for this parameter will cause a new embed player URL to be generated.
require_drmint(optional) Specify a 1 to enable required tokens. Specify a 0 to disable required tokens.
metastring(optional) The metadata to set on the asset. This must be a dictionary in JSON format. If the asset has existing meta, any new meta will be merged. To clear all metadata, set to '{}'.
poster_imgstring(optional) The image to be used for this asset's poster image, as a base64-encoded string. Limited to images that are smaller than 3MB before base64 encoding. To reset the asset's poster image, set to the empty string ''.
autoexpirestring(optional) A timestamp in milliseconds after which the asset will be deleted automatically. Use a value of 0 to indicate that the asset should not auto-expire.

* Either id or external_id must be specified.

Response
(Same as for asset/get)
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
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,
        "slices": 22,
        "autoexpire": 0,
        "created": 1345730768265,
        "job_type": "vod",
        "libraries": [],
        "meta": {"key1":"value1",
                 "key2":"value2"},
        "test_player_url": "http://content.uplynk.com/player/Hak3zjnPLSW5o0j8GMpzRMsa.html",
        "test_players": [
            {"desc": "Monitoring Test Player",
             "id": "Hak3zjnPLSW5o0j8GMpzRMsa",
             "url": "http://content.uplynk.com/player/Hak3zjnPLSW5o0j8GMpzRMsa.html"},
            {"desc": "Affiliate Test Player",
             "id": "3fqeYp0yrG5Pk4bDqazn79",
             "url": "http://content.uplynk.com/player/3fqeYp0yrG5Pk4bDqazn79sa.html"}],
        "state": "ready",
        "duration": 88.88598639455783,
        "embed_player_url": "http://content.uplynk.dev:8000/player/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
}
				

Note that external ID's are opaque values to the upLynk system so it is up to you to use a convention that ensures uniqueness within your content library. If you assign the same external ID to multiple assets, the system will choose one arbitrarily when you try to access the asset by its external ID.

/api2/asset/list

Lists or searches for assets.

Request parameters
searchstring(optional) Text to search for in the asset's description, ID, or external ID.
limitinteger(optional) Cap the number of items returned, maximum of 100 items.
skipinteger(optional) Skip the first N results. The skip and limit parameters can be used together for paginated results.
orderstring(optional) Sort the results by the given field. Supported fields include: desc, created, lastmod, duration, state, and external_id. Prefix the sort field with a minus sign for descending order (e.g. order='-desc' to retrieve values in reverse alphabetical order)
Response parameters
assetslistA list of assets, where each matches the form returned by asset/get.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// grab the 3 most recently created assets that have the string "abc" in their description
// or external_id or asset ID
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
}

/api2/asset/delete

Deletes one or more assets from your library.

Request parameters
idslist(optional*) a list of IDs of assets to be deleted
external_idslist(optional*) a list of external IDs of assets to be deleted

* Either ids or external_ids must be specified, and both are allowed.

Response parameters
deletedlistA list of assets that were deleted. Each item in the list contains id and external_id members.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
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
}

/api2/asset/changes

Returns a list of changes that have been made to assets from a certain point in time onward. This API can be helpful in keeping another CMS syncrhonized with the upLynk CMS.

Because there can potentially be many changes, the system limits the number of changes returned to a few hundred. Included in the response is a time value that reflects the ending point in time of the response. This ending point can be used in a subsequent request as a new starting point from which to find changes.

Please see additional notes below.

Request parameters
startintThe starting point in time to look for changes. This value is in milliseconds since the epoch in UTC. The system will return changes at or after this point in time.
Response parameters
startintThe same start value that was used in the call.
endintThe ending point in time for the changes returned back. This value can be used as the starting point in a subsequent call.
changeslistA list of (timestamp of change, change type, asset ID). Timestamps are in milliseconds since the epoch. Changes are one of 'create', 'update', or 'delete'.
assetsobjectThe assets referenced in the change list; a mapping from asset ID to the asset's information as of the time of the call (not as of the time of any particular change in the past).
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
Call('/api2/asset/changes', start=1391714449648)

{
    "changes": [
        [
            1391796562910,
            "update",
            "1ca770087e7a46a7aec4f8aebc198aff"
        ],
        [
            1391796578879,
            "delete",
            "1ca770087e7a46a7aec4f8aebc198aff"
        ]
    ],
    "assets": {
        "1ca770087e7a46a7aec4f8aebc198aff": {
            "orig_filename": null,
            "rays": 7,
            "require_drm": 1,
            "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
}

Addtional notes: In order to avoid any gaps in the data returned, the system returns changes at or after the start point and at or before the returned end point. Thus, a subsequent call with that end point as the new start point will (correctly) include the last change from the previous call as the first change of the second call.

The system remembers asset deletions for up to 24 hours. If you are using this API to keep another CMS synchronized with activity in the upLynk CMS, it is important that you call this API at least once every 24 hours so that the other CMS is aware of any assets that were deleted from the upLynk CMS.

The information returned in the assets object represents the information in that asset at the time the API was called. For example, if an asset was created and then edited a few minutes later, a call to this API would return a change entry for when the asset was created and when it was updated, and the asset's information provided in the 'assets' section of the response would reflect the current state of that asset (the updated version and not the original version).

/api2/asset/getframe

Returns a base64 representation of the specified frame from the highest bitrate variant of the specified asset.

Request parameters
idintID of the asset from which to grab a frame
tsint /
string
Timestamp of the frame to grab. Specify in milliseconds as an integer, or as a string in the 'hh:mm:ss.ms' format
Response Params
imgstringBase64-encoded representation of the requested frame
Example Calls
1
2
3
4
5
6
7
Call('/api2/asset/getframe', id='5fa5c4bc8ff34261b7fbafba5b5e6347', ts=91415)         # 91.415 seconds
Call('/api2/asset/getframe', id='5fa5c4bc8ff34261b7fbafba5b5e6347', ts='01:31.415')   # 91.415 seconds

{
    'img': 'iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAIAAAB...'
}
                

/api2/asset/getthumbs

Return a list of base64 representations of the frames in the range from `start` to `stop` from the lowest bitrate variant of the asset. The time range specified by start-stop may not be greater than 1 second. If the optional `stop` parameter is omitted, will return a 1-second range, beginning at `start`.

Request parameters
idintRequired. ID of the asset from which to grab a a range of thumbnails.
startint /
string
Required. Timestamp of the start of the range. Specify as an integer, or as a string in the 'hh:mm:ss.ms' format
stopint /
string
(optional) Timestamp of the end of the range. If omitted, will default to start + 1 second. Same format as start.
Response Params
imgsstringA list of Base64-encoded representations of the requested frames
Example Calls
1
2
3
4
5
6
7
8
9
Call('/api2/asset/getthumbs', id='5fa5c4bc8ff34261b7fbafba5b5e6347', start=91415)      # 91.415 seconds
Call('/api2/asset/getthumbs', id='5fa5c4bc8ff34261b7fbafba5b5e6347', start='01:31.415')# 91.415 seconds

{
    'imgs': ['iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAIAAAB...',
             'iVBORw0KGgoAAAANSUhEUgAABQAAAALQCAIAAAB...',
             ...]
}
                

Generate an MP4 of an asset

To create an MP4 from one of your assets, please use the /api2/cloudslicer/jobs/create_export endpoint.