Customer Sign In

upLynk

Integration APIs: Cloud Slicer

Overview

The purpose of the Cloud Slicer is to slice and encode cloud content or to provide an alternative slicing method when it is not feasible or practical to run a slicer locally. Each requested slicing job is placed into a queue until a Cloud Slicer is available to work on it. At which point, the assigned Cloud Slicer downloads the media and then slices it for encoding.

Considerations when using the Cloud Slicer:

  • Cost: The use of the Cloud Slicer service incurs a cost in addition to the normal encoding rate.
  • Queue: Each requested slicing job is placed into a queue and is processed according to the order in which it was received. Although the pool of available Cloud Slicers is ramped up to meet demand, some jobs may be delayed to ensure fairness to other users.
  • Feedback: A local slicer provides immediate feedback when a job cannot be processed, while a Cloud Slicer will not provide feedback until after the job is processed.
  • File Size: The Cloud Slicer may only process files that are smaller than 90 GBs. Please use a local slicer for larger files.

The Cloud Slicer may be automated via an API. The methods through which it may be automated are described below.

API Methods

The Cloud Slicer Integration API supports the following methods:

MethodDescription
/jobs/createCreates a new cloud slicing job.
/jobs/getRetrieves the details of an existing cloud slicing job.
/jobs/listRetrieves a list of recent cloud slicing jobs.
/jobs/deleteDeletes queued and completed cloud slicing jobs.
/jobs/quickclipCreates a clip from an existing CMS asset.
/jobs/create_exportExports an asset.
/jobs/cancelCancels a cloud slicing job.
/jobs/copy-from-libraryCopies an asset from a shared library.
/batch/copy-from-libraryCopies one or more asset(s) from a shared library.
/batch/get-job-statesRetrieves the results for a copy-from-library request.

/cloudslicer/jobs/create

Creates a new cloud slicing job

Request ParametersTypeDescription
sourceObjectHolds information on how to obtain the media file. The source object must contain a 'url' key.

For files available over HTTP, the 'url' key is the only one required in the source object, e.g. {'source':{'url:'http://myserver.com/path/to/myfile.mp4'}}

For files on Amazon S3, the 'url' value is of the form 's3://<s3endpoint>/<bucketname>/<key>', e.g. 's3://s3.amazonaws.com/mybucket/video/intro.mp4'. See the S3 documentation for a list of available endpoints. When using S3, two additional items must be present in the source parameter: api_key and api_secret. These are the AWS credentials to use to access the bucket. If the files are publicly readable in your S3 bucket, you may use an HTTP URL instead of an S3 URL.

Reminder: The Cloud Slicer may only process files that are smaller than 90 GBs. Please use a local slicer for larger files.

argsObject(optional) Any number of slicebot slicer configuration settings to use when slicing the file.
Response ParametersTypeDescription
jobObjectThe newly created cloud slicing job, as in the same format as returned by /cloudslicer/jobs/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
Call('/api2/cloudslicer/jobs/create', args=dict(trim='5000,10000', description='My file description'),
                source=dict(url='http://www.myserver.com/videos/test.mp4'))

{
    "job": {
        "state": "waiting",
        "last_error": "",
        "args": {
            "trim": "5000,10000",
            "desc": "My file description"
        },
        "attempts": 0,
        "source": {
            "url": "http://www.myserver.com/videos/test.mp4"
        },
        "finished": 0,
        "last_start": 0,
        "owner": "a735c56ea4014685bc74c0a375236cc5",
        "progress": "",
        "id": "0dce9166be404672a7dd0d28d7257587"
    },
    "error": 0
}

Note: as with slicebot, the cloud slicer will make use of support files (ttml, configuration) if present on the server alongside the media file. For example, if your file's source URL is http://server.org/file.mp4, then prior to slicing it, the cloud slicer will check http://server.org/file.mp4.ttml to see if a TTML file is present for subtitles, and it will also check http://server.org/file.mp4.cfg to see if a slicebot configuration file is present with additional settings. Also support files are optional - if they are not present then no error will result.

Additionally, if you supply an invalid slicer argument, you will recieve an array of the invalid args in the response formatted thusly:

1
2
3
4
5
6
7
8
{
    "job": {...},
    "illegal_slicer_args": [
        "bad_arg1",
        "bad_arg2"
    ],
    "error": 0
}

However, this will not prevent the job from being created or processed as the invalid args are ignored.

/cloudslicer/jobs/get

Retrieves the details of an existing cloud slicing job

Request ParametersTypeDescription
idStringThe ID of the cloud slicing job to retrieve.
Response Parameters (inside the 'job' object)TypeDescription
idStringThe unique ID for this job
ownerStringThe owner (account) ID of the job's owner
sourceObjectThe media file's source object, as passed to /cloudslicer/jobs/create
argsObjectAdditional slicing parameters, if any
stateStringThe current state of the job. One of: 'waiting' (the job is in the job queue, waiting for a cloud slicer to work on it), 'assigned' (the job is being worked on by a cloud slicer), 'done' (the job has finished slicing successfully), 'error' (after multiple tries, the system gave up trying to slice the file), 'cancelled' (The job was cancelled before/during slicing)
last_startIntegerTimestamp (Unix time, in milliseconds) of the most recent time the job was assigned to a cloud slicer
finishedIntegerTimestamp (Unix time, in milliseconds) of when the job reached the done or error state.
attemptsIntegerThe number of times the system has attempted to slice the file so far
progressStringA human-readable description of any progress made on handling the job
last_errorStringIn the event slicing failed, the most recent error message that resulted
hd_exported_urlStringThis parameter is only returned upon the completion of a job created by the /jobs/create_export endpoint. It indicates the URL to the exported MP4 asset. If captions are present, a TTML file may be downloaded by appending ".ttml" to this URL.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
Call('/api2/cloudslicer/jobs/get', id='0dce9166be404672a7dd0d28d7257587')

{
    "job": {
        "state": "waiting",
        "last_error": "",
        "args": {
            "trim": "5000,10000",
            "desc": "blarg"
        },
        "attempts": 0,
        "source": {
            "url": "http://www.protoven.com/dave/edu/TomNgo_lo.mp4"
        },
        "finished": 0,
        "last_start": 0,
        "owner": "a735c56ea4014685bc74c0a375236cc5",
        "progress": "",
        "id": "0dce9166be404672a7dd0d28d7257587"
    },
    "error": 0
}

/cloudslicer/jobs/list

Retrieves a list of current and recent cloud slicing jobs

Request ParametersTypeDescription
limitInteger(optional) Cap the number of jobs reutrned, maximum of 50 jobs.
skipInteger(optional) Skip over some number of jobs when building the list of jobs to return. The skip and limit parameters can be used together for pagination of results.
Response ParametersTypeDescription
jobsListA list of jobs, where each matches the form returned by jobs/get.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
Call('/api2/cloudslicer/jobs/list', limit=3)

{
    "jobs": [
        {
            "id": "d3345dbe5e064d09a20b762f7618839e",
            "attempts": 1,
            ...
        },
        {
            "id": "aa85e5d009ae459d98b24a540ef5a0c7",
            "attempts": 3,
            ...
        },
        {
            "id": "361f8426d36a4ac3af3348113489c83a",
            "attempts": 1,
            ...
        }
    ],
    "error": 0
}

/cloudslicer/jobs/delete

Deletes queued or finished cloud slicing jobs

Request ParametersTypeDescription
idsListOne or more job IDs to delete.
Response ParametersTypeDescription
actionsListA list of actions taken, where each action is an ID from the request and a string description of what action was taken. If the job was deleted, the action is 'deleted'. Otherwise it is the reason why it was not deleted.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Call('/api2/cloudslicer/jobs/delete', ids=['1234', 'd3345dbe5e064d09a20b762f7618839e'])

{
    "actions": [
        [
            "1234",
            "Not found"
        ],
        [
            "d3345dbe5e064d09a20b762f7618839e",
            "deleted"
        ]
    ],
    "error": 0
}

/cloudslicer/jobs/quickclip

Quick Clip jobs allow you to quickly create simple clips from your Uplynk assets. Unlike the clipping tool, the asset is copied. So you cannot add overlays, fades, bumper assets, add or remove ad breaks, add or remove alternate audio tracks or captions, etc. It's much more limited in it's capabilities as a tradeoff for speed.

Quick Clips returns an asset ID (via /cloudslicer/jobs/get after export finishes)
assetStringThe Asset ID of the clip that was created.
Request ParametersTypeDescription
sourceDictA dict containing a single key, 'trim' which is an array with two elements. The start offset in milliseconds and the duration in milliseconds.
argsDictA dict containing the keys below:
 beam_idStringThe GUID of the asset you wish to clip. (required)
 poster_tsInteger/ StringTimestamp from which to extract a frame (of the original asset being clipped) to be set as the poster image of the new asset. Specify in milliseconds as an integer, or as a string in the 'hh:mm:ss.ms' or 'ss.ms' format. (optional)
Response ParametersTypeDescription
jobObjectThe newly created cloud slicing job, as in the same format as returned by /cloudslicer/jobs/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/cloudslicer/jobs/quickclip', source={"trim":[3000,15000]}, args={"beam_id":"3adca3eeeb7c4f46ad2e0988079816de"})

{
    'job':
    {
        'state': 'waiting', 
        'last_error': '', 
        'args': {}, 
        'attempts': 0, 
        'source': {'trim': [3000, 15000], 'url': 'http://content.uplynk.com/3adca3eeeb7c4f46ad2e0988079816de.m3u8'}, 
        'finished': 0, 
        'asset': None, 
        'last_start': 0, 
        'owner': 'eeef81067eee479aaa6e837cb97cf6d9', 
        'progress': '', 
        'id': 'd3345dbe5e064d09a20b762f7618839e'
    }, 
    'error': 0
}

Call('/api2/cloudslicer/jobs/get', id='d3345dbe5e064d09a20b762f7618839e')

{
    'job': 
    {
        'state': 'done', 
        'last_error': '', 
        'args': {}, 
        'attempts': 1, 
        'source': {'trim': [3000, 15000], 'url': 'http://content.uplynk.com/3adca3eeeb7c4f46ad2e0988079816de.m3u8'}, 
        'finished': 1447368234226, 
        'asset': 'e30ed0b8eee447c7b53c1c441ceecb3f', 
        'last_start': 1447366087113, 
        'owner': 'eeef81067eee479aaa6e837cb97cf6d9', 
        'progress': 'Finished successfully', 
        'id': 'd3345dbe5e064d09a20b762f7618839e'
    }, 
    'error': 0
}

/cloudslicer/jobs/create_export

Creates a job to export the specified asset as a downloadable MP4.

Upon completion, the hd_exported_url parameter, which reports the URL to the exported MP4, will be added to the response provided by the /cloudslicer/jobs/get endpoint. If captions are present, a TTML file may be downloaded by appending ".ttml" to this URL.

Request ParametersTypeDescription
assetStringIdentifies the asset that will be exported by its GUID.
Response ParametersTypeDescription
jobObjectDescribes the requested cloud slicing job using the same format as the /cloudslicer/jobs/get endpoint.
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
Call('/api2/cloudslicer/jobs/create_export', asset='a29a0bf647454d70bbb9b13d6896a108')

{
    "job": {
        "state": "assigned", 
        "last_error": "", 
        "args": {"export_mp4": True}, 
        "attempts": 0, 
        "source": {}, 
        "finished": 0, 
        "asset": "a29a0bf647454d70bbb9b13d6896a108", 
        "last_start": 0, 
        "owner": "a735c56ea4014685bc74c0a375236cc5", 
        "progress": "", 
        "id": "d0d05debde654249ae25b1c7f45a19fe"
    }, 
    "error": 0
}

Call('/api2/cloudslicer/jobs/get', id='d0d05debde654249ae25b1c7f45a19fe')

{
    "job": {
        "state": "done", 
        "last_error": "", 
        "args": {"export_mp4": True}, 
        "attempts": 1, 
        "source": {}, 
        "finished": 1488565621330, 
        "hd_exported_url": "http://stg-ec-ore-u.uplynk.com/slices/5409e4c0c71444849ac6e07743ff20bd_g.mp4"
        "asset": "a29a0bf647454d70bbb9b13d6896a108", 
        "last_start": 1488565611238, 
        "owner": "a735c56ea4014685bc74c0a971238cc5", 
        "progress": "Finished successfully", 
        "id": "d0d05debde654249ae25b1c7f45a19fe"
    },
    "error": 0
}

/cloudslicer/jobs/cancel

Cancels a queued or currently running cloudslicer job. Cloudslicer jobs that have already completed cannot be cancelled. Note that you will still be billed for any slicing and encoding that have completed up to the point the job is cancelled. You will also have to delete any partially sliced assets manually.

Request ParametersTypeDescription
idStringThe ID of the cloudslicer job to cancel.
Response ParametersTypeDescription
jobObjectThe cancelled cloud slicing job, as in the same format as returned by /cloudslicer/jobs/get.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
Call('/api2/cloudslicer/jobs/cancel', id='d3345dbe5e064d09a20b762f7618839e')

{
    "job": {
        "state": "cancelled", 
        "last_error": "", 
        "args": {"export_mp4": True}, 
        "attempts": 0, 
        "source": {}, 
        "finished": 0, 
        "asset": "a29a0bf647454d70bbb9b13d6896a108", 
        "last_start": 0, 
        "owner": "a735c56ea4014685bc74c0a375236cc5", 
        "progress": "", 
        "id": "d0d05debde654249ae25b1c7f45a19fe"
    }, 
    "error": 0
}

/cloudslicer/jobs/copy-from-library

Copies an asset from a library shared with your account to your private CMS library. The following data will be copied from the original asset:

  • Audio/video content
  • Asset name
  • Poster image
  • Metadata
  • Ad breaks
  • Allowed domains
  • DRM status

Note: The asset copied to your account will be assigned a unique system-defined ID (i.e., GUID).

A request parameter is described below.

Request ParametersTypeDescription
asset_idStringRequired. Identifies the asset to be copied to your account by its system-defined ID (i.e., GUID). This asset must reside in a libary shared with your account.

Response parameters are described below.

Response ParametersTypeDescription
jobObjectDescribes the request to copy an asset.
 stateStringIndicates status information for the requested copy action.
Valid values are:
  • waiting: Indicates that the asset is awaiting processing, but has not been assigned a cloud slicer.
  • assigned: Indicates that the asset is is currently being processed by a cloud slicer.
  • done: Indicates that the asset has already been copied to your Uplynk account.
  • error: Indicates that the asset was not copied after several attempts.
  • cancelled: Indicates that the asset was not copied because the job was cancelled.
 last_errorStringIndicates the most recent error message that was reported as a result of a failure to slice the asset.
 argsObjectIndicates any additional parameters that were passed to the Live Slicer.
 attemptsIntegerIndicates the number of attempts that were made to slice the asset.
 sourceObjectContains a parameter that identifies the source content.
  beam_idStringIdentifies the asset being copied by its system-defined ID (i.e., GUID).
 finishedIntegerIndicates the date/time, in Unix time (milliseconds), at which the request to copy the asset was completed or reached an error state.
 assetIdentifies the asset that was created by its system-defined ID (i.e., GUID).
 last_startIntegerIndicates the start date/time, in Unix time (milliseconds), for the most recent attempt to slice the asset (i.e., the job was assigned to a cloud slicer).
 ownerStringIdentifies your Uplynk account by its system-defined ID (i.e., user ID).
 progressStringProvides progress information on the request to copy the asset.
 idStringIdentifies the job by its system-defined ID.
errorIntegerIndicates whether an error occurred.
Example
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
Call('/api2/cloudslicer/jobs/copy-from-library', asset_id = 'ae01164a50a04847b5624485aae1aac3')

{
	'job' : {
		'state' : 'waiting',
		'last_error' : '',
		'args' : {},
		'attempts' : 0,
		'source' : {
			'beam_id' : 'ae01164a50a04847b5624485aae1aac3'
		},
		'finished' : 0,
		'asset' : None,
		'last_start' : 0,
		'owner' : 'a7231b9499a94e7a90e0438c6a136940',
		'progress' : '',
		'id' : 'a3b33c97e932443ea33bc44ab83abb33'
	},
	'error' : 0
}

/cloudslicer/batch/copy-from-library

Copies one or more assets from a library shared with your account to your private CMS library. The following data will be copied from the original asset:

  • Audio/video content
  • Asset name
  • Poster image
  • Metadata
  • Ad breaks
  • Allowed domains
  • DRM status

Note: Each asset copied to your account will be assigned a unique system-defined ID (i.e., GUID).

A request parameter is described below.

Request ParametersTypeDescription
asset_idsListRequired. Identifies each asset in a shared libary that will be copied to your account. Each asset is identified by its system-defined ID (i.e., GUID).

Response parameters are described below.

Response ParametersTypeDescription
batch_idStringIdentifies the batch job by its system-defined ID. Pass this ID to the /batch/get-job-states method to find out the status of the batch copy job.
errorIntegerIndicates whether an error occurred.
Example
1
2
3
4
5
6
7
Call('/cloudslicer/batch/copy-from-library', asset_ids = ['d0c403730ca14575a92f337ef71e0c5a', 
'30d0013d33d54b7c9354a339bfdc743c'])

{
	'batch_id' : '63a304b482284968be49571adb6db661',
	'error' : 0
}

/cloudslicer/batch/get-job-states

Provides status information on a batch copy job.

A request parameter is described below.

Request ParametersTypeDescription
idStringRequired. Identifies a batch copy job by its system-defined ID. This ID was provided in the response to the /batch/copy-from-library method.

Response parameters are described below.

Response ParametersTypeDescription
StatesObjectIndicates status information for each copy job in the batch.
This parameter may contain one or more of the following lists:
  • waiting: Contains the system-defined ID (i.e., GUID) for each asset that is awaiting processing, but has not been assigned a cloud slicer.
  • assigned: Contains the system-defined ID (i.e., GUID) for each asset that is currently being processed by a cloud slicer.
  • done: Contains the system-defined ID (i.e., GUID) for each asset that has already been copied to your Uplynk account.
  • error: Contains the system-defined ID (i.e., GUID) for each asset that was not copied after several attempts.
  • cancelled: Contains the system-defined ID (i.e., GUID) for each asset that was not copied because the batch copy job was cancelled.
errorIntegerIndicates whether an error occurred.
Example
1
2
3
4
5
6
7
8
Call('/api2/cloudslicer/batch/get-job-states', id = 'b3a304b482284968be49571adb6db521')

{
	'states' : {
		'done' : ['a0c403730ca14575a92f337ef71e0c5f', 'c0d0013d33d54b7c9354a339bfdc7434']
	},
	'error' : 0
}

Job Life Cycle

A new slicing job has the 'waiting' state until a cloud slicer begins to work on it, at which point its state becomes 'assigned'. If the file is successfully sliced, it moves to the 'done' state.

If the file fails to slice, it is moved back to the 'waiting' state so that another attempt can be made. If after a few failed attempts the system determines that no additional attempts are likely to succeed, the job is moved into the 'error' state.

After calling /cloudslicer/jobs/cancel API the job will be placed in the 'cancelled' state. If the job was currently slicing, it will stop within 10 seconds. If it was not yet assigned to a cloudslicer, slicing will never begin.

You can use the /cloudslicer/jobs/delete API to delete any job in the waiting, done, cancelled, or error states, but jobs cannot be erased while in the assigned state.

Once a job is finished (in the done, cancelled, or error state), the system will automatically erase the job entry from its database after 72 hours.