Create a Cognitive Services resource using the Azure Command-Line Interface(CLI)

Use this quickstart to get started with Azure Cognitive Services using the Azure Command Line Interface(CLI). Cognitive Services are represented by Azure resources that you create in your Azure subscription. After creating the resource, Use the keys and endpoint generated for you to authenticate your applications.

In this quickstart, you'll learn how to sign up for Azure Cognitive Services and create an account that has a single-service or multi-service subscription, Using the Azure Command Line Interface(CLI). These services are represented by Azure resources, which enable you to connect to one or more of the Azure Cognitive Services APIs.

You can access Azure Cognitive Services through two different resources: A multi-service resource, or a single-service one.

  • Multi-service resource:
    • Access multiple Azure Cognitive Services with a single key and endpoint.
    • Consolidates billing from the services you use.
  • Single-service resource:
    • Access a single Azure Cognitive Service with a unique key and endpoint for each service created.
    • Use the free tier to try out the service.

Prerequisites

Install the Azure CLI and sign in

Install the Azure CLI. To sign into your local installation of the CLI, run the az login command:

az login

You can also use the green Try It button to run these commands in your browser.

Create a new Azure Cognitive Services resource group

Before creating a Cognitive Services resource, you must have an Azure resource group to contain the resource. When you create a new resource, you have the option to either create a new resource group, or use an existing one. This article shows how to create a new resource group.

Choose your resource group location

To create a resource, you'll need one of the Azure locations available for your subscription. You can retrieve a list of available locations with the az account list-locations command. Most Cognitive Services can be accessed from several locations. Choose the one closest to you, or see which locations are available for the service.

Important

  • Remember your Azure location, as you will need it when calling the Azure Cognitive Services.
  • The availability of some Cognitive Services can vary by region. For more information, see Azure products by region.
az account list-locations \
    --query "[].{Region:name}" \
    --out table

After you have your azure location, create a new resource group in the Azure CLI using the az group create command.

In the example below, replace the azure location westus2 with one of the Azure locations available for your subscription.

az group create \
    --name cognitive-services-resource-group \
    --location westus2

Create a Cognitive Services resource

Choose a cognitive service and pricing tier

When creating a new resource, you will need to know the "kind" of service you want to use, along with the pricing tier (or sku) you want. You will use this and other information as parameters when creating the resource.

Note

Many Cognitive services have a free tier you can use to try the service. To use the free tier, use F0 as the sku for your resource.

Vision

Service Kind
Computer Vision ComputerVision
Custom Vision - Prediction CustomVision.Prediction
Custom Vision - Training CustomVision.Training
Face API Face
Form Recognizer FormRecognizer
Ink Recognizer InkRecognizer
Service Kind
Bing Autosuggest Bing.Autosuggest.v7
Bing Custom Search Bing.CustomSearch
Bing Entity Search Bing.EntitySearch
Bing Search Bing.Search.v7
Bing Spell Check Bing.SpellCheck.v7

Speech

Service Kind
Speech Services SpeechServices
Speech Recognition SpeakerRecognition

Language

Service Kind
Form Understanding FormUnderstanding
LUIS LUIS
QnA Maker QnAMaker
Text Analytics TextAnalytics
Text Translation TextTranslation

Decision

Service Kind
Anomaly Detector AnomalyDetector
Content Moderator ContentModerator
Personalizer Personalizer

You can find a list of available Cognitive Service "kinds" with the az cognitiveservices account list-kinds command:

az cognitiveservices account list-kinds

Add a new resource to your resource group

To create and subscribe to a new Cognitive Services resource, use the az cognitiveservices account create command. This command adds a new billable resource to the resource group created earlier. When creating your new resource, you will need to know the "kind" of service you want to use, along with its pricing tier (or sku) and an Azure location:

You can create an F0 (free) resource for Anomaly Detector, named anomaly-detector-resource with the command below.

az cognitiveservices account create \
    --name anomaly-detector-resource \
    --resource-group cognitive-services-resource-group \
    --kind AnomalyDetector \
    --sku F0 \
    --location westus2 \
    --yes

Get the keys for your resource

To log into your local installation of the Command-Line Interface(CLI), use the az login command.

az login

Use the az cognitiveservices account keys list command to get the keys for your Cognitive Service resource.

    az cognitiveservices account keys list \
    --name anomaly-detector-resource \
    --resource-group cognitive-services-resource-group

Configure an environment variable for authentication

Applications need to authenticate access to the Cognitive Services they use. To authenticate, we recommend creating an environment variable to store the keys for your Azure Resources.

After you have your key, write it to a new environment variable on the local machine running the application. To set the environment variable, open a console window, and follow the instructions for your operating system. Replace your-key with one of the keys for your resource.

setx COGNITIVE_SERVICE_KEY "your-key"

After you add the environment variable, you may need to restart any running programs that will need to read the environment variable, including the console window. For example, if you are using Visual Studio as your editor, restart Visual Studio before running the example.

Pricing tiers and billing

Pricing tiers (and the amount you get billed) are based on the number of transactions you send using your authentication information. Each pricing tier specifies the:

  • maximum number of allowed transactions per second (TPS).
  • service features enabled within the pricing tier.
  • The cost for a predefined amount of transactions. Going above this amount will cause an extra charge as specified in the pricing details for your service.

Get current quota usage for your resource

Use the az cognitiveservices account list-usage command to get the usage for your Cognitive Service resource.

az cognitiveservices account list-usage \
    --name anomaly-detector-resource \
    --resource-group cognitive-services-resource-group \
    --subscription subscription-name

Clean up resources

If you want to clean up and remove a Cognitive Services resource, you can delete it or the resource group. Deleting the resource group also deletes any other resources contained in the group.

To remove the resource group and its associated resources, use the az group delete command.

az group delete --name storage-resource-group

See also