/sapi/mediaclip

Contents

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 endpoint has limited support for managing related entities. Related entities can be managed using their own endpoints.

Base URL: https://yourcompanyname.bbvms.com/sapi/mediaclip

All requests must be authenticated. See SAPI Authentication for details. All request bodies must use Content-Type: application/json.

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

Editorial fields (read/write)

Property	Type	Description
title	string	Mediaclip title.
description	string	Mediaclip description.
deeplink	string	A URL pointing to the web page where the mediaclip is featured (the clip’s canonical page).
copyright	string	Copyright notice for the mediaclip.
author	string	Author or creator of the mediaclip.
status	string	draft or published. A published mediaclip is publicly available.
usetype	string	editorial or commercial. Commercial is only used for creatives or logos.
fitmode	string	For video only. Overrides the playout fitmode configuration. Valid values: smart, fitboth, fitvertical, fithorizontal, cover, stretch, native. See the fitmode article for details.
originalfilename	string	The original filename of the uploaded file.
length	integer	Duration in seconds.
cat	array	A list of category tags assigned to the mediaclip.
chapters	array	A list of chapter markers. Each chapter has an id, title, and timeOffset (in seconds).
sourceid	string	An external unique identifier linking to a source system. Can be set on initial ingest; read-only after that.

System fields (read-only)

Property	Type	Description
id	string	Unique identifier of the mediaclip.
type	string	Fixed value: MediaClip.
mediatype	string	The type of media: audio, video, image, or document.
sourcetype	string	Indicates whether the clip is on-demand or a live stream: on_demand or live.
publicationid	string	The ID of the publication this mediaclip belongs to.
createddate	string	ISO 8601 date and time the mediaclip was created.
updateddate	string	ISO 8601 date and time the mediaclip was last updated.
publisheddate	string	ISO 8601 date and time the mediaclip’s status was first set to published.
createdBy	string	Username or email address of the user who created the mediaclip.
updatedBy	string	Username or email address of the user who last updated the mediaclip.
views	integer	Total all-time view count.
width	integer	Pixel width of the video.
height	integer	Pixel height of the video.
dar	string	Display aspect ratio (e.g. 16:9).
originalWidth	integer	Pixel width of the original uploaded file.
originalHeight	integer	Pixel height of the original uploaded file.
src	string	File URI of the primary source file.
gendeeplink	string	Auto-generated deeplink URL, if configured.
hasJobs	boolean	true if there are active transcoding jobs for this clip.
transcodingFinished	boolean	true when transcoding is complete.

Related entities (read-only)

Property	Type	Description
assets	array	A list of transcoded renditions. Writable only on creation; manage renditions after creation via the /sapi/mediaasset endpoint.
thumbnails	array	A list of thumbnail images. Each thumbnail has: src (file URI), main (boolean; true for the selected thumbnail), width and height (in pixels), and optional crops.
subtitles	array	References to subtitle tracks. Manage via the /sapi/subtitle endpoint.
transcript	string	Transcript text, if available.
exports	array	References to social media exports, if any.
timelines	array	References to linked timeline objects. Manage via the /sapi/timeline endpoint.
audiotracks	array	References to linked audiotrack objects. Manage via the /sapi/audiotrack endpoint.

2.0 | Create/Update

Both creating and updating a mediaclip use a PUT request. The presence or absence of an id in the request body determines whether a new clip is created or an existing one is updated.

2.1 | Create

PUT /sapi/mediaclip

Omit the id property to create a new mediaclip. The response contains the complete created mediaclip object.

Example request: create a new mediaclip

curl -X PUT "https://yourcompanyname.bbvms.com/sapi/mediaclip" \
  -H "rpctoken: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MediaClip",
    "mediatype": "video",
    "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.",
    "copyright": "Blue Billywig",
    "author": "Billy",
    "status": "published"
  }'

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.

2.2 | Update

PUT /sapi/mediaclip/{id}

PUT /sapi/mediaclip?q=sourceid:”{sourceid}”

Include the id property to update an existing mediaclip. Alternatively, query by source ID. Only the properties included in the request body are updated. The response contains the complete updated mediaclip object.

Example request: update an existing mediaclip

curl -X PUT "https://yourcompanyname.bbvms.com/sapi/mediaclip/1234567" \
  -H "rpctoken: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "MediaClip",
    "id": "1234567",
    "title": "The perfect coffee: updated",
    "status": "published"
  }'

3.0 | Retrieve List

GET /sapi/mediaclip

Retrieves a list of mediaclips. By default, the 50 most recently created clips are returned.

Example request: retrieve a list of mediaclips

curl -X GET "https://yourcompanyname.bbvms.com/sapi/mediaclip?limit=10&sort=title+asc" \
  -H "rpctoken: {api_key}"

3.1 | Parameters

Parameter	Type	Description	Example
q	string	A query to filter results. See 3.2 Query Syntax below.	?q=title:”perfect coffee”
sort	string	Sort field and direction. Default: id desc.	?sort=title asc
limit	integer	Number of mediaclips to return. Default: 50. Maximum: 1000.	?limit=100
offset	integer	Number of results to skip, for pagination.	?offset=100

3.2 | Query Syntax

The q parameter uses Solr query syntax. The following patterns are supported:

Pattern	Description	Example
Field match	Match an exact value in a specific field	?q=title:”perfect coffee”
Source ID match	Retrieve a clip by its external source ID	?q=sourceid:”my-unique-id”
Date range	Match clips within a date range (ISO 8601, inclusive)	?q=createddate:[2023-01-01T00:00:00Z TO 2023-12-31T23:59:59Z]
Status filter	Filter by publication status	?q=status:published

3.3 | Response

A successful request returns a 200 OK response with the following envelope:

Example list response

{
   "type": "MediaClipList",
   "numfound": 142,
   "offset": 0,
   "limit": 50,
   "count": 50,
   "items": [
      { /* mediaclip object */ },
      { /* mediaclip object */ }
   ]
}

Field	Type	Description
type	string	Fixed value: MediaClipList.
numfound	integer	Total number of matching clips across all pages. Use with limit and offset to build pagination.
offset	integer	The offset used in the current request.
limit	integer	The limit used in the current request.
count	integer	The number of clips returned in the current response.
items	array	The list of mediaclip objects.

4.0 | Retrieve

GET /sapi/mediaclip/{id}

GET /sapi/mediaclip?q=sourceid:”{sourceid}”

Retrieves a single mediaclip object. A successful request returns a 200 OK response with the full mediaclip object.

Example request: retrieve a single mediaclip

curl -X GET "https://yourcompanyname.bbvms.com/sapi/mediaclip/4471615" \
  -H "rpctoken: {api_key}"

5.0 | Delete

DELETE /sapi/mediaclip/{id}

DELETE /sapi/mediaclip?q=sourceid:”{sourceid}”

Moves a mediaclip to the trash. To permanently delete the clip, use the purge parameter (see below). A successful request returns a 200 OK response.

Example request: delete a mediaclip

# Move to trash
curl -X DELETE "https://yourcompanyname.bbvms.com/sapi/mediaclip/4471615" \
  -H "rpctoken: {api_key}"

# Permanently delete
curl -X DELETE "https://yourcompanyname.bbvms.com/sapi/mediaclip/4471615?purge=true" \
  -H "rpctoken: {api_key}"

5.1 | Parameters

Parameter	Type	Description	Example
purge	boolean	Permanently deletes the mediaclip. Without this parameter, the clip is moved to the trash.	?purge=true

6.0 | HTTP Status Codes

Code	Meaning	When it occurs
200 OK	Success	Returned for all successful requests (retrieve, create, update, delete).
400 Bad Request	Invalid request	The request body is malformed or contains invalid values.
401 Unauthorized	Authentication failed	The rpctoken is missing or invalid.
403 Forbidden	Insufficient permissions	The authenticated user does not have permission to perform this action.
404 Not Found	Resource not found	No mediaclip exists with the given ID or query.
409 Conflict	Validation error	The request is valid but violates a business rule (e.g. a required field is missing). The response body includes a violations array with details.

Example error response (409)

{
   "type": "Response",
   "code": 409,
   "error": true,
   "violations": [
      "title is required"
   ]
}

Tagged: mediaclip sapi

Was this article helpful?

Yes No

Contact Support

Can't find the answer you're looking for?

Contact Support