FAQ for Azure Cognitive Services containers

General questions

What is available?

Azure Cognitive Services containers allow developers to use the same intelligent APIs that are available in Azure, but with the benefits of containerization. Some containers are available as a gated preview that might require an application to access. Other containers are publicly available as an ungated preview, or are generally available. You can find a full list of containers and their availability in the Container support in Azure Cognitive Services article. You can also view the containers in Docker Hub.

Is there any difference between the Cognitive Services cloud and the containers?

Cognitive Services containers are an alternative to the Cognitive Services cloud. Containers offer the same capabilities as the corresponding cloud services. Customers can deploy the containers on-premises or in Azure. The core AI technology, pricing tiers, API keys, and API signature are the same between the container and the corresponding cloud services. There are features and benefits for choosing containers over their cloud service equivalent.

How do I access and use a gated preview container?

Previously, gated preview containers were hosted on the containerpreview.azurecr.io repository. As of September 22, 2020, these containers are hosted on the Microsoft Container Registry. Downloading them doesn't require you to use the docker login command. You'll be able to run a gated preview container if your Azure resource was created with the approved Azure subscription ID. You won't be able to run the container if your Azure subscription has not been approved after completion of the request form.

Will containers be available for all Cognitive Services offerings, and what's the next set of containers I should expect?

We'd like to make more Cognitive Services offerings available as containers. Contact your local Microsoft account manager to get updates on new container releases and other Cognitive Services announcements.

What will the service-level agreement (SLA) be for Cognitive Services containers?


To learn more about service-level agreements for Cognitive Services, visit our SLA page.

Cognitive Services provides SLAs which can be viewed on our SLA page at the link provided above.

However, Cognitive Services in containers do not provide an SLA. Customers control Cognitive Services container configurations of resources, so Microsoft won't offer an SLA for general availability (GA). Customers are free to deploy containers on-premises and define the host environments.

Are these containers available in Sovereign clouds?

Cognitive Services containers can be used in the Sovereign clouds. The containers can be run and can connect to the billing endpoint in these clouds, but container images will need to be pulled from the Public cloud container registry.


How are containers updated to the latest version?

Customers can choose when to update the containers that they've deployed. Containers will be marked with standard Docker tags such as latest to indicate the most recent version. We encourage customers to pull the latest versions of containers as they're released. For details on how to get notified when an image is updated, see Azure Container Registry webhooks.

What versions will be supported?

The current and last major version of the container will be supported. However, we encourage customers to stay current to get the latest technology.

How are updates versioned?

Major version changes indicate that there's a breaking change to the API signature. We anticipate that this will generally coincide with major version changes to the corresponding Cognitive Services cloud offering. Minor version changes indicate bug fixes, model updates, or new features that don't make a breaking change to the API signature.

Technical questions

How can I diagnose potential errors in my deployment environment?

If you're having trouble running a Cognitive Services container, you can try using the Microsoft diagnostics container. Use this container to diagnose common errors in your deployment environment that might prevent Cognitive Services containers from functioning as expected.

To get the container, use the following docker pull command:

docker pull mcr.microsoft.com/azure-cognitive-services/diagnostic

Then run the container. Replace {ENDPOINT_URI} with your endpoint, and replace {API_KEY} with your key to your resource:

docker run --rm mcr.microsoft.com/azure-cognitive-services/diagnostic \
eula=accept \
Billing={ENDPOINT_URI} \

The container will test for network connectivity to the billing endpoint.

How should I run the Cognitive Services containers on IoT devices?

Whether you don't have a reliable internet connection, you want to save on bandwidth cost, you have low-latency requirements, or you're dealing with sensitive data that needs to be analyzed on-site, Azure IoT Edge with Cognitive Services containers gives you consistency with the cloud.

Are these containers compatible with OpenShift?

We don't test containers with OpenShift, but generally, Cognitive Services containers should run on any platform that supports Docker images. If you're using OpenShift, we recommend running the containers as root-user.

How do I provide product feedback and feature recommendations?

We encourage customers to voice their concerns publicly and to up-vote others who have done the same where potential issues overlap. You can use the feedback tool for both product feedback and feature recommendations.

What status messages and errors do Cognitive Services containers return?

Here are the status messages and errors:

Status Description
Valid Your API key is valid. No action is needed.
Invalid Your API key is invalid. You must provide a valid API key to run the container. Find your API key and service region in the Azure portal, in the Keys and Endpoint section for your Cognitive Services resource.
Mismatch You've provided an API key or endpoint for a different kind of Cognitive Services resource. Find your API key and service region in the Azure portal, in the Keys and Endpoint section for your Cognitive Services resource.
CouldNotConnect The container couldn't connect to the billing endpoint. Check the Retry-After value and wait for this period to end before you make more requests.
OutOfQuota The API key has exceeded the quota. You can either upgrade your pricing tier or wait for additional quota to become available. Find your tier in the Azure portal, in the Pricing Tier section of your Cognitive Service resource.
BillingEndpointBusy The billing endpoint is currently busy. Check the Retry-After value and wait for this period to end before you make more requests.
ContainerUseUnauthorized The provided API key is not authorized for use with this container. You're likely using a gated container, so make sure your Azure subscription ID is approved by submitting an online request.
Unknown The server is currently unable to process billing requests.

How do I get support?

Customer support channels are the same as for the Cognitive Services cloud-based APIs. All Cognitive Services containers include logging features that will help us and the community support customers. Here are options for more support:

How does billing work?

Customers are charged based on consumption, similar to the Cognitive Services cloud. The containers need to be configured to send metering data to Azure, and transactions will be billed accordingly. Resources used across the hosted and on-premises services will add to the single quota with tiered pricing, counting against both usages. For more information, see the following pricing pages:


Cognitive Services containers are not licensed to run without being connected to Azure for metering. Customers need to enable the containers to communicate billing information with the metering service at all times. Cognitive Services containers do not send customer data to Microsoft.

Here's an example of the information that a container communicates for metering:

  "SubscriptionId": "Customer subscription ID",
  "apiType": "textanalytics",
  "id": "billing id",
  "containerType": "keyphrase",
  "containerVersion": "1.1.00864.0001",
  "containerId": "dep--keyphrase-",
  "meter": {
    "name": "CognitiveServices.TextAnalytics.Container.BatchScoring",
    "quantity": 10.0
  "RequestTime": "The time at which the billing record was created"

What is the current support warranty for containers?

Microsoft's standard warranty for enterprise software applies for all containers formally announced as generally available (GA). There is no warranty for previews.

What happens to Cognitive Services containers when internet connectivity is lost?

Cognitive Services containers are not licensed to run without being connected to Azure for metering. Customers need to enable the containers to communicate with the metering service at all times.

How long can the container operate without being connected to Azure?

Cognitive Services containers are not licensed to run without being connected to Azure for metering. Customers need to enable the containers to communicate with the metering service at all times.

What hardware is required to run these containers?

Cognitive Services containers are x64-based containers that can run any compatible Linux node, VM, and edge device that supports x64 Linux Docker containers. They all require CPU processors. You can find the minimum and recommended configurations for each container offering on these pages:

Are these containers currently supported on Windows?

Cognitive Services containers are Linux containers, but there is some support for Linux containers on Windows. For more information about Linux containers on Windows, see the Docker documentation.

How do Cognitive Services containers compare to AWS and Google offerings?

Microsoft is the first cloud provider to move its pre-trained AI models in containers with simple billing per transaction as though customers are using a cloud service. Microsoft believes a hybrid cloud gives customers more choice.

What compliance certifications do containers have?

Cognitive Services containers don't have any compliance certifications.

What regions are Cognitive Services containers available in?

Containers can be run anywhere in any region, but they need a key and need to call back to Azure for metering. All supported regions for the cloud service are supported for the containers' metering call.