Overview: Ingest Profiles API

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:

• Managing API Authentication Credentials

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

• Get Client Credentials Using CURL
• Get Client Credentials Using Postman

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.

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.

        /accounts/{{account_id}}/configuration
      

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

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

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

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

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.