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:

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

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 20. If you define more than that number, the request will return an error 409 response: profile rendition count exceeds configured rendition limit.

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

Endpoint

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

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:

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

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, 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": "http://learning-services-media.brightcove.com/images/bc_logo.png"
        }
      ]
  }, ...

See the Watermark Fields Reference for a complete explanation of the fields.

Here is a sample video with a logo image added as a watermark:

Watermark Sample