Quick Start: Dynamic Ingest API

Introduction

You can do several things with the Dynamic Ingest API, but its main function is to add videos to Video Cloud. This quick start provides a simple tutorial to walk you through ingesting your first video using the API.

This tutorial uses the popular command line tool called CURL for making HTTP requests. If you are not familiar with CURL, see Set up CURL. Note that CURL installed by default and Mac and Linux systems. On Windows, you will need to install it - instructions are in the Set Up CURL guide.

Steps

Get client credentials

This is a one-off step to create client credentials for the API requests. If you already have the necessary client credentials, you can skip this step.

1. To the Managing API Credentials section of Studio.

2. Click Register New Application

3. Select the appropriate account(s) and select at least these permissions:

   • Dynamic Ingest Create
   • Ingestion Profiles Configuration Read
   • Ingestion Profiles Read

4. Copy and save the client id and client secret that are created (there is no way to get the client secret again once you close the dialog!).

Get OAuth token

The client_id and client_secret are used as username and password to get a token (basic authentication), which is used to authenticate subsequent requests.

1. Copy the code below into a text editor, and replace CLIENT_ID and CLIENT_SECRET with your own client credentials:

       curl --request POST \
       --url https://oauth.brightcove.com/v4/access_token \
       --user CLIENT_ID:CLIENT_SECRET \
       --header 'content-type: application/x-www-form-urlencoded' \
       --data grant_type=client_credentials

   Your code will now look something like this:

       curl --request POST \
       --url https://oauth.brightcove.com/v4/access_token \
       --user 0072bebf-0616-442c-84de-7215bb176061:7M0vMete8vP_Dmb9o4a16iws4RQR74PO-JNDKkCOyXFkSIe_iRKdHiiNO6vuBWadn5xFw \
       --header 'content-type: application/x-www-form-urlencoded' \
       --data grant_type=client_credentials

2. Copy your modified code and paste it into terminal (or your command line app), press Return to run it.
3. The response should look like this:

       {
         "access_token":"AMv4uy9puUMrSPtfOUo412Euy8gY1pcjv6RozlH9ALrHyekxY_u-83KWMECgigG9u_gSQoh_gpe8ChAQ1FHclNHgU4h_2qj-8ei19Ve-m4OJ2UOmJwJBZQht_6bIMJMZUZBIvIAGT-8av-uMOpqnnXVJ1qu2rPQeGraIjEkhTnXnGaa-RNUxisRkIoIktN1o9BFzrbLa1xstvPgVhdg78uVg8uDA8X0K9kfibxBfdIkDBzKJAViZZ3gQa56uit2r79GZ_t2KSUgLq1rOPsd0TflHwCAGtSaAHlvb44m-hUKFAOJa-FtXakQ72QcIXha5PhSjYTJZiUa4EbjxXpR6aLvPW4mGQcDzo8bQQ4Hnq8bsa_8l5eUjOm51WI96WhTPJCt4bBWVJKyLM8P7va_Ho6zJc2yOJHDamilRlyOS-DxN4U30m_2AxhHF3DKJO8fWl5srtpbZRPANOq5B6cpAkOiQafoXUv0ntP9nzRwyO-oXVvH4iLDTAArOTXPh-A7OD8QogWu9wb13vO48CvRPsGv9PfT4ZCxzUa3M2NXn8wontkSARzHVNqf6fh-iF6ifalPTw-Z9MhpPd-qwpcHbJfmu5EcJAR3K3QDYttjeRrmEvTBOgbQttapvI2h6rMQqgytiHXpxYgz3Hr1yKe1cuVI8z3haT5pb-FIfOfHKyr7vQ3RDXjdTTJZMYpOhKNjL0oEH2ev_bIGmbGnqUMcuAGhQgMiCVQUKwoLUGHTRG91ZWMCP7CfTEdcVc10jDSELcZ1SBig5_G42ymv1w3KauK6ZwE_Xmu4NrPZiPo-r3u_K08x8Rz8gS1b9mFtcPj6yux058WAW--HIoIQRFGeppiO3S6s1hzkU2jiKMGtTnB8X4MIJXLPq8LHcZO81appEzraHFUG5ewtKRTq5Ck6OFndlSmhT8KIKid806wI5b39eeoe-4c8Os23QuyWIQthG-YdcTSueNoqZ3-5e7HztoYbzNIKvtrdLpwgMAclD9fzs3oCclECAQaaLD3hWENE3n78_TzPt4OvQ4o8L17JTmozZYCq3VDnsp_M9Bb6az8mZfDX5_ALunsE65dv91aXFCjTJigVJ_r28k7kLVct-PVZ1XPSjdAyGoxttMeYpl24737aUZBqPAirHJK-griQlPBh04E0Ay5ip03gJvJxvGuzRE5r8hKD0lVQjfre9huiSjJX-xts4kbY",
         "token_type":"Bearer",
         "expires_in":300
       }

4. Note that the access_token expires in 5 minutes, but you can rerun the code to get a new one whenever you need it. You will know you need a new one if the API requests in the following steps return an UNAUTHORIZED error.

Create video

A call to the CMS API creates the video object in Video Cloud. The body of the request stipulates metadata like name and description. The only required field is the name.

1. Copy the following code into a text editor and replace ACCOUNT_ID with your own Video Cloud account id, and ACCESS_TOKEN with the token from the response to the request in the previous steps.

       curl --request POST \
       --url https://cms.api.brightcove.com/v1/accounts/ACCOUNT_ID/videos/ \
       --header 'authorization: Bearer ACCESS_TOKEN' \
       --header 'content-type: application/json' \
       --data '{"name": "My Video"}'

2. The JSON response will contain various metadata for the video, but for our purposes, the important field is at the top:

       {
         "id": "123456789001",
         …
       }

   You will use this id in the Ingest request below to let Video Cloud know which video to associate your video source file with.

Ingest request

A call to the Dynamic Ingest gives the location of the file to ingest.

1. Copy the following code into a text editor and replace ACCOUNT_ID with your own Video Cloud account id, VIDEO_ID with the id value returned when you created the video, and ACCESS_TOKEN with the token from the response to the request in the previous steps.

       curl --request POST \
         --url https://ingest.api.brightcove.com/v1/accounts/ACCOUNT_ID/videos/VIDEO_ID/ingest-requests \
         --header 'authorization: Bearer ACCESS_TOKEN' \
         --header 'content-type: application/json' \
         --data '{
           "master": {
             "url": "https://support.brightcove.com/test-assets/videos/Great_Blue_Heron.mp4"
           },
           "callbacks": ["https://solutions.brightcove.com/bcls/di-api/di-callback-app.php"]
         }'

   Note that the video and callback app here are provided by Brightcove Learning Services for testing purposes. You can replace these with paths to your own video and/or callback app. If you do not need to receive notifications concerning the ingest job, you can omit the callbacks field.

   If you do use our callback app, you can view the notifications. This app is used for callbacks by several other apps, so use the job id to search for ones associated with your job.

2. You should receive a response that looks like this:

       {"id":"bcc3dd36-50de-4343-b42a-ad02bd8f0241"}

3. You should save the job id, as it is useful in identifying notifications associated with this job, or if you need to contact Support

If you completed the steps above successfully, have ingested a video into your account using the Dynamic Ingest API. If you had trouble or questions, feel free to contact Brightcove Learning Services for help.

If you will be working extensively with our APIs, you may be interested in trying other testing tools besides CURL:

• Insomnia
• Postman