Edit

Quickstart: Create a Cognitive Services resource using the Azure CLI

  • Article
  • 8 minutes to read

Use this quickstart to create a Cognitive Services resource using Azure Command-Line Interface (CLI) commands. After you create the resource, use the keys and endpoint generated for you to authenticate your applications.

Azure Cognitive Services are cloud-based artificial intelligence (AI) services that help developers build cognitive intelligence into applications without having direct AI or data science skills or knowledge. They are available through REST APIs and client library SDKs in popular development languages. Azure Cognitive Services enables developers to easily add cognitive features into their applications with cognitive solutions that can see, hear, speak, and analyze.

Types of Cognitive Services resources

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

  • A valid Azure subscription - Create one for free.
  • The Azure CLI
  • Your Azure account must have a Cognitive Services Contributor role assigned in order for you to agree to the responsible AI terms and create a resource. To get this role assigned to your account, follow the steps in the Assign roles documentation, or contact your administrator.
  • You must create your first Face, Language service, or Computer Vision resources from the Azure portal to review and acknowledge the terms and conditions. You can do so here: Face, Language service, Computer Vision. After that, you can create subsequent resources using any deployment tool (SDK, CLI, or ARM template, etc) under the same Azure subscription.

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 you create a Cognitive Services resource, you must have an Azure resource group to contain the resource. When you create a new resource, you can 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 resources.
  • 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 service and pricing tier

When you create a new resource, you'll need to know the kind of service you want to use, along with the pricing tier (or SKU) you want. You'll use this and other information as parameters when you create the resource.

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.

See the list of SKUs and pricing information below.

Multi-service

Service Kind
Multiple services. For more information, see the pricing page. CognitiveServices

Vision

Service Kind
Computer Vision ComputerVision
Custom Vision - Prediction CustomVision.Prediction
Custom Vision - Training CustomVision.Training
Face Face
Form Recognizer FormRecognizer

Speech

Service Kind
Speech Services SpeechServices

Language

Service Kind
LUIS LUIS
QnA Maker QnAMaker
Language service TextAnalytics
Text Translation TextTranslation

Decision

Service Kind
Anomaly Detector AnomalyDetector
Content Moderator ContentModerator
Personalizer Personalizer

Azure OpenAI

Service Kind
Azure OpenAI OpenAI

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.
  • cost for a predefined number of transactions. Going above this number will cause an extra charge as specified in the pricing details for your service.

Note

Many of the 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.

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 you created earlier. When you create your new resource, you'll 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

Tip

If your subscription doesn't allow you to create a Cognitive Service resource, you may need to enable the privilege of that Azure resource provider using the Azure portal, PowerShell command or an Azure CLI command. If you are not the subscription owner, ask the Subscription Owner or someone with a role of admin to complete the registration for you or ask for the /register/action privileges to be granted to your account.

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

Your application must be authenticated to access Cognitive Services resources. For production, use a secure way of storing and accessing your credentials. For example, after you have a key for your resource, write it to a new environment variable on the local machine running the application.

Tip

Don't include the key directly in your code, and never post it publicly. See the Cognitive Services security article for more authentication options like Azure Key Vault.

To set the environment variable for your resource key, open a console window, and follow the instructions for your operating system and development environment. To set the COGNITIVE_SERVICE_KEY environment variable, replace your-key with one of the keys for your resource.

setx COGNITIVE_SERVICE_KEY your-key

Note

If you only need to access the environment variable in the current running console, you can set the environment variable with set instead of setx.

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

To set the environment variable for your Speech resource region, follow the same steps. Set COGNITIVE_SERVICE_REGION to the region of your resource. For example, westus.

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 number 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 cognitive-services-resource-group

If you need to recover a deleted resource, see Recover deleted Cognitive Services resources.

See also