Use the /sapi/mediaclip endpoint to manage mediaclip metadata. Mediaclip objects contain:
- Metadata
- File/stream references
- References to related entities (subtitles, timelines and audiotracks)
The /sapi/mediaclip has limited support for managing related entities. Related entities can be managed by using their own endpoints.
1.0 | Mediaclip Object
1.1 | Example Mediaclip Object
Example mediaclip object
{
"id": "4471615",
"type": "MediaClip",
"mediatype": "video",
"fitmode": "",
"usetype": "editorial",
"sourcetype": "on_demand",
"originalfilename": "sample-mp4.mp4",
"length": 30,
"sourceid": "original_source_id_987654321",
"title": "The perfect coffee",
"description": "This video is about coffee, the most appreciated drink",
"deeplink": "https://www.bluebillywig.com/team",
"gendeeplink": null,
"copyright": "",
"author": "Blue Billywig",
"status": "published",
"publicationid": "754",
"chapters": [
{
"id": "k6r8eeu31b",
"title": "Introduction",
"timeOffset": 0
},
{
"id": "3ubivf3s4ai",
"title": "Origins",
"timeOffset": 10
},
{
"id": "0vzvcmxgbiz",
"title": "Summary",
"timeOffset": 20
}
],
"createddate": "2021-11-29T14:20:37Z",
"updateddate": "2024-07-01T16:14:14Z",
"publisheddate": "2021-11-29T14:20:37Z",
"views": 2592,
"width": 1920,
"height": 1080,
"dar": "16:9",
"originalWidth": 1920,
"originalHeight": 1080,
"createdBy": "support@bluebillywig.com",
"updatedBy": "support@bluebillywig.com",
"date": "1970-01-01T00:00:00Z",
"src": "/yourcompanyname/media/2021/11/29/4471615.mp4",
"cat": ["coffee", "beverage"],
"thumbnails": [
{
"src": "/yourcompanyname/media/2021/12/01/4471615-1638374527283339.jpg",
"width": "1920",
"height": "1080",
"main": true,
"crops": {
"landscape": {
"x": 0,
"y": 0,
"width": 1,
"height": 1,
"main": true
}
}
},
{
"src": "/yourcompanyname/media/2021/12/01/4471615-1638374527877623.jpg",
"width": "1920",
"height": "1080",
"main": false,
"crops": {
"landscape": {
"x": 0,
"y": 0,
"width": 1,
"height": 1,
"main": false
}
}
}
],
"assets": [
{
"mediatype": "MP4_MAIN",
"id": "1638195639053247",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195592818702.mp4",
"length": "30",
"exactlength": "30656",
"width": "1280",
"height": "720",
"bandwidth": "2000",
"mimetype": "video/mp4; codecs=\"avc1.4d481f, mp4a.40.2\""
},
{
"mediatype": "MP4_MAIN",
"id": "1638195640108785",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195593007920.mp4",
"length": "30",
"exactlength": "30656",
"width": "768",
"height": "432",
"bandwidth": "1600",
"mimetype": "video/mp4; codecs=\"avc1.4d481e, mp4a.40.2\""
},
{
"mediatype": "MP4_HD",
"id": "1638195644375364",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195593735015.mp4",
"length": "30",
"exactlength": "30656",
"width": "1920",
"height": "1080",
"bandwidth": "3000",
"mimetype": "video/mp4; codecs=\"avc1.4d4828, mp4a.40.2\""
}
],
"hasJobs": "false",
"subtitles": [
{
"languageid": "2912",
"languagename": "English",
"id": "142762",
"name": "",
"default": "false",
"isocode": "en",
"status": "published"
}
],
"transcript": null,
"exports": null,
"timelines": null,
"audiotracks": null
}
1.2 | Attributes
| Property | Description |
| type | (fixed) MediaClip. Read-only. |
| id | (string) Unique identifier of the mediaclip. Read-only. |
| mediatype | (string) Audio, video, image or document. Read-only. |
| fitmode | (string) Only used for video. Use to override the playout fitmode configuration. Read/write. |
| usetype | (string) Editorial or commercial. Commercial is only used for creatives or logos. Read/write. |
| originalfilename | (string) The original filename of the attached audiovisual file. Read/write |
| length | (Integer) The length in seconds. Read/write. |
| createddate | (string) ISO 8601 date/time the mediaclip was created. Read-only. |
| updateddate | (string) ISO 8601 date/time the mediaclip was last updated. Read-only. |
| publisheddate | (string) ISO 8601 date/time the mediaclip’s status was first set to published. Read-only. |
| sourceid | (string) An external unique identifier pointing to a source system of (part of) an ingested file name. Read-only (after initial ingest) |
| title | (string) Mediaclip title. Read/write. |
| description | (string) Mediaclip description text. Read/write. |
| deeplink | (string) Mediaclip “home url”. Read/write. |
| assets | (array) A list of stream files/versions/renditions. Mutable only on creation. After that manageable via /sapi/mediaasset endpoint (learn more about the sapi/mediaasset endpoint) |
| thumbnails | A list of images related to the mediaclip. Attributes: src (a file uri reference), main (true for the selected thumbnail and false for others), width (in pixels), height (in pixels). |
| status | Draft or published. If a mediaclip has status published it will be publicly available. |
| transcodingFinished | When true transcoding is finished for this clip. Read-only. |
| views | All time views |
2.0 | Create/Update
PUT /sapi/mediaclip
Create a new mediaclip by omitting the id property.
Example payload to create a new clip
{
"type": "MediaClip",
"mediatype": "video",
"fitmode": "",
"usetype": "editorial",
"sourcetype": "on_demand",
"originalfilename": "The perfect cup.mp4",
"sourceid": "my-unique-sourceid",
"title": "The perfect coffee",
"description": "Coffee, the most appreciated drink in the world.",
"deeplink": "",
"copyright": "Blue Billywig",
"author": "Billy",
"status": "published"
}PUT /sapi/mediaclip/{id}
Update an existing mediaclip by including the clip id property. Alternatively, use the source id property:
PUT /sapi/mediaclip?q=sourceid:”{sourceid}”
Example payload to update a clip
{
"type": "MediaClip",
"mediatype": "video",
"id": "1234567",
"fitmode": "",
"usetype": "editorial",
"sourcetype": "on_demand",
"originalfilename": "The perfect cup.mp4",
"sourceid": "my-unique-sourceid",
"title": "The perfect coffee",
"description": "Coffee, the most appreciated drink in the world.",
"deeplink": "",
"copyright": "Blue Billywig",
"author": "Billy",
"status": "published"
}The response will contain the entire created or updated mediaclip object.
Direct AWS S3 Upload
To add a video or audio file to a newly created mediaclip object: upload the file to the AWS S3 source bucket. Read more about uploading directly to AWS S3.
3.0 | Retrieve List
GET /sapi/mediaclip
Retrieves a list of mediaclips. By default a list of the 15 most recently created clips will be returned.
2.1 | Parameters
| Parameter | Description | Example |
| q | (string) specify a query to select a subset | ?q=title:”my fantastic new title” ?q=createddate:[2018-12-31T22:59:59Z TO 2019-12-31T22:59:29Z] |
| sort | (string fieldname string direction) determine sorting field and direction (default is id desc) | ?sort=title asc |
| limit | (integer) determine the number of mediaclips to return | ?limit=100 |
| offset | (integer) determine an offset to start the list | ?offset=100 |
4.0 | Retrieve
GET /sapi/mediaclip/{id}
Retrieves a mediaclip object.
Alternatively, query on a source id:
GET /sapi/mediaclip?q=sourceid:”{sourceid}”
5.0 | Delete
DELETE /sapi/mediaclip/{id}
Deletes a mediaclip object
Alternatively, query on a source id:
DELETE /sapi/mediaclip?q=sourceid:”{sourceid}”
5.1 | Params
| Parameter | Description | Example |
| purge | (boolean) permanently delete a mediaclip | ?purge=true |