This topic covers using the Backlot API to ingest content to Video Cloud.
Introduction
Use the Backlot API to programmatically upload content into Video Cloud. This approach enables you to integrate your content management system (CMS) or workflows directly with the Video Cloud platform.
You can use the Backlot API to programmatically upload and manage videos, thumbnails, and closed caption files.
If you want to ingest content using the Backlot API, see:
- Video and Audio Assets (for videos and thumbnails)
- Working with Closed Captions
The primary call used to upload files (called "assets") is the /v2/assets route.
Note: Do not add a video with a null external_id, that is, an external_id with no value ("") or a value of "null". Such null external IDs cannot be searched for later.
Video and Audio Assets
When you upload a video to Ooyala, Ooyala automatically transcodes it using the settings specified for your account and makes the videos available for playback through your player.
We recommend that you upload videos to Ooyala in H.264, but we also support many commonly used codecs.
To create new video or audio assets:
- Create the asset with basic properties
- Retrieve the "uploading URLs" from the system
- For each "uploading URL", put the appropriate file chunk to the system
Note: When you upload each chunk, do not sign the request, as you would other requests. Simply PUT the chunk contents to the exact URLs. These URLs have already been signed for you.
Get Uploading URLs for Newly Created Asset
[GET]/v2/assets/{asset_id}/uploading_urls
Note: When you upload each chunk, do not sign the request, as you would other requests. Simply PUT the chunk contents to the exact URLs. These URLs have already been signed for you.
Set Uploading Status
[PUT] /v2/assets/{asset_id}/upload_status
{
"status":"uploaded"
}
View Streams for a Video
The term streams in this context means the internal-to-Ooyala processes that are started by the system to transcode your videos.
Note: You cannot control or manipulate these streams; they are controlled by the system. You can only view their names, not change them.
[GET]/v2/assets/{asset_id}/streams
View Source Files for a Video
[GET]/v2/assets/{asset_id}/source_file_info
Get URLs for Autogenerated Preview Images
[GET] /v2/assets/{asset_id}/generated_preview_images
Upload Custom Preview Image
[POST]/v2/assets/{asset_id}/preview_image_files
<file_contents>
Set Primary Preview Image Configuration
Set the type of the primary preview image of an asset to one of the following:
- generated: use the autogenerated preview image
- uploaded_file: use the uploaded custom preview image
- remote_url: URL for the preview image
[PUT]/v2/assets/{asset_id}/primary_preview_image
{
"type":"generated" | "uploaded_file" | "remote_url"
}
About Metadata
An asset can have up to 100 name/value pairs of custom metadata. A name is limited to 128 characters, and its value is limited to 2,048 characters.
Examples
This example creates a video:
[POST]/v2/assets{
"name":"Honey Badger",
"file_name":"honeybadger.avi",
"asset_type":"video",
"file_size":398422,
"chunk_size":100000
}
Video Cloud returns a response similar to the following:
{
"name":"Honey Badger",
"preview_image_url":null,
"asset_type":"video",
"duration":0,
"embed_code":{embed_code},
"created_at":"2011-10-26T19:40:32+00:00",
"time_restrictions":null,
"updated_at":"2011-10-26T19:40:32+00:00",
"external_id":null,
"hosted_at":null,
"original_file_name":"honeybadger.avi",
"description":null,
"status":"uploading"
}
This example returns the uploading URLs:
[GET]/v2/assets/{asset_id}/uploading_urls
Video Cloud returns a response similar to the following:
["https://uploader-v2.ooyala.com/send?filename=EwZ2RyMjrulwSBrJMpFd7xQ6FoftMnaA/0000000000000-0000000099999&filesize=100000&expires=1314391791&signature=Jliypj/Q0c5dVu4tDFUDIjIngyDu/LGng+rCG3KNSF4",
"https://uploader-v2.ooyala.com/send?filename=EwZ2RyMjrulwSBrJMpFd7xQ6FoftMnaA/0000000100000-0000000199999&filesize=100000&expires=1314391791&signature=qOjdkomEUO7mgWDjqu9z01QrI39sxa9W0zzRXDhOR9Y",
"https://uploader-v2.ooyala.com/send?filename=EwZ2RyMjrulwSBrJMpFd7xQ6FoftMnaA/0000000200000-0000000299999&filesize=100000&expires=1314391791&signature=+bT8Jft9kvVdkYMND87BSs/VWu1r2imCNkl9v2++eTU",
"https://uploader-v2.ooyala.com/send?filename=EwZ2RyMjrulwSBrJMpFd7xQ6FoftMnaA/0000000300000-0000000398421&filesize=98422&expires=1314391791&signature=cObAITdnMHeT6/wuNCAjYABgxqdlfPaLeATOmsKxmdg" ]
This example marks the video as uploaded, which tells Video Cloud to start processing the file:
[PUT]/v2/assets/{asset_id}/upload_status
{
"status":"uploaded"
}
Video Cloud returns a response similar to the following:
{
"status": "uploaded"
}
[GET]/v2/assets/{asset_id}/source_file_info
Video Cloud returns a response similar to the following:
{
"original_file_name": lakeside.wmv,
"source_file_url":{source_url}"
"file_size": 25227886
}
Note: The URLs to the source files are signed and expire in 24 hours.
Working with Closed Captions
You can add closed captions to videos or remote asset videos via the Backlot API.
Supported Formats for Captions
| File Extension | Description |
|---|---|
| .vtt (WebVTT/) - this is the format required for HTML5 video players | WebVTT can be used for both embedded and sidecar captions in HTTP streaming formats such as HLS and DASH. |
| .TTML (formerly DXFP) - will be converted to WebVTT | TTML (Timed Text Markup Language file. Generally, a closed caption file of this type will have a .dfxp (Distribution Format Exchange Profile) extension. |
Upload Closed Captions
[PUT]/v2/assets/{asset_id}/closed_captions/{dfxp_file_content}
Get Closed Captions
[GET]/v2/assets/{asset_id}/closed_captions
Update Closed Captions
[PUT]/v2/assets/{asset_id}/closed_captions
Delete Closed Captions
[DELETE]/v2/assets/{asset_id}/closed_captions