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

Note that Brightcove accounts may or may not also be enabled for Context Aware Encoding.

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.

Also see the API Reference.

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.

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": "f1b16093e2dc4f81810f1488",
            "version": 1,
            "name": "multi-platform-extended-static",
            "description": "Deliver high quality content for a wide range content types and screen sizes including
            mobile, desktop and large screens.", ...
        

"multi-platform-extended-static" or "f1b16093e2dc4f81810f1488" 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:

      https://ingestion.api.brightcove.com/v1/
    

Authorization

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

See Ingest Profiles Best Practices.

Account operations

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

Endpoint

      /accounts/{{account_id}}/profiles
    

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 API Reference for details and sample request bodies, and the Profile Fields Reference for the allowable fields.

 

Create a Live profile

To create a custom ingest profile for Live, you simply need to specify HLS renditions with live_stream set to true:

    {
      "media_type": "video",
      "format": "ts",
      "segment_seconds": 6,
      "label": "hls1080p",
      "live_stream": true,
      "video_codec": "h264",
      "video_bitrate": 4000,
      "keyframe_interval": 60,
      "width": 1920,
      "height": 1080,
      "h264_profile": "high"
      }
  

Note that you should use only the legacy ingest rendition settings for Live profiles, not the dynamic_origin settings for Dynamic Delivery profiles.

Single profile operations

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

Endpoint

      /accounts/{{account_id}}/profiles/{profile_id}
    

For the profile_id, you can use either the:

  • name (e.g. multi-platform-standard-static)
  • generated id (e.g. f1b16093e2dc4f81810f1488)

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:

        /accounts/{{account_id}}/configuration
      

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. multi-platform-standard-static)
  • generated id (e.g. f1b16093e2dc4f81810f1488)

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}
          }
      

Setting the default social clipping profile

Setting the default social clipping 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_social_clipping_profile_id": {default_social_clipping_profile_id}
          }
      

Notes:

  • 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.

Watermarks

If you want to add watermarks (or a logo image) to your videos, Contact Brightcove Support.