Azure OpenAI

Purpose and Scope

Azure support in this SDK has two closely related modes, and choosing the right one is the main task for application developers. For Azure OpenAI's current v1 API, the repository documentation directs readers to use the standard OpenAI client with an Azure endpoint. For dated Azure OpenAI API versions, it directs readers to use the AzureOpenAI class. Both approaches let TypeScript and JavaScript applications keep using the familiar SDK resource model, while adapting base URLs, authentication, deployment names, and API versioning for Azure-hosted deployments.

Sources: azure.md, README.md

The important distinction is that the v1 API is treated as a standard OpenAI-compatible endpoint, while dated Azure API versions still have Azure-specific request construction. In v1 usage, the model field is the Azure deployment name, so the application code passes the deployment configured in Azure rather than a general public model identifier. In dated-version usage, the AzureOpenAI constructor receives Azure-specific options such as apiVersion, azureADTokenProvider, and optionally deployment for realtime flows. This separation helps avoid mixing endpoint conventions between the two Azure API families.

Sources: azure.md

Relevant Source Files

• azure.md - Primary Azure guide for this repository, including v1 API usage with the standard OpenAI client, dated API usage with AzureOpenAI, Azure Identity examples, and realtime Azure setup.
• README.md - General SDK introduction showing the package purpose, installation paths, default client usage, and the broader generated OpenAI API context into which Azure support fits.
• tests/lib/azure.test.ts - Unit tests for AzureOpenAI request construction, default headers, default query parameters, custom fetch behavior, abort signals, and retry metadata.
• examples/package.json - Example workspace dependency manifest showing that runnable examples include @azure/identity alongside openai and dotenv.

Core Primitives

The standard OpenAI client is the primitive for Azure's current v1 API. The Azure guide imports OpenAI from the package, builds a baseURL by appending the Azure endpoint with the openai v1 path, and supplies apiKey as a token provider rather than a static string. After that, normal SDK resources such as chat.completions are used. The result is intentionally close to non-Azure SDK code: the client shape remains familiar, but endpoint and authentication values are provided from Azure configuration.

Sources: azure.md, README.md

AzureOpenAI is the primitive for dated Azure API versions. Its constructor accepts Azure-focused configuration, and the guide warns that the Azure API shape slightly differs from the core API shape. That warning matters for TypeScript consumers because generated static types for response and parameter objects may not always align perfectly with dated Azure behavior. Treat AzureOpenAI as the compatibility boundary: it preserves the SDK method organization, but request URLs, query parameters, and authentication headers follow Azure expectations for the selected API version.

Sources: azure.md, tests/lib/azure.test.ts

Azure Identity support is shown through getBearerTokenProvider and DefaultAzureCredential from @azure/identity. The v1 sample uses the scope for Azure AI, while the dated API sample uses the Cognitive Services scope. In both cases, the SDK receives a provider that can produce bearer tokens, allowing applications running in Azure-managed environments to avoid hard-coding long-lived secrets. The examples package declares @azure/identity as a dependency, which signals that Azure examples are meant to be runnable with the same identity library used in the guide.

Sources: azure.md, examples/package.json

Configuration Reference

A minimal v1 setup follows the repository guide pattern: read AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT from the environment, create a DefaultAzureCredential, convert it to a bearer token provider with the Azure AI scope, and pass that provider to the standard OpenAI constructor. The base URL construction trims trailing slashes before appending the v1 path, which prevents accidental double slashes when operators configure endpoints differently. The chat completion call then uses model as the deployment value, keeping deployment selection explicit in the request.

Sources: azure.md

import OpenAI from 'openai';
import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';
 
const endpoint = process.env['AZURE_OPENAI_ENDPOINT'];
const deployment = process.env['AZURE_OPENAI_DEPLOYMENT'];
if (!endpoint || !deployment) throw new Error('Missing Azure OpenAI configuration');
 
const tokenProvider = getBearerTokenProvider(
  new DefaultAzureCredential(),
  'https://ai.azure.com/.default',
);
 
const client = new OpenAI({
  baseURL: `${endpoint.replace(/\/+$/, '')}/openai/v1/`,
  apiKey: tokenProvider,
});
 
const completion = await client.chat.completions.create({
  model: deployment,
  messages: [{ role: 'user', content: 'Say hello!' }],
});

For dated APIs, construct AzureOpenAI directly and provide an apiVersion such as a preview version supported by the Azure deployment. The guide's dated example uses DefaultAzureCredential with the Cognitive Services scope, then passes azureADTokenProvider into AzureOpenAI. This is the path to choose when an Azure deployment has not moved to the current v1 API or when a workload must target a dated Azure preview. Because the guide explicitly calls out type shape differences, production code should validate important response fields and avoid assuming perfect parity with the public OpenAI API.

Sources: azure.md

import { AzureOpenAI } from 'openai';
import { getBearerTokenProvider, DefaultAzureCredential } from '@azure/identity';
 
const credential = new DefaultAzureCredential();
const azureADTokenProvider = getBearerTokenProvider(
  credential,
  'https://cognitiveservices.azure.com/.default',
);
 
const client = new AzureOpenAI({
  azureADTokenProvider,
  apiVersion: '2024-10-01-preview',
});

Execution Flow

At runtime, Azure configuration affects request construction before any model call is sent. The v1 flow computes a base URL from the Azure endpoint and lets normal SDK resources build paths beneath it. The dated AzureOpenAI flow appends the api-version query parameter and applies Azure authentication behavior. Tests exercise this lower-level machinery by building requests and URLs directly, rather than only checking high-level model calls. That gives maintainers confidence that headers, query parameters, retries, and custom transport hooks are applied before the request reaches Azure.

Sources: tests/lib/azure.test.ts

The Azure realtime flow starts with a fully configured AzureOpenAI instance and passes it into OpenAIRealtimeWS.azure or OpenAIRealtimeWebSocket.azure. The guide demonstrates a deployment such as a realtime preview deployment, an Azure AD token provider, and an API version. This pattern keeps Azure authentication and versioning centralized in the AzureOpenAI client, then hands that prepared client to the realtime transport helper. Once the realtime instance is created, the application can send requests and receive streaming responses through the realtime client instead of ordinary request-response calls.

Sources: azure.md

Testing Signals

The Azure unit tests define concrete behaviors that are useful when debugging configuration. Default headers are included in built requests, can be ignored with undefined, and can be removed with null. The api-key header can also be explicitly omitted with null, which is important when a caller wants a bearer-token-only request path. Retry metadata is represented with the x-stainless-retry-count header. These tests show that AzureOpenAI inherits the SDK's configurable request pipeline while still adding Azure-specific API versioning to URLs.

Sources: tests/lib/azure.test.ts

Query-string behavior is also tested. A client configured with defaultQuery still receives the required api-version parameter, and multiple default query parameters are preserved. When a request overrides a default query value with undefined, the test expects the default value to disappear while api-version remains. The custom fetch test proves that AzureOpenAI can use an injected transport, and the resulting URL includes the configured api-version. These are practical extension points for proxies, observability wrappers, test doubles, and nonstandard runtime environments.

Sources: tests/lib/azure.test.ts

Next Steps

Use the v1 standard OpenAI client path for new Azure OpenAI integrations when the deployment supports the current v1 API. Use AzureOpenAI for dated Azure API versions, for compatibility with Azure-specific query construction, or when following the repository's Azure realtime setup. Keep @azure/identity available in runnable examples or applications that rely on DefaultAzureCredential. After this page, read the general client configuration material for transport options and the realtime page if the workload needs bidirectional streaming rather than ordinary chat or responses calls.

Sources: azure.md, README.md, examples/package.json