Quickstart: Use the API

Azure AI Video Indexer consolidates various audio and video artificial intelligence (AI) technologies offered by Microsoft into one integrated service, making development simpler. Azure AI Video Indexer is designed to enable developers to focus on using media AI technologies without worrying about scale, global reach, availability, and reliability of cloud platforms. You can use the API to upload your files, get detailed video insights, get URLs of embeddable insights, player widgets, and more.

When you visit the Azure AI Video Indexer website for the first time, a trial account is automatically created for you. With the trial account, you get some free indexing minutes. You can later add a paid account. With the paid option, you pay for indexed minutes. For details about available accounts (trial and paid options), see Azure AI Video Indexer account types.

This article shows you how to use the Azure AI Video Indexer API.

Prerequisites

Upload a media file. There are two ways:

1. Upload a media file to the URL of your choice (recommended). You can use a public network location. After you upload the file, you can check whether the file is accessible to AVI by copying and pasting it into your browser's location bar. If you can play the media file, then it's likely that VI can also access it. If you would like to secure the storage location using Azure Storage Blob, upload the file and obtain a SAS URL. For more information about getting a secure URL for your file, see Azure Blob Storage SAS URLs. This URL is used to copy your file to Azure AI Video Indexer for indexing.

2. Send the video file a byte array in the request body. For more information about uploading a media file as a byte array in a request body, see Upload a blob with .NET.

Subscribe to the API

1. Sign in to the Azure AI Video Indexer API developer portal.
2. Subscribe by selecting the Products tab. Then, select Authorization and subscribe. New users are automatically subscribed to Authorization.
3. Find, copy and save the primary and secondary keys. You can find your subscription in your Profile. The primary and secondary keys are in the Subscriptions section.
4. Select the Show link for both the Primary key and the Secondary key. Copy and paste them to a text editor until you're ready to use them in your environment variables file.

Obtain an access token using the Authorization API

You don't want to give full access to every user for your application. There are several levels of access for VI.

Create and send the access token request

Set the subscription-id, the resource-group-name, the VI account-name in the request and set the scope and permissionType parameter in the request body to the access level you need.

For example, if you want to provide access to a user so that they can work with projects but can't work with accounts, set the permissionType to "Contributor" and the scope to "Project." IF setting permissions for a project, provide the projectId.

POST https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.VideoIndexer/accounts/{account-name}/generateAccessToken?api-version=2024-01-01

{
  "permissionType": "Reader",
  "scope": "Project",
  "projectId": "07ec9e38d4"
}

Sample response

{
  "accessToken": "<jwt token of 1260 characters length>"
}

For more examples of setting the scope and permission types, see the VI REST API.

Start using the API

You're ready to start using the API. Find the detailed description of each Azure AI Video Indexer REST API.

For a detailed example of using the keys in your environment variable file, and using access tokens see the Azure AI Video Indexer sample.

Recommendations

• When you call the API that gets video insights for the specified video, you get a detailed JSON output as the response content. See details about the returned JSON in this article.
• The JSON output produced by the API contains Insights and SummarizedInsights elements. We highly recommend using Insights and not using SummarizedInsights (which is present for backward compatibility).
• We don't recommend that you use data directly from the artifacts folder for production purposes. Artifacts are intermediate outputs of the indexing process and are raw outputs of the various AI engines that analyze the videos. The artifacts schema can change over time.
• Use the Get Video Index API, as described in Get insights and artifacts produced by the API and not Get-Video-Artifact-Download-Url.