Images and the Dynamic Ingest API

Introduction

You can ingest images of six types to associate with Video Cloud videos:

poster: The poster image is displayed in the Brightcove Player before the user plays the video. It is typically a frame captured from the video, but does not have to be.
thumbnail: The thumbnail image is displayed in playlists, end screens, and so forth. It is typically a frame captured from the video, but does not have to be.
portrait: An image used typically as a poster in portrait mode on phones and other devices. Required for Brightcove Beacon. Details of the specification are in the table below.
square: An image used typically as a channel logo or in grid displays. Required for Brightcove Beacon. Details of the specification are in the table below.
wide: An image used typically as a poster in landscape mode on phones and other devices. Required for Brightcove Beacon. Details of the specification are in the table below.
ultra-wide: An image used typically as a poster on ultra-wide displays such as TVs. Required for Brightcove Beacon. Details of the specification are in the table below.

Specifications

The table below provides specifications for images.

Image Details Table
Type	Format	Aspect Ratio (W/H)	Minimum Width (pixels)
poster	jpg or png	match video	none
thumbnail	jpg or png	match video	none
portrait	jpg or png	0.6667 (2x3)	500
square	jpg or png	1.0 (1x1)	500
wide	jpg or png	1.7778 (16x9)	2000
ultra-wide	jpg or png	2.3333 21x9	2000

There are two different ways to add basic 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.

Multilingual variants

You can provide different versions of images to be used for different languages. This is handled by Brightcove Beacon for Brightcove Beacon apps. General implementation in the Brightcove Player currently requires custom development.

The language for an image is specified in the language property detailed in the next section.

Ingest images

Here are the details of adding custom images for your video.

Image fields in the request body

Images in the ingest request body are specified as an array of objects. The object properties are detailed in the following table.

Image Object Properties
Property	Description	Type	Example
`url`	A url that Video Cloud can retrieve the image from	string	`https://mysite.com/videos/video123/images/poster.png`
`language`	Language code for the image from the subtags in http://www.iana.org/assignments/language-subtag-registry/language-subtag-registry (default can be set for the account by contacting Brightcove Support)	string
`variant`	The type for this image: `poster` \| `thumbnail` \| `portrait` \| `square` \| `wide` \| `ultra-wide`	string	`wide`
`height`		number	`2160`
`width`		number	`3840`

{
      "images":[
        {
            "url":"https://apis.support.brightcove.com/assets/images/dynamic-ingest/test-images/poster.jpg",
            "variant": "poster",
            "height": 1080,
            "width": 1920
        },
        {
            "url":"https://apis.support.brightcove.com/assets/images/dynamic-ingest/test-images/thumbnail.jpg",
            "variant": "thumbnail",
            "height": 108,
            "width": 292
        },
        {
            "url":"https://apis.support.brightcove.com/assets/images/dynamic-ingest/test-images/square.jpg",
            "language": "de",
            "variant": "square",
            "height": 570,
            "width": 570
        },
        {
            "url":"https://apis.support.brightcove.com/assets/images/dynamic-ingest/test-images/wide.jpg",
            "language": "fr",
            "variant": "wide",
            "height": 1440,
            "width": 2560
        },
        {
            "url":"https://apis.support.brightcove.com/assets/images/dynamic-ingest/test-images/portrait.jpg",
            "language": "es",
            "variant": "portrait",
            "height": 1200,
            "width": 800
        },
        {
            "url":"https://apis.support.brightcove.com/assets/images/dynamic-ingest/test-images/ultra-wide.jpg",
            "language": "hi",
            "variant": "ultra-wide",
            "height": 1646,
            "width": 3840
        }
      ]
    }

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.

Note that resizing and padding are the only modifications Video Cloud or Brightcove Beacon. Images are never cropped.

Override auto-resizing

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

Create a new custom ingest profile for your account (or modify an existing custom profile)

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
    }

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.

Capture images

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

For custom ingest profiles, image capture requires that two special renditions be added to the ingest profile that you are using. See Images in ingest profiles below.

You should also set the capture-images flag in your request data to true if you want the poster and thumbnail to be captured from the video during transcoding, 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
      }

Note that you must include the profile field and specify a profile with image renditions (all the standard profiles have them).

Images in ingest profiles

Here are details of how image renditions are specified in ingest profiles.

Property	Value
`media_type`	"image"
`label`	"poster" or "thumbnail" (you need a rendition for each)
`format`	"png" or "jpg"
`width`	number (pixels)
`height`	number (pixels)

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 can specify png or jpg as the format - currently captured images are always output as jpg images.

            {
                "height": 360,
                "label": "poster",
                "width": 480,
                "media_type": "image",
                "format": "png"
            },
            {
                "height": 90,
                "label": "thumbnail",
                "width": 160,
                "media_type": "image",
                "format": "png"
            }

Retrieving image data

You can retrieve image data using the CMS API.

The CMS API will return the image data in a GET request to https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id} or, if you only want the image data, to https://cms.api.brightcove.com/v1/accounts/{account_id}/videos/{video_id}/images

In either case, the image data in the response will look like this:

{
  "thumbnail": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/main/160x90/20s629ms/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/main/160x90/20s629ms/match/image.jpg",
        "height": 90,
        "width": 160
      }
    ]
  },
  "poster": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/main/1280x720/20s629ms/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/jit/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/main/1280x720/20s629ms/match/image.jpg",
        "height": 720,
        "width": 1280
      }
    ]
  },
  "portrait.es": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/bac8717a-43db-4fa8-a6f0-189c80ee4c4e/800x1200/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/bac8717a-43db-4fa8-a6f0-189c80ee4c4e/800x1200/match/image.jpg",
        "height": 1200,
        "width": 800
      }
    ]
  },
  "thumbnail.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/0ce2da4d-ca36-469b-9024-0273d79feeeb/292x108/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/0ce2da4d-ca36-469b-9024-0273d79feeeb/292x108/match/image.jpg",
        "height": 108,
        "width": 292
      }
    ]
  },
  "poster.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/a7cb150d-c84a-48e0-9469-5b4ce80fba53/1920x1080/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/a7cb150d-c84a-48e0-9469-5b4ce80fba53/1920x1080/match/image.jpg",
        "height": 1080,
        "width": 1920
      }
    ]
  },
  "square.de": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/22209955-e136-4f17-914c-e19ec4c58886/570x570/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/22209955-e136-4f17-914c-e19ec4c58886/570x570/match/image.jpg",
        "height": 570,
        "width": 570
      }
    ]
  },
  "ultra-wide.hi": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/72fd489f-d978-44ba-8d04-1e33c7c36cef/3840x1646/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/72fd489f-d978-44ba-8d04-1e33c7c36cef/3840x1646/match/image.jpg",
        "height": 1646,
        "width": 3840
      }
    ]
  },
  "wide.fr": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/4405a5d5-8b9e-4c2b-be71-cf4e2c153e87/2560x1440/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/57838016001/ee705e97-3fb5-409c-99d8-703e9f57bd0a/4405a5d5-8b9e-4c2b-be71-cf4e2c153e87/2560x1440/match/image.jpg",
        "height": 1440,
        "width": 2560
      }
    ]
  }
}

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.
Currently, image data for the wide, square, portrait, and ultra-wide variants is returned only by the CMS API, not by Playback API video requests.