Contact Support | System Status
Page Contents

    Overview: Dynamic Ingest API

    In this topic, you will learn how to use the Dynamic Ingest API to upload and manage video content.

    API functionality

    Brightcove's Dynamic Ingest (DI) API is based on functionality where video source files are downloaded from the customer's storage location and specified renditions of the source files are created. (There is also an option to upload your source files to a temporary location where Dynamic Ingest can access them.) The platform is cloud-centric, globally-distributed and based on modern practices to deliver best in class consistency and speed.

    Workflow overview

    A number of systems/technologies are used in the overall transcoding and storage of media. They are:

    • Content Management System (CMS) API: Creates a video object for use in the DI API
    • Zencoder: Transcodes the video creating multiple renditions
    • Amazon S3: Moves the master and renditions to storage, based on profile settings
    • Catalog: Stores requisite information associated with the video

    After initial transcoding, you have the following actions you can perform on the media:

    • Re-transcode: Create new renditions when master is present (error if master is not present)
    • Replace: Point to a new master, or replace an existing master


    When you use the DI API you will perform different operations, such as reading an ingest profile and writing ingest information to your account. The following is a complete list of operations required for DI tasks:

    • video-cloud/video/create
    • video-cloud/video/read
    • video-cloud/video/update
    • video-cloud/ingest-profiles/profile/read
    • video-cloud/ingest-profiles/account/read
    • video-cloud/ingest-profiles/account/write
    • video-cloud/ingest-profiles/profile/write
    • video-cloud/upload-urls/read

    To obtain client credentials, use the Studio admin tools or see one of the following documents:

    Best practices

    Valid source locations

    Dynamic Ingest can pull source video files from: HTTP/HTTPS or S3 - with or without authentication


    • s3://my-bucket/video.mp4

    Notes on S3

    If your videos are in a protected S3 bucket, see Using Dynamic Ingest with S3 for details on how to set up permissions for Dynamic Ingest to access your files.

    The advantages of using pull-based ingest include a simpler workflow and having a repository of your own digital masters. If this is not an option for you, however, you can also use Source File Upload to upload your videos and other assets to a temporary location from which Dynamic Ingest can access them.

    Source file names

    All input urls must properly url encoded according to RFC 3986 when being sent to Brightcove. This means that any reserved characters found in the path of the url are percent encoded (spaces being encoded to %20), and any reserved characters found in the query of the url are percent encoded (spaces being encoded to + or %20, and + being encoded to %2B).

    A pre-signed S3 (v2 contains Signature, Expires and AWSAccessKeyId, and v4 contains X-Amz-Algorithm, X-Amz-Credential, X-Amz-Date, X-Amz-Expires, X-Amz-SignedHeaders, and X-Amz-Signature) or GCS (contains Signature, Expires, and GoogleAccessId) url should already be properly encoded and can be used as is.

    Ingesting videos

    There are two API calls required for ingesting videos:

    1. Call the CMS API to create a video object in the Video Cloud system and get its id
    2. Call the DI API to provide the URL for the video source file and specify the ingest profile to be used

    A sample set of basic requests would look like the following:

    CMS API request

    HTTP method
    Request URL{account_id}/videos
    Request body
        "name": "My new video"

    The response data will include the video id , which is used in the next request.

    Ingest API request

    HTTP method
    Request URL{account_id}/videos/{video_id}/ingest-requests
    Request body
        "master": {
        "url": "http://host/master.mp4"
        "profile": "high-resolution"

    See the Quick Start for details of the API calls, and you can also see a working sample.

    For CMS API call to create the video in the Video Cloud system, see the CMS API Overview. Note that the video name is required, and that the name and any other strings included for video metadata (such as the description ) must be URI-encoded.

    Sample assets

    Brightcove Learning Services provides some sample assets you can use to experiment with in getting started with Dynamic Ingest. These assets include short videos, images, and WebVTT captions in multiple languages:

    Replace a video

    To replace a video with a new version or a new set of renditions, the Dynamic Ingest API call is exactly the same as it would be for ingesting new videos - the only difference is that you do not need to make a prior call to the CMS API to create the video object in the Video Cloud system and get an id for it. If the source video file at the specified URL is the same one originally ingested, you will simply get a new set of renditions. If the source file is new, you will be replacing the existing video. All videos will remain playable with existing renditions until retranscoding is complete.

    See the working sample here.

    Retranscode a video

    If you chose to archive a master when you ingested the video through the Dynamic Ingest API or the Studio Upload Module, then you can also retranscode the video from the master. Again the URL for the ingest request will be the same, but the request body will have the following:

        // request
        POST /v1/accounts/{account_id}/videos/{video_id}/ingest-requests
        // request body
        "master": { "use_archived_master": true },
        "profile": "videocloud-default-v1"


    You can use the Dynamic Ingest API to capture poster and thumbnail images from your video, or to add your own images. For details, see Images and the Dynamic Ingest API.

    Ingest captions

    You can also add WebVTT captions to your video or upload them for an existing video using Dynamic Ingest. For details, see Ingesting WebVTT Files.

    DRM and HLSe

    Dynamic Ingest handles videos that use any of the DRM types supported by Brightcove. HLSe is also supported.

    Archiving Renditions

    By default, all video and image renditions are automatically archived. If you want to turn archiving of renditions off, contact Brightcove Support. Note that digital masters are archived if that is specified in the ingest profile.


    You can specify a one or more callback URLs to receive notifications of the results of the ingest process. The URLs you specify should be for apps than can accept POST requests. Notifications will be sent in JSON format.

    Details of receiving and interpreting notifications can be found in Notifications: Dynamic Ingest and CMS APIs

    Page last updated on 31 Jan 2021