Images and the Dynamic Ingest API

Introduction

There are two different ways to add poster and thumbnail images to your videos using the Dynamic Ingest API:

• Capture images at the mid-point of the video during transcoding
• Ingest your own images, either at the same time you ingest the video, or separately

Setup

The setup for Dynamic Ingest requests is the same, whether you are ingesting a video, images, a WebVTT file, or all of these:

Request URL

    https://ingest.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/ingest-requests

Authentication

Authentication requires an access token passed as a Bearer token in an Authorization header:

    Authorization: Bearer {access_token}

Note on S3

If your images will be pulled from a protected S3 bucket, you will need to set a bucket policy to allow Video Cloud to access the files. See Using Dynamic Ingest with S3 for details.

Capture images

During transcoding, Video Cloud can capture a snapshot from the video at the midpoint and save this as poster (video still) and thumbnail images.

For custom renditions, image capture requires that two special renditions be added to the ingest profile that you are using. The new renditions must have the following properties:

Here is sample data for the two renditions:

    {
      "media_type": "image",
      "format": "jpg",
      "label": "poster",
      "width": 1280,
      "height": 720
    },
    {
      "media_type": "image",
      "format": "jpg",
      "label": "thumbnail",
      "width": 160,
      "height": 90
    }

You should also set the capture-images flag in your request data to true, but this is the default value if the selected profile includes image renditions. (If there are no image renditions in the profile, the default for capture-images is false.)

Sample request data:

    {
      "master": { "url": "http://learning-services-media.brightcove.com/videos/mp4/Bird_Titmouse.mp4" },
      "profile": "multi-platform-standard-static",
      "capture-images": true
    }

Sample request data for adding an image after the video has been ingested

    {
        "profile": "multi-platform-standard-static",
        "thumbnail": {
            "url": "http://bcls@solutions.brightcove.com/bcls/assets/images/great-blue-heron-thumbnail.png",
            "width": 160,
            "height": 90
        },
        "poster": {
            "url": "http://bcls@solutions.brightcove.com/bcls/assets/images/great-blue-heron-poster.png",
            "width": 1280,
            "height": 720
        }
    }

Ingest images

You can also include a custom poster and thumbnail for your video (or add them) by referencing their URLs in the JSON you use for the Dynamic Ingest request body:

    {
        "poster": {
            "url": "http://learning-services-media.brightcove.com/images/for_video/Water-In-Motion-poster.png",
            "width": 1280,
            "height": 720
        },
        "thumbnail": {
            "url": "http://learning-services-media.brightcove.com/images/for_video/Water-In-Motion-thumbnail.png",
            "width": 160,
            "height": 90
        }
    }

Automatic resizing

When you add custom poster and/or thumbnail images via Studio or the Dynamic Ingest API, by default Video Cloud will resize these to match the image sizes defined in the default Ingest Profile for the account.

Override auto-resizing

If you want to override this behavior and have Video Cloud retain actual image dimensions, follow these steps:

1. Create a new custom ingest profile for your account (or modify an existing custom profile)
2. Include image renditions for the post and thumbnail that have exactly these width and height values:

       {
         "media_type": "image",
         "format": "jpg",
         "label": "poster",
         "width": 9999,
         "height": 9999
       },
       {
         "media_type": "image",
         "format": "jpg",
         "label": "thumbnail",
         "width": 9999,
         "height": 9999
       }

3. Make this the default profile for the account if you always want images to be saved with their original sizes.

Now when you add custom images via Studio or Dynamic Ingest, they will have the original dimensions of the source images.

Limitations

• The ingestion system does not allow concurrent jobs on the same video. Therefore, if you attempt to upload images while the video is being ingested or retranscoded, the image upload will fail.