Page Contents

    Images and the Dynamic Ingest API

    This topic explains how to capture or ingest images for a video.

    Introduction

    You can ingest two categories of images:

    • Primary/default poster and thumbnail images, which are defined in the request body as poster and thumbnail objects (field and syntax details are below)
    • Multilingual variant images, which are defined in an images array of objects (field and syntax details are below)

    The multilingual variant images can be of six types:

    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 tables below provide specifications for images.

    Primary Image Details
    Type Format Aspect Ratio (W/H) Minimum Width (pixels)
    Poster png or jpg 16:9 or 4:3 640
    Thumbnail png or jpg 16:9 or 4:3 160
    Multilingual Variant Image Details
    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 primary poster and thumbnail images to your videos using the Dynamic Ingest API:

    • Capture images at the mid-point of the video during transcoding (currently this applies to poster and thumbnail images. Other types must be ingested). Capturing images for the primary poster and thumbnail can be used along with ingested images for multilingual variants.
    • Ingest your own images, either at the same time you ingest the video, or separately. Note that if you ingest images after ingesting the video, you must wait for the video processing to complete before ingesting the images.

    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

    As noted above, primary poster and thumbnail images are specified as top-level objects in the request body. Multilingual variant images in the ingest request body are specified as an array of objects. The object properties are detailed in the following tables.

    Primary Poster and Thumbnail Images
    Property Description Type Required Example
    url Public URL where the image can be retrieved String http://some.site.com/images/celtic-lullaby-large.png
    width Width of the image in pixels Number 1920
    Height Height of the image in pixels Number 1080
    Multilingual Image Object Properties
    Property Description Type Required 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); if not included, the default language for the account will be used. string
    variant The type for this image: poster | thumbnail | portrait | square | wide | ultra-wide string wide
    height number 2160
    width number 3840

    Sample request body

    The sample request body below includes the image fields only. Other ingest fields can be included as well.

    {
			"poster": {
				"url": "http://some.site.com/images/celtic-lullaby-large.png",
				"width": 1400,
				"height": 1400
			},
			"thumbnail": {
				"url": "http://some.site.com/images/celtic-lullaby-large.png",
				"width": 160,
				"height": 90
			},
	    "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
        }
      ]
    }
    Sample response

    Below is a response to a CMS API Get Video Images request. See Retrieving image data below.

    {
  "thumbnail.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/5b593403-01a7-4a18-978e-cad13647cf99/292x108/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/5b593403-01a7-4a18-978e-cad13647cf99/292x108/match/image.jpg",
        "height": 108,
        "width": 292
      }
    ]
  },
  "ultra-wide.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/48900952-8e0e-4fc6-bd4f-116809195ab7/2000x857/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/48900952-8e0e-4fc6-bd4f-116809195ab7/2000x857/match/image.jpg",
        "height": 857,
        "width": 2000
      }
    ]
  },
  "wide.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/111fafb1-d754-49a9-9fc7-04a5637bb3d0/2000x1125/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/111fafb1-d754-49a9-9fc7-04a5637bb3d0/2000x1125/match/image.jpg",
        "height": 1125,
        "width": 2000
      }
    ]
  },
  "portrait.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/d6c605ed-11db-45a1-a7a9-beeb7b4ead1d/500x750/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/d6c605ed-11db-45a1-a7a9-beeb7b4ead1d/500x750/match/image.jpg",
        "height": 750,
        "width": 500
      }
    ]
  },
  "poster.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/35d3f294-b62e-46e5-874e-c0c85846d80a/1920x1080/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/35d3f294-b62e-46e5-874e-c0c85846d80a/1920x1080/match/image.jpg",
        "height": 1080,
        "width": 1920
      }
    ]
  },
  "square.en": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/1f719d8b-ebe9-4f6a-b5f1-8906b220554f/500x500/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/1f719d8b-ebe9-4f6a-b5f1-8906b220554f/500x500/match/image.jpg",
        "height": 500,
        "width": 500
      }
    ]
  },
  "poster": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/6c9b5fc6-3368-47c5-98a5-a5878224fe5b/1400x1400/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/6c9b5fc6-3368-47c5-98a5-a5878224fe5b/1400x1400/match/image.jpg",
        "height": 1400,
        "width": 1400
      }
    ]
  },
  "thumbnail": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/b56eee50-f593-4d0d-be15-42d5c5c147af/160x90/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/b56eee50-f593-4d0d-be15-42d5c5c147af/160x90/match/image.jpg",
        "height": 90,
        "width": 160
      }
    ]
  },
  "ultra-wide.hi": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/48b1cfee-8579-4d48-9824-93ea2e1cce22/3840x1646/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/48b1cfee-8579-4d48-9824-93ea2e1cce22/3840x1646/match/image.jpg",
        "height": 1646,
        "width": 3840
      }
    ]
  },
  "wide.fr": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/45bf1048-d3fa-4ad3-89f1-1df362b60264/2560x1440/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/45bf1048-d3fa-4ad3-89f1-1df362b60264/2560x1440/match/image.jpg",
        "height": 1440,
        "width": 2560
      }
    ]
  },
  "portrait.es": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/89581e27-38b7-4b1b-85c6-fc624331a72b/800x1200/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/89581e27-38b7-4b1b-85c6-fc624331a72b/800x1200/match/image.jpg",
        "height": 1200,
        "width": 800
      }
    ]
  },
  "square.de": {
    "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/12819ec8-4da6-42ae-a67f-aed0424b8d51/570x570/match/image.jpg",
    "sources": [
      {
        "src": "https://cf-images.us-east-1.prod.boltdns.net/v1/static/3676484086001/4fb9012e-7b20-4744-9fff-512634d7b2a5/12819ec8-4da6-42ae-a67f-aed0424b8d51/570x570/match/image.jpg",
        "height": 570,
        "width": 570
      }
    ]
  }
}

    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.

    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://some.site.com/videos/mp4/Bird_Titmouse.mp4" },
        "profile": "multi-platform-standard-static",
        "capture-images": true
      }

    Images in ingest profiles

    For poster and thumbnail images only, you must include image renditions in the ingest profile. This is for auto-capture, whether you use it when you ingest the video or decide to later when transcoding it. Image renditions are included in all standard ingest profiles, so this section applies only to custom 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 renditions:

    "images": [
	{
		"label": "square",
		"height": 500,
		"width": 500
	},
	{
		"label": "ultra-wide",
		"height": 1714,
		"width": 4000
	},
	{
		"label": "wide",
		"height": 2250,
		"width": 4000
	},
	{
		"label": "portrait",
		"height": 3000,
		"width": 2000
	},
	{
		"label": "thumbnail",
		"height": 90,
		"width": 160
	},
	{
		"label": "poster",
		"height": 1080,
		"width": 1920
	}
]

    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.
    • 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.
    Page last updated on 03 Aug 2022