Clip and Draft Clip API

Use these versioned APIs to perform the following tasks:

• Retrieve and manage drafts of video clips.

  Endpoint	Description
  Create Draft Clip POST /clipping_draft	Creates a draft of a video clip.
  Delete Draft Clip DELETE /clipping_draft/Draft Clip ID	Deletes a draft of a video clip.
  Get All Draft Clips GET /clipping_draft	Retrieves a list of all drafts of video clips.
  Get Draft Clip GET /clipping_draft/Draft Clip ID	Retrieves a specific draft of a video clip.

• Retrieve video clip information.

  Endpoint	Description
  Get Multiple Clips GET /clip/draft_info GET /clip/draft_info?draft_id=Draft Clip ID	Retrieves up to 1,000 of the latest video clips generated from draft clips. You may filter the response to only include the clip created from a specific draft clip.
  Get Clip GET /clip/draft_info/Clip ID	Retrieves a specific video clip.

Base URL

Use the following base URL:

Draft Clips

Learn how to create, delete, retrieve all, and retrieve a draft of a video clip.

Create Draft Clip

Creates a draft of a video clip by identifying:

• An asset in your library.
• The clip's starting and stopping point.

Convert drafts to video clips from within the Clipping tool.

Request

Request syntax:

Request body:

Define a draft video clip through the following properties:

Property	Data Type	Description
beam Required	String	Identifies the asset in your library from which a draft clip will be created by its asset ID. Where can I find an asset ID? Navigate to the CMS library by clicking the Content tab. Select the desired asset. The asset ID corresponding to the asset selected in the previous step is listed under the GUID label.
duration	Integer	You must specify one of the following properties: duration, stop, or stop_time. Learn more. Determines the relative stopping point for the draft of the video clip. Specify the clip's duration, in seconds, starting from the time defined by either the start or start_time properties.
start	Integer	You must specify either start or start_time. Learn more. Determines the relative starting point for the draft of the video clip. Specify this starting point as the number of milliseconds from the start of the asset.
start_time	String	You must specify either start or start_time. Learn more. Determines the starting point for the draft of the video clip. Specify the date and time (UTC) at which the clip will start. Calculate the number of seconds into the asset at which the clip will start by using the asset's creation date as a point of reference. Use the Asset API to find out an asset's creation date. Syntax: YYYY-MM-DDThh:mm:ssZ Example: 2023-01-08T20:31:11Z Learn more. Calculate the number of seconds from the start of the asset at which the clip will start by subtracting the asset's creation date from start_time. Formula: Starting PointIdentifies the number of seconds from the start of the asset at which the video clip will start. = Asset's Creation Date - Start Time
stop	Integer	You must specify one of the following properties: duration, stop, or stop_time. Learn more. Determines the relative stopping point for the draft of the video clip. Specify this stopping point as the number of milliseconds from the start of the asset.
stop_time	String	You must specify one of the following properties: duration, stop, or stop_time. Learn more. Determines the stopping point for the draft of the video clip. Specify the date and time (UTC) at which the clip will stop. Calculate the number of seconds into the asset at which the clip will stop by using the asset's creation date as a point of reference. Use the Asset API to find out an asset's creation date. Syntax: YYYY-MM-DDThh:mm:ssZ Example: 2023-01-08T20:31:11Z Learn more. Calculate the number of seconds from the start of the asset at which the clip will stop by subtracting the asset's creation date from start_time. Formula: Stopping PointIdentifies the number of seconds from the start of the asset at which the video clip will stop. = Asset's Creation Date - Stop Time
title	String	Defines a description that will be assigned to the draft of the clip. Default value: By default, the asset's description will be assigned to the draft of the clip.
meta	Dictionary	Identifies zero or more key-value pairs that will override a profile's metadata configuration for the current draft. You cannot use this property to add or remove metadata keys from a profile. Specifying a key that does not exist within the profile will cause it to be ignored. This property does not override key-value pairs that have not been specified. For example, if you specify 2 metadata key-value pairs and a profile contains 5 metadata keys, then the default values for the other 3 metadata keys will also be applied to the current draft. Syntax: {"Key 1Represents a metadata key. This key will be ignored unless it exists in the current profile.":"Value 1Represents the metadata value that will be assigned to a key.", "Key 2Represents a metadata key. This key will be ignored unless it exists in the current profile.":"Value 2Represents the metadata value that will be assigned to a key.", "Key nRepresents a metadata key. This key will be ignored unless it exists in the current profile.":"Value nRepresents the metadata value that will be assigned to a key."} Example: {"Title": "Slam Dunk Compilation", "Sport": "Basketball"}
profile	String	Assigns a profile to the draft of the video clip. You may assign a different profile to the draft of the video clip when using the Clipping tool. Default value:  If a profile has not been assigned to a draft of a video clip, then one will be assigned as indicated below: New Session: Upon loading the Clipping tool, the draft of the video clip will be assigned the first profile listed on the Clipping page. Existing Session: The default profile is determined by the currently selected profile within the Clipping tool.

Identifying a Video Segment

Define a clip's starting and stopping point by passing any of the following combination of properties:

    ...
    'start': 120000,
    'stop': 130000,
    ...

    ...
    'start': 120000,
    'duration': 10,
    ...

    ...
    'start_time': 2023-01-03T17:52:29Z,
    'stop_time': 2023-01-03T17:52:39Z,
    ...

    ...
    'start_time': 2023-01-03T17:52:29Z,
    'duration': 10,
    ...

You must specify one of the above property combinations. Do not specify additional time properties. For example, if you define start and stop, do not include start_time, stop_time, or duration in the request.

Use the following syntax to specify a timestamp (ISO 8601 - seconds; UTC):

Syntax:

Example:

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

The response for a successful request contains the following properties:

Sample Request/Response

Call the create_draft_clip module (Python 3) to create a draft of a video clip. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class CreateDraftClip:
    def __init__(self):
        self.host = "services.uplynk.com"

    def run(self):
        """
        Create a draft of a video clip.
        """
        self._create_draft()

    def _create_draft(self):
        url = "{}{}".format(self.host, "/api/v4/clipping_draft")

        start_milliseconds = 55000 # how far into the asset should the clip start
        stop_seconds = 10 # how long after the start point should the clip stop
        payload = {
            'beam':'0123456789abcdefghijklmnopqrstuv',
            'title':'My Clip',
            'start': start_milliseconds,
            'duration': stop_seconds,
        }

        headers = {'Content-Type': 'application/json'}

        response = requests.post(
            url, params=APIParams(APICredentials()).get_params({}), data=json.dumps(payload), headers=headers 
        )

        print(response.json())

CreateDraftClip().run()

Response:

{
	"@id": "/api/v4/clipping_draft/abc0123def456ghi789klmno0123pqrs",
	"@type": "ClippingDraft",
	"id": "abc0123def456ghi789klmno0123pqrs"
}

Delete Draft Clip

Deletes a draft of a video clip. Identify a draft by its system-defined ID.

Request

Request syntax:

Use the Get All Draft Clips endpoint to retrieve a list of drafts and their system-defined IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

The response for a successful request contains the following properties:

Sample Request/Response

Call the delete_draft_clip module (Python 3) to delete a draft of a video clip. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class DeleteDraftClip:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Deletes a draft of a video clip.
        """
        self._delete_draft()

    def _delete_draft(self):
        draft_clip_id = 'abc0123def456ghi789klmno0123pqrs' # Replace with the desired draft clip ID.
        url = "{}{}{}".format(self.host, "/api/v4/clipping_draft/", draft_clip_id)
 
        response = requests.delete(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

DeleteDraftClip().run()

Response:

{
	"message": "Deleted",
	"@id": "/api/v4/clipping_draft/15b8de658a2e4149aa772de8c7d8b86d",
	"@type": "ClippingDraft"
}

Get All Draft Clips

Retrieves a list of drafts of video clips.

Request

Request syntax:

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

The response for a successful request contains the following properties:

items List

The items list describes each draft via the following properties:

Sample Request/Response

Call the get_all_draft_clips module (Python 3) to retrieve a list of draft clips. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class GetAllDraftClips:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Get all drafts of video clips.
        """
        self._get_all_drafts()

    def _get_all_drafts(self):
        url = "{}{}".format(self.host, "/api/v4/clipping_draft")

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

GetAllDraftClips().run()

		

Response:

{
	"total_items": 2,
	"items": [{
			"beam": "ab4cdd9b405c41c984adc6d0bea55bcd",
			"created": "2019-12-27T23:20:44.436000Z",
			"title": "My First Draft",
			"@type": "ClippingDraft",
			"frame_stop_time": 29.123,
			"frame_start_time": 24.978,
			"@id": "/api/v4/clipping_draft/25c8de658a2e4149aa772de8c7d8b8ge",
			"id": "25c8de658a2e4149aa772de8c7d8b8ge"
		}, {
			"beam": "ab4cdd9b405c41c984adc6d0bea55bcd",
			"created": "2019-12-27T22:58:52.723000Z",
			"title": "My Second Draft",
			"@type": "ClippingDraft",
			"frame_stop_time": 65.978,
			"frame_start_time": 54.978,
			"@id": "/api/v4/clipping_draft/1237d408b1b944d2bb5fd0c33d43ac7e",
			"id": "1237d408b1b944d2bb5fd0c33d43ac7e"
		}
	],
	"@id": "/api/v4/clipping_draft",
	"@type": "Collection"
}

Get Draft Clip

Retrieves a draft of a video clip. Identify a draft by its system-defined ID.

Request

Request syntax:

Use the Get All Draft Clips endpoint to retrieve a list of drafts and their system-defined IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

The response for a successful request contains the following properties:

Sample Request/Response

Call the get_draft_clip module (Python 3) to retrieve a draft. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class GetDraftClip:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Get a draft of a video clip.
        """
        self._get_draft()

    def _get_draft(self):
        draft_clip_id = 'abc0123def456ghi789klmno0123pqrs' # Replace with the desired draft clip ID.
        url = "{}{}{}".format(self.host, "/api/v4/clipping_draft/", draft_clip_id)

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

GetDraftClip().run()

Response:

{
	"beam": "abc0123def456ghi789klmno0123pqrs",
	"created": "2019-12-27T23:20:44.436000Z",
	"title": "My Third Draft",
	"@type": "ClippingDraft",
	"frame_stop_time": 52.478,
	"frame_start_time": 44.978,
	"@id": "/api/v4/clipping_draft/1238de658a2e4149aa772de8c7d8bdef",
	"id": "1238de658a2e4149aa772de8c7d8bdef"
}

Video Clips

Learn how to retrieve information for multiple or a specific video clip created from a draft clip.

Get Clip

Retrieves a specific video clip generated from a draft clip.

Request

Request syntax:

Use the Get Multiple Clips endpoint to retrieve a list of clips and their system-defined IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

The response for a successful request contains the following properties:

Sample Request/Response

Call the get_clip module (Python 3) to retrieve a specific clip. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class GetClip:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Get a video clip.
        """
        self._get_clip()

    def _get_clip(self):
        clip_id = 'e8d6b5cb940c40cc9ec6ad081a38f3f0' # Replace with the desired clip ID.
        url = "{}{}{}".format(self.host, "/api/v4/clip/draft_info/", clip_id)

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

GetClip().run()

Response:

{
	'@id': '/clip/draft_info/e1fc7c4987ce4b6f96dc561993479666',
	'@type': 'Clip',
	'asset': '',
	'draft_id': '3b5cd277915c4c0cb0aea542ce42b5f2',
	'is_complete': False,
	'id': 'e1fc7c4987ce4b6f96dc561993479666'
}

Get Multiple Clips

Retrieves up to 1,000 of the latest video clips generated from draft clips. You may filter the response to only include the clip created from a specific draft clip.

Request

Request syntax (all clips):

Request syntax (filtered by draft clip):

Use the Get All Draft Clips endpoint to retrieve a list of draft clips and their system-defined IDs.

Authentication

Pass a digital signature based off of msg.

Learn more.

Response

The response for a successful request contains the following properties:

items List

The items list describes each video clip via the following properties:

Sample Request/Response

Call the get_multiple_clips module (Python 3) to retrieve a list of clips. This module imports names from the api_auth module.

import json
import requests
from api_auth import APICredentials, APIParams

class GetMultipleClips:
    def __init__(self):
        self.host = "https://services.uplynk.com"

    def run(self):
        """
        Get multiple video clips.
        """
        self._get_multiple_clips()

    def _get_multiple_clips(self):
        url = "{}{}".format(self.host, "/api/v4/clip/draft_info")

        response = requests.get(
            url, params=APIParams(APICredentials()).get_params({})
        )

        print(response.json())

GetMultipleClips().run()

Response:

{
	'@id': '/clip/draft_info',
	'@type': 'Collection',
	'items': [{
			'@id': '/clip/draft_info/e1fc7c4987ce4b6f96dc561993479666',
			'@type': 'Clip',
			'asset': '',
			'draft_id': '3b5cd277915c4c0cb0aea542ce42b5f2',
			'is_complete': False,
			'id': 'e1fc7c4987ce4b6f96dc561993479666'
		}
	],
	'total_items': 1
}

More Information

• Versioned API