support Contact Support | system status System Status

Ooyala-Video Cloud Ingestion Adapter: Ingesting with the Backlot API

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.

Ingestion via Backlot API
Ingestion via Backlot API

If you want to ingest content using the Backlot API, see:

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:
  1. Create the asset with basic properties
  2. Retrieve the "uploading URLs" from the system
  3. 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

Supported Formats
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

Page last updated on 19 Mar 2020