Azure OpenAI

The Azure OpenAI provider contains language model support for the Azure OpenAI chat API.

Setup

The Azure OpenAI provider is available in the @ai-sdk/azure module. You can install it with

$ pnpm add @ai-sdk/azure

$ npm install @ai-sdk/azure

$ yarn add @ai-sdk/azure

$ bun add @ai-sdk/azure

Provider Instance

You can import the default provider instance azure from @ai-sdk/azure:

import { azure } from '@ai-sdk/azure';

If you need a customized setup, you can import createAzure from @ai-sdk/azure and create a provider instance with your settings:

import { createAzure } from '@ai-sdk/azure';

const azure = createAzure({
  resourceName: 'your-resource-name', // Azure resource name
  apiKey: 'your-api-key',
});

You can also use a complete Microsoft Foundry OpenAI v1 base URL:

const azure = createAzure({
  baseURL: 'https://your-resource.services.ai.azure.com/openai/v1',
  apiKey: 'your-api-key',
});

For Microsoft Entra ID authentication, you can provide a token provider. Install @azure/identity separately if you want to use its credential helpers:

import { createAzure } from '@ai-sdk/azure';
import {
  DefaultAzureCredential,
  getBearerTokenProvider,
} from '@azure/identity';

const credential = new DefaultAzureCredential();
const scope = 'https://cognitiveservices.azure.com/.default';
const tokenProvider = getBearerTokenProvider(credential, scope);

const azure = createAzure({
  resourceName: 'your-resource-name',
  tokenProvider,
});

You can use the following optional settings to customize the OpenAI provider instance:

• resourceName string

  Azure resource name. It defaults to the AZURE_RESOURCE_NAME environment variable.

  The resource name is used in the assembled URL: https://{resourceName}.openai.azure.com/openai/v1{path}. It must be a single DNS label (letters, digits, and hyphens). You can use baseURL instead to specify the URL prefix.

• apiKey string

  API key that is being sent using the api-key header. It defaults to the AZURE_API_KEY environment variable.

• tokenProvider () => Promise<string>

  Microsoft Entra ID token provider that returns an access token to be sent using the Authorization header. When provided, this is used instead of apiKey.

• apiVersion string

  Sets a custom api version. Defaults to v1. This setting is applied when the provider constructs the v1 path or uses deployment-based URLs. Complete v1 base URLs are used as-is.

• baseURL string

  Use a different URL prefix for API calls, e.g. to use proxy servers.

  Either this or resourceName can be used. When a baseURL is provided, the resourceName is ignored.

  For Azure-hosted URLs ending in .openai.azure.com, .services.ai.azure.com, or .cognitiveservices.azure.com, you can pass either an unversioned OpenAI prefix such as https://your-resource.services.ai.azure.com/openai or a complete v1 base URL such as https://your-resource.services.ai.azure.com/openai/v1. The provider appends /v1 and the configured api-version to unversioned resource URLs. Complete v1 URLs are used as-is.

  Complete Microsoft Foundry project v1 URLs, such as https://your-resource.services.ai.azure.com/api/projects/your-project/openai/v1, are also used as-is. If /v1 is omitted from a Foundry project URL, the provider appends it without adding an api-version query parameter.

  With a non-Azure custom gateway baseURL, the resolved URL is {baseURL}{path}; the SDK does not append /v1 or an api-version query parameter in this mode.

• headers Record<string,string>

  Custom headers to include in the requests.

• fetch (input: RequestInfo, init?: RequestInit) => Promise<Response>

  Custom fetch implementation. Defaults to the global fetch function. You can use it as a middleware to intercept requests, or to provide a custom fetch implementation for e.g. testing.

• useDeploymentBasedUrls boolean

  Use deployment-based URLs for API calls. Set to true to use the legacy deployment format: {baseURL}/deployments/{deploymentId}{path}?api-version={apiVersion} instead of {baseURL}/v1{path}?api-version={apiVersion}. Defaults to false.

  This option is useful for compatibility with certain Azure OpenAI models or deployments that require the legacy endpoint format.

• speechBaseURL string

  URL prefix for Azure Speech requests (MAI-Transcribe transcription and MAI-Voice speech generation), for example a regional endpoint such as https://eastus.api.cognitive.microsoft.com. Defaults to https://{resourceName}.cognitiveservices.azure.com. Speech requests do not use baseURL or apiVersion.

• maiBaseURL string

  URL prefix for MAI requests (MAI-Image and MAI-Transcribe-2-Streaming). Defaults to https://{resourceName}.services.ai.azure.com/mai/v1.

• webSocket WebSocketConstructor

  Custom WebSocket implementation for MAI streaming transcription, for example the WebSocket export of the ws package in Node.js. With a custom implementation the API key is sent in the api-key header; with the native WebSocket it is sent as the api-key query parameter. Microsoft Entra ID (tokenProvider) authentication requires a custom implementation; without one, streaming fails with an InvalidArgumentError before connecting.

Language Models

The Azure OpenAI provider instance is a function that you can invoke to create a language model:

const model = azure('your-deployment-name');

You need to pass your deployment name as the first argument.

Reasoning Models

Azure exposes the thinking of DeepSeek-R1 in the generated text using the <think> tag. You can use the extractReasoningMiddleware to extract this reasoning and expose it as a reasoning property on the result:

import { azure } from '@ai-sdk/azure';
import { wrapLanguageModel, extractReasoningMiddleware } from 'ai';

const enhancedModel = wrapLanguageModel({
  model: azure('your-deepseek-r1-deployment-name'),
  middleware: extractReasoningMiddleware({ tagName: 'think' }),
});

You can then use that enhanced model in functions like generateText and streamText.

Example

You can use OpenAI language models to generate text with the generateText function:

import { azure } from '@ai-sdk/azure';
import { generateText } from 'ai';

const { text } = await generateText({
  model: azure('your-deployment-name'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

OpenAI language models can also be used in the streamText function and support structured data generation with Output (see AI SDK Core).

Provider Options

When using OpenAI language models on Azure, you can configure provider-specific options using providerOptions.openai. More information on available configuration options are on the OpenAI provider page.

import { azure, type OpenAILanguageModelResponsesOptions } from '@ai-sdk/azure';

const messages = [
  {
    role: 'user',
    content: [
      {
        type: 'text',
        text: 'What is the capital of the moon?',
      },
      {
        type: 'file',
        mediaType: 'image',
        data: 'https://example.com/image.png',
        providerOptions: {
          openai: { imageDetail: 'low' },
        },
      },
    ],
  },
];

const { text } = await generateText({
  model: azure('your-deployment-name'),
  providerOptions: {
    openai: {
      reasoningEffort: 'low',
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

Chat Models

You can create models that call the Azure OpenAI chat completions API using the .chat() factory method:

const model = azure.chat('your-deployment-name');

Azure OpenAI chat models support also some model specific settings that are not part of the standard call settings. You can pass them as an options argument:

import { azure, type OpenAILanguageModelChatOptions } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure.chat('your-deployment-name'),
  prompt: 'Write a short story about a robot.',
  providerOptions: {
    openai: {
      logitBias: {
        // optional likelihood for specific tokens
        '50256': -100,
      },
      user: 'test-user', // optional unique user identifier
    } satisfies OpenAILanguageModelChatOptions,
  },
});

The following optional provider options are available for OpenAI chat models:

• logitBias Record<number, number>

  Modifies the likelihood of specified tokens appearing in the completion.

  Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.

  As an example, you can pass {"50256": -100} to prevent the token from being generated.

• logprobs boolean | number

  Return the log probabilities of the tokens. Including logprobs will increase the response size and can slow down response times. However, it can be useful to better understand how the model is behaving.

  Setting to true will return the log probabilities of the tokens that were generated.

  Setting to a number will return the log probabilities of the top n tokens that were generated.

• parallelToolCalls boolean

  Whether to enable parallel function calling during tool use. Default to true.

• user string

  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

DeepSeek Chat Models

You can create Azure-hosted DeepSeek chat models using the .deepseek() factory method:

const model = azure.deepseek('your-deepseek-deployment-name');

Use this factory for Azure DeepSeek models that support DeepSeek's chat reasoning fields, such as deepseek-v4-pro and deepseek-v4-flash. The factory maps top-level reasoning to DeepSeek reasoning_effort request settings, and parses streamed reasoning_content as AI SDK reasoning parts.

import { azure, type AzureDeepSeekLanguageModelOptions } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = generateText({
  model: azure.deepseek('your-deepseek-deployment-name'),
  prompt: 'How many "r"s are in the word "strawberry"?',
  reasoning: 'high',
});

Responses Models

Azure OpenAI uses responses API as default with the azure(deploymentName) factory method.

const model = azure('your-deployment-name');

Further configuration can be done using OpenAI provider options. You can validate the provider options using the OpenAILanguageModelResponsesOptions type.

import { azure, OpenAILanguageModelResponsesOptions } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure('your-deployment-name'),
  providerOptions: {
    azure: {
      parallelToolCalls: false,
      store: false,
      user: 'user_123',
      // ...
    } satisfies OpenAILanguageModelResponsesOptions,
  },
  // ...
});

The following provider options are available:

• parallelToolCalls boolean Whether to use parallel tool calls. Defaults to true.

• store boolean Whether to store the generation. Defaults to true.

• metadata Record<string, string> Additional metadata to store with the generation.

• previousResponseId string The ID of the previous response. You can use it to continue a conversation. Defaults to undefined.

• instructions string Instructions for the model. They can be used to change the system or developer message when continuing a conversation using the previousResponseId option. Defaults to undefined.

• user string A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Defaults to undefined.

• reasoningEffort 'low' | 'medium' | 'high' Reasoning effort for reasoning models. Defaults to medium. If you use providerOptions to set the reasoningEffort option, this model setting will be ignored.

• strictJsonSchema boolean Whether to use strict JSON schema validation. Defaults to false.

The Azure OpenAI provider also returns provider-specific metadata:

For Responses models (azure(deploymentName)), you can type this metadata using AzureResponsesProviderMetadata:

import { azure, type AzureResponsesProviderMetadata } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure('your-deployment-name'),
});

const providerMetadata = result.providerMetadata as
  | AzureResponsesProviderMetadata
  | undefined;

const { responseId, logprobs, serviceTier } = providerMetadata?.azure ?? {};

// responseId can be used to continue a conversation (previousResponseId).
console.log(responseId);

The following Azure-specific metadata may be returned:

• responseId string | null | undefined The ID of the response. Can be used to continue a conversation.
• logprobs (optional) Log probabilities of output tokens (when enabled).
• serviceTier (optional) Service tier information returned by the API.

Changing Reasoning Effort Mid-Conversation

Azure Responses models support message-level reasoning effort updates through providerOptions.azure.reasoningEffortUpdate. The openai namespace is also accepted when the message has no azure options. Use the OpenAIResponsesSystemMessageOptions type exported from @ai-sdk/azure to validate these options:

import { azure, type OpenAIResponsesSystemMessageOptions } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  // Use the name of your GPT-6 deployment.
  model: azure.responses('gpt-6-astra'),
  reasoning: 'low',
  allowSystemInMessages: true,
  messages: [
    {
      role: 'system',
      content: '',
      providerOptions: {
        azure: {
          reasoningEffortUpdate: 'high',
        } satisfies OpenAIResponsesSystemMessageOptions,
      },
    },
    { role: 'user', content: 'Analyze the failure modes of this migration.' },
  ],
});

Keep the request-level reasoning unchanged throughout the conversation and retain earlier effort updates when resending message history. These updates also work with streamText. See the OpenAI reasoning effort guide for continuation, compaction, and configuration restrictions.

Web Search Tool

The Azure OpenAI responses API supports web search through the azure.tools.webSearch tool.

const result = await generateText({
  model: azure('gpt-5'),
  prompt: 'What happened in San Francisco last week?',
  tools: {
    web_search: azure.tools.webSearch({
      // optional configuration:
      searchContextSize: 'high',
      userLocation: {
        type: 'approximate',
        city: 'San Francisco',
        region: 'California',
      },
      filters: {
        allowedDomains: ['sfchronicle.com', 'sfgate.com'],
        blockedDomains: ['example.com'],
      },
    }),
  },
  // Force web search tool (optional):
  toolChoice: { type: 'tool', toolName: 'web_search' },
});

// URL sources directly from `results`
const sources = result.sources;

// Or access sources from tool results
for (const toolResult of result.toolResults) {
  if (toolResult.toolName === 'web_search') {
    console.log('Query:', toolResult.output.action.query);
    console.log('Sources:', toolResult.output.sources);
    // `sources` is an array of object: { type: 'url', url: string }
  }
}

The web search tool supports the following configuration options:

• externalWebAccess boolean - Whether to use external web access for fetching live content. Defaults to true.
• searchContextSize 'low' | 'medium' | 'high' - Controls the amount of context used for the search. Higher values provide more comprehensive results but may have higher latency and cost.
• userLocation - Optional location information to provide geographically relevant results. Includes type (always 'approximate'), country, city, region, and timezone.
• filters - Optional filter configuration to restrict search results.
  • allowedDomains string[] - Up to 100 allowed domains for the search.
  • blockedDomains string[] - Up to 100 blocked domains for the search.

Omit the HTTP or HTTPS prefix from domain filters. Subdomains of configured domains are automatically included or excluded.

For detailed information on configuration options see the Azure OpenAI Web Search Tool documentation.

File Search Tool

The Azure OpenAI provider supports file search through the azure.tools.fileSearch tool.

You can force the use of the file search tool by setting the toolChoice parameter to { type: 'tool', toolName: 'file_search' }.

const result = await generateText({
  model: azure('gpt-5'),
  prompt: 'What does the document say about user authentication?',
  tools: {
    file_search: azure.tools.fileSearch({
      // optional configuration:
      vectorStoreIds: ['vs_123', 'vs_456'],
      maxNumResults: 10,
      ranking: {
        ranker: 'auto',
      },
    }),
  },
  // Force file search tool:
  toolChoice: { type: 'tool', toolName: 'file_search' },
});

Image Generation Tool

Azure OpenAI's Responses API supports multi-modal image generation as a provider-defined tool. Availability is restricted to specific models (for example, gpt-5 variants).

import { createAzure } from '@ai-sdk/azure';
import { generateText } from 'ai';

const azure = createAzure({
  headers: {
    'x-ms-oai-image-generation-deployment': 'gpt-image-2', // use your own image model deployment
  },
});

const result = await generateText({
  model: azure('gpt-5'),
  prompt:
    'Generate an image of an echidna swimming across the Mozambique channel.',
  tools: {
    image_generation: azure.tools.imageGeneration({ outputFormat: 'png' }),
  },
});

for (const toolResult of result.staticToolResults) {
  if (toolResult.toolName === 'image_generation') {
    const base64Image = toolResult.output.result;
  }
}

Code Interpreter Tool

The Azure OpenAI provider supports the code interpreter tool through the azure.tools.codeInterpreter tool. This allows models to write and execute Python code.

import { azure } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure('gpt-5'),
  prompt: 'Write and run Python code to calculate the factorial of 10',
  tools: {
    code_interpreter: azure.tools.codeInterpreter({
      // optional configuration:
      container: {
        fileIds: ['assistant-123', 'assistant-456'], // optional file IDs to make available
      },
    }),
  },
});

The code interpreter tool can be configured with:

• container: Either a container ID string or an object with fileIds to specify uploaded files that should be available to the code interpreter

PDF support

The Azure OpenAI provider supports reading PDF files. You can pass PDF files as part of the message content using the file type:

const result = await generateText({
  model: azure('your-deployment-name'),
  messages: [
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'What is an embedding model?',
        },
        {
          type: 'file',
          data: fs.readFileSync('./data/ai.pdf'),
          mediaType: 'application/pdf',
          filename: 'ai.pdf', // optional
        },
      ],
    },
  ],
});

The model will have access to the contents of the PDF file and respond to questions about it. The PDF file should be passed using the data field, and the mediaType should be set to 'application/pdf'.

Typed providerMetadata in Text Parts

When using the Azure OpenAI Responses API, the SDK attaches Azure OpenAI-specific metadata to output parts via providerMetadata.

This metadata can be used on the client side for tasks such as rendering citations or downloading files generated by the Code Interpreter. To enable type-safe handling of this metadata, the AI SDK exports dedicated TypeScript types.

For text parts, when part.type === 'text', the providerMetadata is provided in the form of AzureResponsesTextProviderMetadata.

This metadata includes the following fields:

• itemId
  The ID of the output item in the Responses API.

• annotations (optional) An array of annotation objects generated by the model. If no annotations are present, this property itself may be omitted (undefined).

  Each element in annotations is a discriminated union with a required type field. Supported types include, for example:

  • url_citation
  • file_citation
  • container_file_citation
  • file_path

  These annotations directly correspond to the annotation objects defined by the Responses API and can be used for inline reference rendering or output analysis. For details, see the official OpenAI documentation: Responses API – output text annotations.

import { azure, type AzureResponsesTextProviderMetadata } from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure('gpt-4.1-mini'),
  prompt:
    'Create a program that generates five random numbers between 1 and 100 with two decimal places, and show me the execution results. Also save the result to a file.',
  tools: {
    code_interpreter: azure.tools.codeInterpreter(),
    web_search_preview: azure.tools.webSearchPreview({}),
    file_search: azure.tools.fileSearch({ vectorStoreIds: ['vs_1234'] }), // requires a configured vector store
  },
});

for (const part of result.content) {
  if (part.type === 'text') {
    const providerMetadata = part.providerMetadata as
      | AzureResponsesTextProviderMetadata
      | undefined;
    if (!providerMetadata) continue;
    const { itemId: _itemId, annotations } = providerMetadata.azure;

    if (!annotations) continue;
    for (const annotation of annotations) {
      switch (annotation.type) {
        case 'url_citation':
          // url_citation is returned from web_search and provides:
          // properties: type, url, title, start_index and end_index
          break;
        case 'file_citation':
          // file_citation is returned from file_search and provides:
          // properties: type, file_id, filename and index
          break;
        case 'container_file_citation':
          // container_file_citation is returned from code_interpreter and provides:
          // properties: type, container_id, file_id, filename, start_index and end_index
          break;
        case 'file_path':
          // file_path provides:
          // properties: type, file_id and index
          break;
        default: {
          const _exhaustiveCheck: never = annotation;
          throw new Error(
            `Unhandled annotation: ${JSON.stringify(_exhaustiveCheck)}`,
          );
        }
      }
    }
  }
}

Typed providerMetadata in Reasoning Parts

When using the Azure OpenAI Responses API, reasoning output parts can include provider metadata. To handle this metadata in a type-safe way, use AzureResponsesReasoningProviderMetadata.

For reasoning parts, when part.type === 'reasoning', the providerMetadata is provided in the form of AzureResponsesReasoningProviderMetadata.

This metadata includes the following fields:

• itemId
  The ID of the reasoning item in the Responses API.
• reasoningEncryptedContent (optional)
  Encrypted reasoning content (only returned when requested via include: ['reasoning.encrypted_content']).

import {
  azure,
  type AzureResponsesReasoningProviderMetadata,
  type OpenAILanguageModelResponsesOptions,
} from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure('your-deployment-name'),
  prompt: 'How many "r"s are in the word "strawberry"?',
  providerOptions: {
    azure: {
      store: false,
      include: ['reasoning.encrypted_content'],
    } satisfies OpenAILanguageModelResponsesOptions,
  },
});

for (const part of result.content) {
  if (part.type === 'reasoning') {
    const providerMetadata = part.providerMetadata as
      | AzureResponsesReasoningProviderMetadata
      | undefined;

    const { itemId, reasoningEncryptedContent } = providerMetadata?.azure ?? {};
    console.log(itemId, reasoningEncryptedContent);
  }
}

Typed providerMetadata in Source Document Parts

For source document parts, when part.type === 'source' and sourceType === 'document', the providerMetadata is provided as AzureResponsesSourceDocumentProviderMetadata.

This metadata is also a discriminated union with a required type field. Supported types include:

• file_citation
• container_file_citation
• file_path

Each type includes the identifiers required to work with the referenced resource, such as fileId and containerId.

import {
  azure,
  type AzureResponsesSourceDocumentProviderMetadata,
} from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure('gpt-4.1-mini'),
  prompt:
    'Create a program that generates five random numbers between 1 and 100 with two decimal places, and show me the execution results. Also save the result to a file.',
  tools: {
    code_interpreter: azure.tools.codeInterpreter(),
    web_search_preview: azure.tools.webSearchPreview({}),
    file_search: azure.tools.fileSearch({ vectorStoreIds: ['vs_1234'] }), // requires a configured vector store
  },
});

for (const part of result.content) {
  if (part.type === 'source') {
    if (part.sourceType === 'document') {
      const providerMetadata = part.providerMetadata as
        | AzureResponsesSourceDocumentProviderMetadata
        | undefined;
      if (!providerMetadata) continue;
      const annotation = providerMetadata.azure;
      switch (annotation.type) {
        case 'file_citation':
          // file_citation is returned from file_search and provides:
          // properties: type, fileId and index
          // The filename can be accessed via part.filename.
          break;
        case 'container_file_citation':
          // container_file_citation is returned from code_interpreter and provides:
          // properties: type, containerId and fileId
          // The filename can be accessed via part.filename.
          break;
        case 'file_path':
          // file_path provides:
          // properties: type, fileId and index
          break;
        default: {
          const _exhaustiveCheck: never = annotation;
          throw new Error(
            `Unhandled annotation: ${JSON.stringify(_exhaustiveCheck)}`,
          );
        }
      }
    }
  }
}

Completion Models

You can create models that call the completions API using the .completion() factory method. The first argument is the model id. Currently only gpt-35-turbo-instruct is supported.

const model = azure.completion('your-gpt-35-turbo-instruct-deployment');

OpenAI completion models support also some model specific settings that are not part of the standard call settings. You can pass them as an options argument:

import {
  azure,
  type OpenAILanguageModelCompletionOptions,
} from '@ai-sdk/azure';
import { generateText } from 'ai';

const result = await generateText({
  model: azure.completion('your-gpt-35-turbo-instruct-deployment'),
  prompt: 'Write a haiku about coding.',
  providerOptions: {
    openai: {
      echo: true, // optional, echo the prompt in addition to the completion
      logitBias: {
        // optional likelihood for specific tokens
        '50256': -100,
      },
      suffix: 'some text', // optional suffix that comes after a completion of inserted text
      user: 'test-user', // optional unique user identifier
    } satisfies OpenAILanguageModelCompletionOptions,
  },
});

The following optional provider options are available for Azure OpenAI completion models:

• echo: boolean

  Echo back the prompt in addition to the completion.

• logitBias Record<number, number>

  Modifies the likelihood of specified tokens appearing in the completion.

  Accepts a JSON object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this tokenizer tool to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.

  As an example, you can pass {"50256": -100} to prevent the <|endoftext|> token from being generated.

• logprobs boolean | number

  Return the log probabilities of the tokens. Including logprobs will increase the response size and can slow down response times. However, it can be useful to better understand how the model is behaving.

  Setting to true will return the log probabilities of the tokens that were generated.

  Setting to a number will return the log probabilities of the top n tokens that were generated.

• suffix string

  The suffix that comes after a completion of inserted text.

• user string

  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Embedding Models

You can create models that call the Azure OpenAI embeddings API using the .embedding() factory method.

const model = azure.embedding('your-embedding-deployment');

Azure OpenAI embedding models support several additional settings. You can pass them as an options argument:

import { azure, type OpenAIEmbeddingModelOptions } from '@ai-sdk/azure';
import { embed } from 'ai';

const { embedding } = await embed({
  model: azure.embedding('your-embedding-deployment'),
  value: 'sunny day at the beach',
  providerOptions: {
    openai: {
      dimensions: 512, // optional, number of dimensions for the embedding
      user: 'test-user', // optional unique user identifier
    } satisfies OpenAIEmbeddingModelOptions,
  },
});

The following optional provider options are available for Azure OpenAI embedding models:

• dimensions: number

  The number of dimensions the resulting output embeddings should have. Only supported in text-embedding-3 and later models.

• user string

  A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse. Learn more.

Image Models

You can create models that call the Azure OpenAI image generation API using the .image() factory method. The first argument is your deployment name. MAI-Image models use the MAI image API instead.

const model = azure.image('your-dalle-deployment-name');

Azure OpenAI image models support several additional settings. You can pass them as providerOptions.openai when generating the image:

import { azure } from '@ai-sdk/azure';
import type { OpenAIImageModelGenerationOptions } from '@ai-sdk/openai';
import { generateImage } from 'ai';

await generateImage({
  model: azure.image('your-dalle-deployment-name'),
  prompt: 'A photorealistic image of a cat astronaut floating in space',
  size: '1024x1024', // '1024x1024', '1792x1024', or '1024x1792' for DALL-E 3
  providerOptions: {
    openai: {
      user: 'test-user', // optional unique user identifier
    } satisfies OpenAIImageModelGenerationOptions,
  },
});

Example

You can use Azure OpenAI image models to generate images with the generateImage function:

import { azure } from '@ai-sdk/azure';
import { generateImage } from 'ai';

const { image } = await generateImage({
  model: azure.image('your-dalle-deployment-name'),
  prompt: 'A photorealistic image of a cat astronaut floating in space',
  size: '1024x1024', // '1024x1024', '1792x1024', or '1024x1792' for DALL-E 3
});

// image contains the URL or base64 data of the generated image
console.log(image);

Model Capabilities

Azure OpenAI supports DALL-E 2 and DALL-E 3 models through deployments. The capabilities depend on which model version your deployment is using:

Azure deployment names are user-defined and do not identify the backing model. Consequently, supportsFileInputs and supportsMaskInputs are undefined (unknown) for Azure image model instances. If your application knows the capabilities of a deployment, you can advertise them with the overrideSupportsFileInputs and overrideSupportsMaskInputs options of wrapImageModel.

MAI-Image

MAI-Image models (MAI-Image-2.6, MAI-Image-2.6-Flash, MAI-Image-2.5, MAI-Image-2.5-Flash, MAI-Image-2.5-Pro) use the MAI image API at https://{resourceName}.services.ai.azure.com/mai/v1 (override with maiBaseURL). Deployments named after the model are detected automatically, case-insensitively. For other deployment names, set providerOptions.azure.api to 'mai'.

import { azure, type AzureImageModelOptions } from '@ai-sdk/azure';
import { generateImage } from 'ai';

const { image, usage } = await generateImage({
  model: azure.image('MAI-Image-2.6'),
  prompt: 'A watercolor of three flowers on a blue background',
  size: '1536x1024',
  providerOptions: {
    azure: {
      webGrounding: true,
    } satisfies AzureImageModelOptions,
  },
});

Pass reference images to edit or combine them (up to five JPEG or PNG images). Masks are not supported.

const { image } = await generateImage({
  model: azure.image('MAI-Image-2.6-Flash'),
  prompt: {
    text: 'Put the product from the first image into the scene from the second',
    images: [productImage, sceneImage],
  },
});

Each request returns one PNG image; generateImage sends one request per image. size is sent as width and height. Each side must be at least 768 pixels, and the total pixel count at most 2,359,296 for MAI-Image-2.6 models and 1,048,576 for MAI-Image-2.5 models. Without size, aspectRatio is mapped to dimensions of about one megapixel; without either, the model returns 1024x1024. seed is not supported. Token usage is returned in usage, with the input text and image token split in providerMetadata.azure.images.

The following provider options are available:

• api 'mai' | 'openai'

  API to use. Defaults to 'mai' for MAI-Image models, 'openai' otherwise.

• autoAspectRatio boolean

  Let the model choose the output aspect ratio from the prompt and reference images. MAI-Image-2.6 models only.

• webGrounding boolean

  Ground generation in Bing web search results. MAI-Image-2.6 models only.

Transcription Models

You can create models that call the Azure OpenAI or Azure Speech transcription API using the .transcription() factory method.

The first argument is the model id e.g. whisper-1.

const model = azure.transcription('whisper-1');

MAI-Transcribe

MAI-Transcribe models are multilingual speech-to-text models from Microsoft AI, served through Azure. The following model IDs use the Azure Speech API. They are matched case-insensitively and sent to Azure under their Azure model names:

mai-transcribe-2-streaming uses the MAI realtime API; see MAI-Transcribe-2-Streaming. All other IDs use the OpenAI API by default, including custom deployment names.

import { azure, type AzureTranscriptionModelOptions } from '@ai-sdk/azure';
import { transcribe } from 'ai';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: azure.transcription('mai-transcribe-2'),
  audio: await readFile('audio.wav'),
  providerOptions: {
    azure: {
      timestamps: 'word',
      diarization: { enabled: true },
      transcribeStyle: 'clean',
    } satisfies AzureTranscriptionModelOptions,
  },
});

MAI-Transcribe models require a Microsoft Foundry (Speech) resource in a region where they are available: centralindia, eastus, northeurope, southeastasia, westus, or westus2 (see Speech service regions). Resources in other regions reject the request. Set AZURE_RESOURCE_NAME and AZURE_API_KEY to that resource's name and key, or pass resourceName and apiKey to createAzure. tokenProvider, custom headers, and custom fetch are also supported. Keys are sent as Ocp-Apim-Subscription-Key.

Speech requests use https://{resourceName}.cognitiveservices.azure.com/speechtotext/transcriptions:transcribe with API version 2025-10-15. Use speechBaseURL to supply a different Speech URL prefix (without /speechtotext/transcriptions:transcribe), for example a regional endpoint:

import { createAzure } from '@ai-sdk/azure';

const azure = createAzure({
  speechBaseURL: 'https://eastus.api.cognitive.microsoft.com',
  apiKey: process.env.AZURE_SPEECH_API_KEY,
});

Speech requests do not use baseURL, apiVersion, or useDeploymentBasedUrls; those settings only apply to Azure OpenAI models.

The following options are available through providerOptions.azure:

• api 'openai' | 'speech' Overrides model-based API selection for this request. Set openai for an OpenAI deployment named after one of the model IDs above, or speech to send another model ID to Speech. Other Speech model IDs are sent unchanged.

• timestamps 'word' | 'segment' | 'none' Timing granularity. For MAI-Transcribe-2 the AI SDK defaults to segment so that results include timed segments (Azure's own default is none). segment returns one segment per sentence or speaker turn, word additionally returns word timing in provider metadata, and none returns a single segment that spans the whole audio. MAI-Transcribe-1.5 only supports none, so the AI SDK does not send a default for it.

• transcribeStyle 'verbatim' | 'clean' verbatim keeps fillers and false starts, clean removes them. Defaults to verbatim. clean requires MAI-Transcribe-2.

• locales string[] Exactly one language code, such as ['en']. This is a strong hint; omit it for automatic language detection and code switching.

• diarization object Set enabled to true to identify speakers. Speaker IDs are returned in provider metadata. Requires MAI-Transcribe-2. maxSpeakers is not supported.

• phraseList object Set phrases to a list of names and domain terms to bias recognition toward them.

Explicit api takes precedence over the model ID. Existing OpenAI transcription options remain under providerOptions.openai. Speech-only Azure options produce warnings when used with the OpenAI API. Unknown providerOptions.azure keys (for example diarization.maxSpeakers) are rejected before the request is sent. Options that a model does not support, such as timestamps: 'word' with MAI-Transcribe-1.5, are sent unchanged, and Azure rejects the request with an error that names the option.

Results include transcript text, timed segments, duration, and an ISO-639-1 language code when the reported phrase locales identify one language. Mixed-language results, and languages without an ISO-639-1 code such as Filipino (fil) or Cantonese (yue), leave language undefined. Speaker IDs, exact locales, and word timing are preserved in providerMetadata.azure.phrases; use the exported AzureTranscriptionProviderMetadata type to access them. Phrase timing is in milliseconds in metadata and seconds in normalized segments.

MAI-Transcribe models are file transcription models: they accept WAV, MP3, or FLAC files shorter than 2 hours and smaller than 250 MB, and do not support streaming transcription; use MAI-Transcribe-2-Streaming to stream. The models are in public preview. See Azure's MAI-Transcribe guide for supported languages and diarization limits.

AI Gateway forwards these provider options, including azure.api.

MAI-Transcribe-2-Streaming

MAI-Transcribe-2-Streaming is a low-latency streaming speech-to-text model from Microsoft AI. azure.transcription('mai-transcribe-2-streaming') streams audio to the MAI realtime API (wss://{resourceName}.services.ai.azure.com/mai/v1/realtime) with experimental_streamTranscribe. The model ID is sent to Azure as the Foundry deployment name, so deploy the model as mai-transcribe-2-streaming, or set api: 'mai' for other deployment names.

import {
  createAzure,
  type AzureOpenAIProviderSettings,
  type AzureTranscriptionModelOptions,
} from '@ai-sdk/azure';
import { experimental_streamTranscribe as streamTranscribe } from 'ai';
import { WebSocket } from 'ws';

const azure = createAzure({
  // `ws`'s WebSocket type differs from the DOM-style WebSocketConstructor.
  webSocket: WebSocket as unknown as AzureOpenAIProviderSettings['webSocket'],
});

const result = streamTranscribe({
  model: azure.transcription('mai-transcribe-2-streaming'),
  audio, // ReadableStream of 16-bit mono PCM chunks
  inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
  providerOptions: {
    azure: { language: 'en' } satisfies AzureTranscriptionModelOptions,
  },
});

for await (const part of result.fullStream) {
  if (part.type === 'transcript-delta') {
    process.stdout.write(part.delta);
  }
}

The model requires a Microsoft Foundry resource with a MAI-Transcribe-2-Streaming deployment in a supported region, such as centralus. Input audio must be 16-bit mono PCM (audio/pcm) at 16000 or 24000 Hz; the default is 24000 Hz.

The stream emits transcript-delta parts for finalized text and transcript-partial parts for the provisional text that follows the latest delta. MAI does not detect pauses on the server, so the stream commits once when the input audio ends and then emits a transcript-final part and the finished transcript. durationInSeconds is computed from the streamed audio.

The following options are available through providerOptions.azure:

• api 'openai' | 'speech' | 'mai' Set mai to stream with a deployment that has a different name.

• language string Language hint such as en. Omit for automatic language detection.

File transcription options such as timestamps produce warnings when streaming. MAI-Transcribe-2-Streaming does not support file transcription.

OpenAI transcription

const azure = createAzure({
  useDeploymentBasedUrls: true,
  apiVersion: '2025-04-01-preview',
});

You can also pass additional provider-specific options using the providerOptions argument. For example, supplying the input language in ISO-639-1 (e.g. en) format will improve accuracy and latency.

import { transcribe } from 'ai';
import { azure, type OpenAITranscriptionModelOptions } from '@ai-sdk/azure';
import { readFile } from 'fs/promises';

const result = await transcribe({
  model: azure.transcription('whisper-1'),
  audio: await readFile('audio.mp3'),
  providerOptions: {
    openai: {
      language: 'en',
    } satisfies OpenAITranscriptionModelOptions,
  },
});

The following provider options are available:

• timestampGranularities string[] The granularity of the timestamps in the transcription. Defaults to ['segment']. Possible values are ['word'], ['segment'], and ['word', 'segment']. Note: There is no additional latency for segment timestamps, but generating word timestamps incurs additional latency.

• language string The language of the input audio. Supplying the input language in ISO-639-1 format (e.g. 'en') will improve accuracy and latency. Optional.

• prompt string An optional text to guide the model's style or continue a previous audio segment. The prompt should match the audio language. Optional.

• temperature number The sampling temperature, between 0 and 1. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. If set to 0, the model will use log probability to automatically increase the temperature until certain thresholds are hit. Defaults to 0. Optional.

• include string[] Additional information to include in the transcription response.

Model Capabilities

Speech Models

You can create models that call the Azure OpenAI speech API or Azure Speech text to speech using the .speech() factory method.

The first argument is your deployment name for the text-to-speech model (e.g., tts-1), or a MAI-Voice model ID.

const model = azure.speech('your-tts-deployment-name');

Example

import { azure } from '@ai-sdk/azure';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: azure.speech('your-tts-deployment-name'),
  text: 'Hello, world!',
  voice: 'alloy', // OpenAI voice ID
});

You can also pass additional provider-specific options using the providerOptions argument:

import { azure, type OpenAISpeechModelOptions } from '@ai-sdk/azure';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: azure.speech('your-tts-deployment-name'),
  text: 'Hello, world!',
  voice: 'alloy',
  providerOptions: {
    openai: {
      speed: 1.2,
    } satisfies OpenAISpeechModelOptions,
  },
});

The following provider options are available:

• instructions string Control the voice of your generated audio with additional instructions e.g. "Speak in a slow and steady tone". Does not work with tts-1 or tts-1-hd. Optional.

• speed number The speed of the generated audio. Select a value from 0.25 to 4.0. Defaults to 1.0. Optional.

Model Capabilities

Azure OpenAI supports TTS models through deployments. The capabilities depend on which model version your deployment is using:

MAI-Voice

MAI-Voice models are multilingual text-to-speech models from Microsoft AI, served through Azure. The following model IDs use the Azure Speech API:

All other IDs use the OpenAI API by default, including custom deployment names.

import { azure, type AzureSpeechModelOptions } from '@ai-sdk/azure';
import { generateSpeech } from 'ai';

const result = await generateSpeech({
  model: azure.speech('mai-voice-2-flash'),
  text: 'Thanks for calling! Your order shipped this morning.',
  voice: 'en-US-Ethan',
  providerOptions: {
    azure: { style: 'excited' } satisfies AzureSpeechModelOptions,
  },
});

MAI-Voice models require a Microsoft Foundry (Speech) resource in a region where they are available (see Speech service regions). They use the same settings as MAI-Transcribe: resourceName (or AZURE_RESOURCE_NAME), apiKey (or AZURE_API_KEY), tokenProvider, and speechBaseURL.

• voice is a prebuilt voice ID that includes its locale, such as en-US-Harper (the default), de-DE-Mia, or es-MX-Valeria. The voice locale selects the language. Full Azure voice names such as es-MX-Valeria:MAI-Voice-2 are also accepted. Available voices vary by model; see Azure's MAI-Voice guide.
• language picks a default voice when voice is not set (see the table below). Other languages and auto use en-US-Harper with a warning. When voice is set, its locale selects the language, and a conflicting language produces a warning.
• outputFormat accepts mp3 (default, 24 kHz), wav, pcm (headerless 24 kHz, 16-bit, mono), opus (Ogg), or any Azure X-Microsoft-OutputFormat value such as audio-48khz-192kbitrate-mono-mp3. Other values fall back to mp3 with a warning. Azure labels raw formats such as pcm as audio/basic.
• speed is a rate multiplier, for example 0.5 for half speed or 2 for double speed.
• instructions is not supported and produces a warning.

The following options are available through providerOptions.azure:

• api 'openai' | 'speech' Overrides model-based API selection for this request. Set openai for an OpenAI deployment named after one of the model IDs above, or speech to send another model ID to Speech.

• style string Speaking style, such as excited or whispering. Supported styles vary by voice and model.

• styleDegree number Style intensity from 0.01 to 2. Azure defaults to 1. Requires style.

Text is always spoken as plain text; SSML input is not supported. The models are in public preview. AI Gateway forwards these provider options, including azure.api.