Azure OpenAI provider

You can proxy requests to Azure OpenAI AI models through AI Gateway by creating AI Model Provider and AI Model entities. This reference documents all supported AI capabilities, configuration requirements, and provider-specific details needed for proper integration.

AI Gateway automatically routes requests to the appropriate Azure OpenAI API endpoints. The following table shows the upstream paths used for each capability.

The following tables show the AI capabilities supported by the Azure OpenAI provider when configuring AI Models.

By default, AI Gateway uses the path templates shown in the tables below (e.g., /chat/completions, /embeddings, etc.). To customize these paths, configure the config.paths field in your AI Model entity. Custom paths take the form {configured_path}/{template_path} — for example, if you set a custom path of /v2, requests to /embeddings would be routed to /v2/embeddings.

Text generation

Support for Azure OpenAI text generation capabilities:

Embeddings

Support for Azure OpenAI embeddings generation:

¹ Use text-embedding-3-small or text-embedding-3-large for dynamic dimensions.

Agentic

Support for Azure OpenAI agent and assistant capabilities:

² Assistants API requires header OpenAI-Beta: assistants=v2. Responses API requires config.azure_api_version set to "preview".

Audio

Support for Azure OpenAI audio capabilities (speech synthesis, transcription, and translation):

For requests with large payloads, consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Supported audio formats, voices, and parameters vary by model. Refer to your provider’s documentation for available options.

Image

Support for Azure OpenAI image generation and editing capabilities:

For requests with large payloads, consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Supported image sizes and formats vary by model. Refer to your provider’s documentation for allowed dimensions and requirements.

Video

Support for Azure OpenAI video generation capabilities:

For requests with large payloads (video generation), consider increasing config.max_request_body_size on your AI Model entity to three times the raw binary size.

Realtime

Support for Azure OpenAI’s bidirectional streaming for realtime applications:

Realtime processing uses WebSocket protocol (ws/wss). This protocol is automatically enabled when you configure your AI Model with the realtime capability.

³ For requests to Azure OpenAI realtime API, include the header OpenAI-Beta: realtime=v1.

Batches

Support for Azure OpenAI batch processing capabilities:

Batches are configured on a separate AI Model with type: "api", distinct from regular models that handle synchronous capabilities like generate and embeddings. Create a dedicated AI Model exclusively for batches and files, as each model must be either a regular model or an API model, not both.

Files

Support for Azure OpenAI file management capabilities:

Batches are configured on a separate AI Model with type: "api", distinct from regular models that handle synchronous capabilities like generate and embeddings. Create a dedicated AI Model exclusively for batches and files, as each model must be either a regular model or an API model, not both.## Azure OpenAI base URL

The base URL is https://{azure_instance}.openai.azure.com:443/openai/deployments/{deployment_name}/{capability_path}. The {capability_path} is determined by the AI capability.

AI Gateway uses this URL automatically. You only need to configure a URL if you’re using a self-hosted or Azure OpenAI-compatible endpoint, in which case set the upstream_url option in your AI Model configuration.

To use Azure OpenAI with AI Gateway, configure a new AI Model Provider. You can then access supported AI Models from Azure OpenAI.

Here’s a minimal configuration for chat completions:

Replace kong-az-east with your Azure OpenAI resource instance name (the subdomain in your resource’s endpoint, for example the kong-az-east in https://kong-az-east.openai.azure.com).

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Azure Production",
      "name": "my-azure-account",
      "type": "azure",
      "config": {
        "auth": {
          "type": "basic",
          "headers": [
            {
              "name": "Authorization",
              "value": "'$AZURE_OPENAI_API_KEY'"
            }
          ]
        },
        "instance": "kong-az-east"
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-azure-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Azure Production
    name: my-azure-account
    type: azure
    config:
      auth:
        type: basic
        headers:
        - name: Authorization
          value: !secret {source: !env AZURE_OPENAI_API_KEY}
      instance: kong-az-east

You can also use Azure OpenAI with Azure credentials by setting auth to azure and specifying:

• use_managed_identity: Set to true to use Azure Managed Identity (recommended for deployments in Azure). When true, the system uses the identity of the current Azure resource (VM, container, function app, etc.).
• client_id (optional): Entra ID (formerly AAD) application client ID. Required if using a user-assigned managed identity or service principal instead of system-assigned managed identity.
• client_secret (optional): Client secret for the Entra ID application. Required if client_id is set.
• tenant_id (optional): Azure tenant ID (directory ID). Required if using service principal credentials.

Regardless of the auth type you use, config.instance is always required and must be set to your Azure OpenAI resource instance name.