Product Updates | Contact Support | System Status
Page Contents

    Overview: Ingest Profiles API

    In this topic, you will get an overview of the Ingest Profiles API. The Ingest Profiles API allows you to create, retrieve, update, and delete rendition profiles for your Video Cloud account.

    Managing Ingest Profiles

    Ingest profiles are used as a specification for transcoding when you upload or re-transcode videos. You can manage these profiles using the Ingest Profiles API.

    Glossary of terms

    Profile JSON

    The term "profile JSON" below means the JSON representation of a profile object. They contain top-level profile fields and a collection of rendition objects as a list. See Standard Profiles to see the JSON for the standard profiles included in every account and Content Security (DRM and HLSe) for sample profiles that include DRM packaging.

    Profile id

    A profile id can be either the id or name top-level field in a profile. In this example (a fragment of a profile):

            "id": "5591b5ede4b0f7138939ad8c",
            "version": 4,
            "name": "screencast-1280",
            "description": "A high resolution profile optimized for screencasts with 1280 x 720 resolution.", ...

    "screencast-1280" or "5591b5ede4b0f7138939ad8c" are both valid profile ids. When you create a profile for the first time, you'll supply a profile with a name but without an id, and the response will contain the created profile including its id. You may then use either on any subsequent API call.

    Reference id

    A reference_id uniquely identifies a rendition within a profile. Reference ids are used for DRM packaging, and may be used for other purposes in the future. Aside from being unique within the profile, reference ids can be any string - it should not include spaces. We recommend using some scheme that will make it easy to identify the format of the rendition, for example: mp4_1, mp4_2, hls1, hls2, etc.

    Profile version

    A version is the revision number of a profile for an account. It is represented by a long integer value. Note: it is not quoted in the JSON representation.

    Active profile

    A profile is active if it can be used for uploads. For instance, if you update a profile, you get a new profile with an incremented version number which is active, and the old version becomes inactive.

    Standard profile

    A profile is standard if it is provided for use by Brightcove (i.e. it is not a custom profile specific to a single account).

    Default profile

    A profile is default if it's used when no profile is explicitly chosen. If you have no account configuration, or do not set a default profile in your configuration, one of the Brightcove standard profiles will be used in accordance with your account type.

    Base URL

    The service URL is:


    Authorization for the API is via Brightcove's OAuth2 implementation. You will need client credentials (a client id and a client secret) that has permissions for the following operations on your account(s):

    • video-cloud/ingest-profiles/profile/read
    • video-cloud/ingest-profiles/profile/write
    • video-cloud/ingest-profiles/account/read
    • video-cloud/ingest-profiles/account/write

    To get a client_id and client_secret, you will need to go to the OAuth UI and register an app:

    You can also get your credentials via CURL or Postman - see:

    You will use your client credentials to get access tokens that will allow you to make calls to the API. Access tokens are passed in an Authorization header:

        Authorization: Bearer {your_access_token}

    See the Oauth Section for more information.

    Maximum renditions

    The maximum number of renditions that you can define in an ingest profile is 25. If you define more than that number, the request will return an error 409 response: profile rendition count exceeds configured rendition limit.

    Conditional outputs

    If the videos you ingest vary widely in quality - for example, your videos might include user-generated content created on phones with low-quality cameras - you may wish to make the generation of some renditions conditional on the bitrate or some other property of the source video. This will prevent the creation and storage of redundant renditions. See Conditional Outputs for details on how to do this.

    Account operations

    At the account level, you can get all profiles for the account and create new ones.



    Get all profiles

    To get all profiles for the account (including standard profiles), you submit a GET request to endpoint shown above.

    Create a profile

    To create a new profile, you submit a POST request to the endpoint shown above, including JSON data for the profile as the request body. See the sample profile below for an example of the JSON data, and the Profile Fields Reference for the allowable fields.

    Single profile operations

    For individual profiles, you can get the profile by name or id, replace a profile, and delete a profile.



    For the profile_id, you can use either the:

    • name (e.g. balanced-high-definition)
    • generated id (e.g. 54de14cce4b0a6d2bf9cb08a)

    Get a profile by id

    To retrieve a single profile, make a GET request to the endpoint shown above.

    Update a profile

    To update a profile, make a PUT request to the endpoint above, including the complete JSON data for profile in the request body.

    Delete a profile

    To delete a profile, make a DELETE request to the endpoint above.

    This action is irreversible

    Default profile operations

    You can get, set, or update the default video-on-demand and live video profiles for your account using the endpoint:


    Get the default profile

    Retrieve the default profile for your account by making a GET request to endpoint above.

    If no default profile has been set, the system default profile will be returned.

    Set the default profile

    To set the default profile, make a POST request to the endpoint shown above, including the JSON in request body:

          "account_id": {account_id},
          "default_profile_id": {default_profile_id}

    For the default_profile_id, you can use either of the:

    • name (e.g. balanced-high-definition)
    • generated id (e.g. 54de14cce4b0a6d2bf9cb08a)

    Update the default profile

    To update the default profile, make a PUT request to the endpoint shown above, including this JSON in the request body:

          "id": {configuration_id},
          "account_id": {account_id},
          "default_profile_id": {default_profile_id}

    Get the configuration_id from the response to a GET or POST request.

    Setting the default live profile

    Setting the default live profile is exactly the same as setting the default video-on-demand profile, except for this change in the request body:

          "id": {configuration_id},
          "account_id": {account_id},
          "default_live_profile_id": {default_live_profile_id}


    • If you specify a non-existent profile, the request will fail

    Sample Profile

    The Standard Profiles document will show you all the default profiles that currently exist for all Video Cloud accounts.


    If you want to add watermarks (or a logo image) to your videos, you can use the watermark fields in your ingest profile.

    Here is an example of a rendition profile with watermarks:

        "renditions": [
              "media_type": "video",
              "id": "559697ece4b072e9641b8404",
              "reference_id": "mp0",
              "format": "mp4",
              "audio_codec": "aac",
              "audio_bitrate": 64,
              "video_codec": "h264",
              "speed": 3,
              "video_bitrate": 450,
              "decoder_bitrate_cap": 771,
              "decoder_buffer_size": 1028,
              "keyframe_rate": 0.5,
              "max_frame_rate": 30,
              "width": 480,
              "height": 270,
              "h264_profile": "baseline",
              "watermarks": [
                  "y": "70%",
                  "width": "20%",
                  "url": ""
          }, ...

    See the

    Page last updated on 19 Jun 2021