Create And Upload MediaObjects

Create a MediaObject and upload its native media

When uploading a file via the Limecraft Flow UI in the browser, a MediaObject will be created and the bytes uploaded will be assumed to represent the native media of the MediaObject. This section explains the steps involved in this process.

Create a MediaObject

We start the upload by doing a POST call and passing it at least the name, size and fileName properties of the file we want to upload.

POST /production/{prId}/mo

{
    "name": "My super clip",
    "size": 184915, // this is in bytes
    "fileName": "1.mp4", // name of the file with a relevant path to it
}

In the resulting object, you will find location parameter, which can be used to do the actual upload of the clip. After a successful upload, the user finishes up by sending the close upload call.

The resulting object also contains a workflowId parameter, which is the id of the Ingest workflow which will process the media once it is uploaded.

Send data

PUT {{uploadLocation}}

The call in Create a MediaObject returned a JSON object which had a location field. The PUT in this section will send bytes to that location.

Close the upload

POST /production/{prId}/mo/{id}/close

This API call will consider the upload to be finished.

Details
Description

This will automatically trigger the default ingest workflow.

Parameters
Path Parameters
Name Description Required Type

prId

ID of the production.

Long

id

ID of the MediaObject.

Long

Body Parameters
Name Description Required Type

CloseRequest

CloseRequest

CloseRequest

Field Name Required Type Description Format

skipIngest

Boolean

skipVerification

Boolean

Return Type

MediaObject

Field Name Required Type Description Format

annotations

List of Annotation

created

Date

The time when this resource was created

date-time

createdBy

String

The request or process that created this resource

createdByShareId

Long

int64

createdBySharedUserId

Long

int64

creatorId

Long

The id of the user who created this resource

int64

deleted

Date

date-time

duration

Long

int64

durationSeconds

Double

double

growing

Boolean

id

Long

The id of this resource

int64

keyFrame

Long

int64

lastUpdated

Date

The time when this resource was last updated

date-time

mediaObjectInstances

List of MediaObjectInstance

modifiedBy

String

The request or process responsible for the last update of this resource

name

String

objectType

String

The data model type or class name of this resource

packageId

Long

int64

productionId

Long

int64

proxyOnline

Boolean

sampleRate

SampleRate

timecode

SMPTETimePoint

timecodeFrames

Long

int64

tracks

List of MediaObjectTrack

type

String

Enum: IMAGE, DOCUMENT, PENDING, AUDIO, VIDEO, SNIPPET, PACKAGE,

umid

String

version

Long

The version of this resource, used for Optimistic Locking

int64

wfr

List of MediaObjectWorkflowReport

workflowId

String

Content Type
  • application/json

Responses
Table 1. http response codes
Code Description Datatype

201

The request was successful.

MediaObject

403

The user needs LIBRARY_UPLOAD or SharePermission.UPLOAD rights.

ForbiddenError

404

The production or media object was not found.

NotFoundError

412

The upload was not complete.

IncompleteUploadError

Closing the upload tells the API it should no longer expect more bytes to come in. The file is complete. This will usually start the Ingest workflow.

Wait for the Ingest workflow to finish

After the upload completes, the Ingest workflow will start processing the uploaded data. Its type, duration and other media properties are detected, versions are created which can be visualized in a browser, etc. Before continuing with the MediaObject, it is advised to wait for the Ingest workflow to complete.

For more info on workflows, please refer to the Workflow section.

GET /production/{prId}/{alias}/{id}/progress

This is a generic workflow progress monitor call, which can be used to monitor the ingest workflow in particular, but all other workflows as well.

Details
Description

Wait for the given workflow to finish.

Parameters
Path Parameters
Name Description Required Type

alias

Either workflow or workflowReport. Both are aliases of each other.

String

prId

ID of the production.

Long

id

ID of the workflow.

String

Return Type

String

Content Type
  • application/json

Responses
Table 2. http response codes
Code Description Datatype

200

The request was successful.

String

403

The user needs PRODUCTION_VIEW rights.

ForbiddenError

404

The production or workflow was not found.

NotFoundError

Remember that the Create a MediaObject call returned a workflowId field on its response, which is the id of the workflow we want to wait for.

Create a placeholder MediaObject without uploading media

It is also possible to only create the MediaObject, without uploading any media. We again do the same POST call, but now we do not pass the fileName and size parameters. The API interprets this as "I shouldn’t expect an upload for this".

A simple placeholder

POST /production/{prId}/mo

{
  "name": "My super clip"
}
POST /production/{prId}/mo

This API call creates a placeholder or prepares for an upload depending on the presence of the fileName/size properties.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

ID of the production.

Long

Body Parameters
Name Description Required Type

MediaObjectRequest

Media object.

MediaObjectRequest

MediaObjectRequest

Field Name Required Type Description Format

acceptedType

String

accessToken

String

annotations

List of object

attachToEdlId

Long

int64

attachToEoId

Long

int64

circled

Boolean

clipMetadata

Object

cloud

Boolean

collections

List of object

content

String

created

Date

The time when this resource was created

date-time

createdBy

String

The request or process that created this resource

createdByShareId

Long

int64

createdBySharedUserId

Long

int64

creatorId

Long

The id of the user who created this resource

int64

customFields

CustomFields

data

Boolean

deleted

Date

date-time

description

String

duration

Long

int64

durationSeconds

Double

double

enableHDProxy

Boolean

enableProxy

Boolean

enableShot

Boolean

enableSpeaker

Boolean

enableSpeech

Boolean

enableStitch

Boolean

fileName

String

forceOverwrite

Boolean

growing

Boolean

hash

String

id

Long

The id of this resource

int64

isCloud

Boolean

isData

Boolean

isProxy

Boolean

keyFrame

Long

int64

label

String

language

String

lastUpdated

Date

The time when this resource was last updated

date-time

loggingStatus

String

Enum: NOT_STARTED, EDITING, COMPLETED,

markForRemoval

Boolean

matchingType

String

Enum: NONE, VIDEO_ONLY, AUDIO_ONLY, FULL,

mediaInfo

Object

mediaInfoObject

MediaInfo

mediaInfoProxy

String

mediaInfoString

String

mediaObjectId

Long

int64

mediaObjectInstanceId

Long

int64

mediaObjectInstances

List of object

modifiedBy

String

The request or process responsible for the last update of this resource

name

String

nonPreferred

Boolean

objectType

String

The data model type or class name of this resource

origin

String

packageId

Long

int64

prefix

String

productionId

Long

int64

proxy

Boolean

proxyOnline

Boolean

proxyProfile

String

rating

Double

double

rawPath

String

resolveMethod

String

Enum: FINGERPRINT, FINGERPRINT_2, NAME, CRITERIA,

reviewStatus

String

sampleRate

SampleRate

screenshot

List of ByteArray

byte

screenshotMimeType

String

size

Long

int64

smallHash

String

source

String

subtitlingStatus

String

Enum: NOT_STARTED, EDITING, COMPLETED, AUTOMATIC_STARTED, AUTOMATIC_COMPLETED, AUTOMATIC_FAILED,

subtitlingStatuses

SubtitlingStatusMap

synchronizeOptions

Map of SynchronizeConfiguration

systemFields

CustomFields

tags

Set of string

timecode

SMPTETimePoint

timecodeFrames

Long

int64

tracks

List of MediaObjectTrack

transcriptionStatus

String

Enum: NOT_STARTED, EDITING, COMPLETED, AUTOMATIC_STARTED, AUTOMATIC_COMPLETED, AUTOMATIC_FAILED,

transcriptionStatuses

TranscriptionStatusMap

type

String

Enum: IMAGE, DOCUMENT, PENDING, AUDIO, VIDEO, SNIPPET, PACKAGE,

umid

String

url

String

version

Long

The version of this resource, used for Optimistic Locking

int64

wfr

List of MediaObjectWorkflowReport

workflowId

String

Return Type

FileUploadResponse

The response you get when creating a new upload

Field Name Required Type Description Format

location

String

mediaObjectAnnotation

MediaObjectAnnotation

mediaObjectAnnotationId

Long

int64

mediaObjectId

Long

int64

mediaObjectInstances

List of MediaObjectInstance

position

Long

int64

syncReport

SyncReport

uploadId

String

Content Type
  • application/json

Responses
Table 3. http response codes
Code Description Datatype

201

The request was successful.

FileUploadResponse

402

The user is not allowed to create more resources, quota exceeded.

ForbiddenError

403

The user needs LIBRARY_UPLOAD or SharePermission.UPLOAD rights.

ForbiddenError

404

The production was not found.

NotFoundError

If you like, you can send a thumbnail image to use for this clip using this call:

PUT /production/{prId}/mo/{id}/screenshot

This call allows the user to upload a custom screenshot to a clip, acting as its thumbnail on Limecraft Flow.

Details
Description
Parameters
Path Parameters
Name Description Required Type

prId

ID of the production.

Long

id

ID of the MediaObject.

Long

Body Parameters
Name Description Required Type

ScreenshotUpdateRequest

ScreenshotUpdateRequest

ScreenshotUpdateRequest

Field Name Required Type Description Format

screenshot

List of ByteArray

byte

screenshotType

String

Return Type

MediaObject

Field Name Required Type Description Format

annotations

List of Annotation

created

Date

The time when this resource was created

date-time

createdBy

String

The request or process that created this resource

createdByShareId

Long

int64

createdBySharedUserId

Long

int64

creatorId

Long

The id of the user who created this resource

int64

deleted

Date

date-time

duration

Long

int64

durationSeconds

Double

double

growing

Boolean

id

Long

The id of this resource

int64

keyFrame

Long

int64

lastUpdated

Date

The time when this resource was last updated

date-time

mediaObjectInstances

List of MediaObjectInstance

modifiedBy

String

The request or process responsible for the last update of this resource

name

String

objectType

String

The data model type or class name of this resource

packageId

Long

int64

productionId

Long

int64

proxyOnline

Boolean

sampleRate

SampleRate

timecode

SMPTETimePoint

timecodeFrames

Long

int64

tracks

List of MediaObjectTrack

type

String

Enum: IMAGE, DOCUMENT, PENDING, AUDIO, VIDEO, SNIPPET, PACKAGE,

umid

String

version

Long

The version of this resource, used for Optimistic Locking

int64

wfr

List of MediaObjectWorkflowReport

workflowId

String

Content Type
  • application/json

Responses
Table 4. http response codes
Code Description Datatype

200

The request was successful.

MediaObject

403

The user needs LIBRARY_UPDATE_METADATA rights.

ForbiddenError

404

The production or media object was not found.

NotFoundError

Synchronize clips

Clips can also be synchronized with Limecraft Flow. For more info on that one, please check out this page.