Skip to content

Create a clip for download

If configured for your OU you can create clips from assets and get a download link.

Create a clipping order

API documentation: https://mgmtapidocs.emp.ebsd.ericsson.net/

The parts of the management API that are relevant for ordering clips is the clipping part of the API and in particular the endpoint /v1/customer/{customerUnit}/businessunit/{businessUnit}/clip/{assetId} .

To request a clip you send in a clipping order request to the ManagementAPI. If you have standard VODs you can simply send in two durations relative to the start of the asset and then a clip will be generated for you. You are also expected to provide an id for the request, a callback URL and can provide an optional boolean specifying if you want the generated clip to be audio only or not.

{
    "id":"4f79ad8a-9e53-4f86-bf31-4151b3d7e127",
    "startDuration":"PT1H2M43S",
    "endDuration":"PT1H4M43S",
    "callback":"https://www.example.com/callback",
    "audioOnly":false
}

The ID allows you to keep track of clipping orders on your end. When a clipping order is fullfilled and we have generated the file and download URL we will POST it to the specified callback URL The callback will look as follows if everything went well

{
  "orderId": "e28c3bd1-ef6e-4f1f-b2f2-63e624030774",
  "requestId" : "4f79ad8a-9e53-4f86-bf31-4151b3d7e127",
  "assetId" : "theAssetIdYouSpecifiedInThePath",
  "duration" : "PT2M",
  "downloadLink" : "https://cdnHost/clip/filename.mp4?sig=downloadToken",
  "fileSize" : 4152395,
  "expiration" : "2021-05-28T15:05:48.442392Z", 
  "status" : "DONE"
}

The requestId in the callback is the ID you specified in the body of the original request, the assetId is the id specified in the path when making the request. Duration is simply the duration of the generated clip and fileSize is the size of the generated clip in bytes. The downloadLink is where you can find the clip and expiration is the date until which the downloadLink is valid. Once the expiration date is reached the clip will be automatically purged and no longer available for download.

If you are using assets with wall clock time you can order your clips using absolute time instead of duration like in the example below.

{
    "id":"3d7e1d8a-9e53-4f86-bf31-4151bd8ae127",
    "startTime":"2020-02-12T12:00:00.000Z",
    "endTime":"2020-02-12T12:00:20.000Z",
    "callback":"https://www.example.com/callback",
    "audioOnly":false
}

If something goes wrong during the clip generation you'll get an error callback. If you want to separate error callbacks from regular callbacks you can specify an errorCallback-URL in the original request like this

{
    "id":"4f79ad8a-9e53-4f86-bf31-4151b3d7e127",
    "startDuration":"PT1H2M43S",
    "endDuration":"PT1H4M43S",
    "callback":"https://www.example.com/callback",
    "errorCallback":"https://www.example.com/errorCallback",
    "audioOnly":false
}

If you don't specify a separate errorCallback the error callbacks will just be sent to the normal callback URL. The body of the error callback is the following

{
  "orderId": "e28c3bd1-ef6e-4f1f-b2f2-63e624030774",
  "requestId" : "4f79ad8a-9e53-4f86-bf31-4151b3d7e127",
  "assetId" : "theAssetIdYouSpecifiedInThePath", 
  "duration" : "PT2M",
  "status" : "FAILED",
  "message" : "some message describing the reason why it failed"
}

The message will be some sort of "error code" describing why it failed. At the moment the following messages are sent out but this might change in the future

  • ASSET_NOT_FOUND

If the asset doesn't exist in the system when the clipping order gets executed. * INTERNAL_TIMEOUT

If there is a timeout inside RBMOTT during the execution of the clipping order. This should not happen but if it does it might be worth retrying the clipping order since it's probably temporary. * INTERNAL_ERROR

An error occurred during execution of the clipping order and it's very likely it will persist. A retry of the clipping order will most likely not do anything to solve the issue.

Check the status of a clipping order

When a clipping order is created you get a response like this

{
    "id": "e28c3bd1-ef6e-4f1f-b2f2-63e624030774",
    "requestId": "3d7e1d8a-9e53-4f86-bf31-4151bd8ae127",
    "state":"NEW"
    "created": "2021-05-27T21:43:20.000Z",
    "changed": "2021-05-27T21:43:20.000Z"
}

The requestId is the id you specified in the request. The id is the id of the clipping order inside our system. You can use this id to poll for the current state of the clipping order. The possible states are

  • NEW The clipping order has been received, but we haven't started to do any actual work yet
  • RUNNING We are currently executing the work order
  • DONE We are done creating the clip, but we haven't performed the callback yet
  • FAILED We encountered an error during the clip generation process
  • REPORTED We have performed the callback and got a 2XX response while doing so OR no callback was specified
  • CALLBACK_FAILED We got anything but a 2XX back from the callback URL

Update a clipping order

If you have ordered a clip and the order hasn't run yet it's possible to update the order by POSTing the following body

{
   "assetId":"9e531d8a-3d7e-4f86-bf31-4151bd8ae127_a23b54",
   "startDuration":"PT1H2M43S",
   "endDuration":"PT1H4M43S",
   "callback":"https://www.example.com/callback",
   "audioOnly":false
}

The update of course also supports start- and endTime if you prefer to use that.

If the clipping order has already been run an update won't trigger it to run again.

Retry a clipping order

If for whatever reason you want a specific clipping order to be executed again instead of creating a new one you can just have it run again. The logic is extremely simple at this point and will just reset the clipping order so that the system re-runs all steps in the clipping workflow. You can't retry deleted work orders but you can retry failed ones. This might be useful eg. if you notice you have clipping orders in the state CALLBACK_FAILED. Simply update the callback URL and retry them.

Delete a clipping order

If you have requested a clip but change your mind you can delete the clipping order in question. This only means that the order as such is marked as deleted. If you delete it once it has run the files, URLs etc. will still be available until they are automatically purged.