Azure Cognitive Services containers frequently asked questions (FAQ)

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 which may 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 the 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. Here are the 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 repository. Starting September 22nd 2020, these containers are hosted on the Microsoft Container Registry, and 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 completing the request form.

Will containers be available for all Cognitive Services and what are the next set of containers we should expect?

We would like to make more Cognitive Services available as container offerings. Contact to 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?

Cognitive Services containers do not have an SLA.

Cognitive Services container configurations of resources are controlled by customers, so Microsoft will not offer an SLA for general availability (GA). Customers are free to deploy containers on-premises, thus they define the host environments.


To learn more about Cognitive Services Service-Level Agreements, visit our SLA page.

Are these containers available in sovereign clouds?

Not everyone is familiar with the term "sovereign cloud", so let's begin with definition:

The "sovereign cloud" consists of the Azure Government, Azure Germany, and Azure China 21Vianet clouds.

Unfortunately, the Cognitive Services containers are not natively supported in the sovereign clouds. The containers can be run in these clouds, but they will be pulled from the public cloud and need to send usage data to the public endpoint.


How are containers updated to the latest version?

Customers can choose when to update the containers they have 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 version of containers as they are released, checkout Azure Container Registry webhooks for details on how to get notified when an image is updated.

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 is a breaking change to the API signature. We anticipate that this will generally coincide with major version changes to the corresponding Cognitive Service cloud offering. Minor version changes indicate bug fixes, model updates, or new features that do not make a breaking change to the API signature.

Technical questions

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

Whether you don't have a reliable internet connection, or want to save on bandwidth cost. Or if have low-latency requirements, or are dealing with sensitive data that needs to be analyzed on-site, Azure IoT Edge with the 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 support Docker images. If you're using OpenShift, we recommend running the containers as root-user.

How do I provide product feedback and feature recommendations?

Customers are encouraged to voice their concerns publicly, and up-vote others who have done the same where potential issues overlap. The feedback tool can be used for both product feedback and feature recommendations.

What status messages and errors are returned by Cognitive Services containers?

See the following table for a list of 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 an valid API key to run the container. Find your API key and service region in the Keys and Endpoint section for your Azure Cognitive Services resource, in the Azure portal.
Mismatch You have provided an API Key or endpoint for a different kind of cognitive services resource. Find your API key and service region in the Keys and Endpoint section for your Azure 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 making additional requests.
OutOfQuota The API key is out of quota. You can either upgrade your pricing tier, or wait for additional quota to be made available. Find your tier in the Pricing Tier section of your Azure Cognitive Service resource, in the Azure portal.
BillingEndpointBusy The billing endpoint is currently busy. Check the Retry-After value and wait for this period to end before making additional requests.
ContainerUseUnauthorized The API key provided is not authorized for use with this container. You are 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.

Who do I contact for support?

Customer support channels are the same as the Cognitive Services cloud based APIs. All Cognitive Services containers include logging features that will help us and the community support customers. For additional support, see the following options.

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 single quota with tiered pricing, counting against both usages. For more detail, refer to pricing page of the corresponding offering.


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 only with the metering service at all times. Cognitive Services containers do not send customer data to Microsoft.

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

"usageRequestBody": {
  "id": "customer_subscriptionID",
  "apiType": "textanalytics",
  "containerType": "keyphrase",
  "containerVersion": "1.1.00864.0001",
  "containerId": "dep--keyphrase-",
  "meter": {
    "name": "CognitiveServices.TextAnalytics.Container.BatchScoring",
    "quantity": 10.0

What is the current support warranty for containers?

There is no warranty for previews. Microsoft's standard warranty for enterprise software will apply when containers are formally announced as general availability (GA).

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. The minimum and recommended configurations for each container offering are available below:

Are these containers currently supported on Windows?

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

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

Microsoft is first cloud provider to move their 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 do not have any compliance certifications.

What regions are Cognitive Services containers available in?

Containers can be run anywhere in any region however they need a key and to call back to Azure for metering. All supported regions for the Cloud Service are supported for the containers metering call.

Next steps

Let's continue working with Azure Cognitive Services containers.