@ai-sdk/azure 3.0.127 → 3.0.129

package/src/azure-openai-provider.ts

@@ -21,11 +21,17 @@ import {
   loadApiKey,
   loadSetting,
   normalizeHeaders,
+  parseProviderOptions,
   withoutTrailingSlash,
   withUserAgentSuffix,
   type FetchFunction,
 } from '@ai-sdk/provider-utils';
 import { azureOpenaiTools } from './azure-openai-tools';
+import { AzureSpeechTranscriptionModel } from './azure-speech-transcription-model';
+import {
+  azureTranscriptionModelOptions,
+  isMAITranscribe2,
+} from './azure-transcription-model-options';
 import { VERSION } from './version';
 
 export interface AzureOpenAIProvider extends ProviderV3 {
@@ -87,10 +93,16 @@ export interface AzureOpenAIProvider extends ProviderV3 {
   imageModel(deploymentId: string): ImageModelV3;
 
   /**
-   * Creates an Azure OpenAI model for audio transcription.
+   * Creates an Azure transcription model. MAI-Transcribe-2 uses the Speech API
+   * by default; other IDs use OpenAI. Override with providerOptions.azure.api.
    */
   transcription(deploymentId: string): TranscriptionModelV3;
 
+  /**
+   * Creates an Azure transcription model. Alias of `transcription`.
+   */
+  transcriptionModel(deploymentId: string): TranscriptionModelV3;
+
   /**
    * Creates an Azure OpenAI model for speech generation.
    */
@@ -155,6 +167,14 @@ export interface AzureOpenAIProviderSettings {
    * `{baseURL}/v1{path}?api-version={apiVersion}`.
    */
   useDeploymentBasedUrls?: boolean;
+
+  /**
+   * URL prefix for Azure Speech transcription (MAI-Transcribe-2), e.g. a
+   * regional endpoint like `https://eastus.api.cognitive.microsoft.com`.
+   * Defaults to `https://{resourceName}.cognitiveservices.azure.com`.
+   * Speech requests do not use `baseURL` or `apiVersion`.
+   */
+  speechBaseURL?: string;
 }
 
 function getAzureOpenAIBaseURLInfo(baseURL: string | undefined) {
@@ -199,15 +219,16 @@ export function createAzure(
     });
   }
 
-  const getHeaders = () => {
+  const getHeaders = (api: 'openai' | 'speech' = 'openai') => {
     const authHeaders = tokenProvider
       ? {}
       : {
-          'api-key': loadApiKey({
-            apiKey: options.apiKey,
-            environmentVariableName: 'AZURE_API_KEY',
-            description: 'Azure OpenAI',
-          }),
+          [api === 'speech' ? 'Ocp-Apim-Subscription-Key' : 'api-key']:
+            loadApiKey({
+              apiKey: options.apiKey,
+              environmentVariableName: 'AZURE_API_KEY',
+              description: api === 'speech' ? 'Azure Speech' : 'Azure OpenAI',
+            }),
         };
 
     return withUserAgentSuffix(
@@ -332,12 +353,25 @@ export function createAzure(
     });
 
   const createTranscriptionModel = (modelId: string) =>
-    new OpenAITranscriptionModel(modelId, {
-      provider: 'azure.transcription',
-      url,
-      headers: getHeaders,
-      fetch,
-    });
+    new AzureTranscriptionModel(
+      modelId,
+      options,
+      new OpenAITranscriptionModel(modelId, {
+        provider: 'azure.transcription',
+        url,
+        headers: getHeaders,
+        fetch,
+      }),
+      new AzureSpeechTranscriptionModel(modelId, {
+        url: () =>
+          `${
+            withoutTrailingSlash(options.speechBaseURL) ??
+            `https://${getResourceName()}.cognitiveservices.azure.com`
+          }/speechtotext/transcriptions:transcribe?api-version=2025-10-15`,
+        headers: () => getHeaders('speech'),
+        fetch,
+      }),
+    );
 
   const createSpeechModel = (modelId: string) =>
     new OpenAISpeechModel(modelId, {
@@ -370,6 +404,7 @@ export function createAzure(
   provider.imageModel = createImageModel;
   provider.responses = createResponsesModel;
   provider.transcription = createTranscriptionModel;
+  provider.transcriptionModel = createTranscriptionModel;
   provider.speech = createSpeechModel;
   provider.tools = azureOpenaiTools;
   return provider;
@@ -379,3 +414,55 @@ export function createAzure(
  * Default Azure OpenAI provider instance.
  */
 export const azure = createAzure();
+
+// Resolves the API per request: providerOptions also reach this model via Gateway.
+class AzureTranscriptionModel implements TranscriptionModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly provider = 'azure.transcription';
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: AzureOpenAIProviderSettings,
+    private readonly openai: OpenAITranscriptionModel,
+    private readonly speech: AzureSpeechTranscriptionModel,
+  ) {}
+
+  async doGenerate(options: Parameters<TranscriptionModelV3['doGenerate']>[0]) {
+    const { api, ...speechOptions } = await this.getOptions(
+      options.providerOptions,
+    );
+    if (api === 'speech') {
+      return this.speech.doGenerate(options, speechOptions);
+    }
+
+    const result = await this.openai.doGenerate(options);
+    return {
+      ...result,
+      warnings: [
+        ...result.warnings,
+        ...Object.keys(speechOptions).map(key => ({
+          type: 'unsupported' as const,
+          feature: `providerOptions.azure.${key}`,
+          details: 'This option requires the Azure Speech API.',
+        })),
+      ],
+    };
+  }
+
+  private async getOptions(
+    providerOptions: Parameters<
+      TranscriptionModelV3['doGenerate']
+    >[0]['providerOptions'],
+  ) {
+    const options = await parseProviderOptions({
+      provider: 'azure',
+      providerOptions,
+      schema: azureTranscriptionModelOptions,
+    });
+    return {
+      ...options,
+      api:
+        options?.api ?? (isMAITranscribe2(this.modelId) ? 'speech' : 'openai'),
+    };
+  }
+}

package/src/azure-speech-transcription-model-options.ts

@@ -0,0 +1,46 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+// Strict objects reject unknown keys (e.g. `diarization.maxSpeakers`, which
+// MAI-Transcribe-2 does not support) instead of silently dropping them.
+export const azureSpeechTranscriptionModelOptionsShape = () => ({
+  /**
+   * Timing granularity. Defaults to `segment` so that transcription results
+   * include timed segments (Azure's own default is `none`).
+   */
+  timestamps: z.enum(['word', 'segment', 'none']).optional(),
+
+  /**
+   * `verbatim` keeps fillers and false starts, `clean` removes them.
+   * Azure defaults to `verbatim`.
+   */
+  transcribeStyle: z.enum(['verbatim', 'clean']).optional(),
+
+  /**
+   * Forces a single language, e.g. `['en']`. Omit for automatic language
+   * detection and code switching.
+   */
+  locales: z.array(z.string()).length(1).optional(),
+
+  /**
+   * Speaker diarization. Speaker IDs are available in provider metadata.
+   */
+  diarization: z.strictObject({ enabled: z.boolean() }).optional(),
+
+  /**
+   * Keyword biasing for names and domain terminology.
+   */
+  phraseList: z.strictObject({ phrases: z.array(z.string()) }).optional(),
+});
+
+export const azureSpeechTranscriptionModelOptions = lazySchema(() =>
+  zodSchema(z.strictObject(azureSpeechTranscriptionModelOptionsShape())),
+);
+
+export type AzureTranscriptionModelSpeechOptions = InferSchema<
+  typeof azureSpeechTranscriptionModelOptions
+>;

package/src/azure-speech-transcription-model.ts

@@ -0,0 +1,155 @@
+import type { TranscriptionModelV3 } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonErrorResponseHandler,
+  createJsonResponseHandler,
+  mediaTypeToExtension,
+  postFormDataToApi,
+  type FetchFunction,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import type { AzureTranscriptionProviderMetadata } from './azure-transcription-provider-metadata';
+import type { AzureTranscriptionModelSpeechOptions } from './azure-speech-transcription-model-options';
+import { isMAITranscribe2 } from './azure-transcription-model-options';
+
+export class AzureSpeechTranscriptionModel implements TranscriptionModelV3 {
+  readonly specificationVersion = 'v3';
+  readonly provider = 'azure.transcription';
+
+  constructor(
+    readonly modelId: string,
+    private readonly config: {
+      url: () => string;
+      headers: () => Record<string, string | undefined>;
+      fetch?: FetchFunction;
+    },
+  ) {}
+
+  async doGenerate(
+    options: Parameters<TranscriptionModelV3['doGenerate']>[0],
+    azureOptions: AzureTranscriptionModelSpeechOptions = {},
+  ): Promise<Awaited<ReturnType<TranscriptionModelV3['doGenerate']>>> {
+    const timestamp = new Date();
+    const formData = new FormData();
+    formData.append(
+      'audio',
+      new Blob(
+        [
+          typeof options.audio === 'string'
+            ? convertBase64ToUint8Array(options.audio)
+            : options.audio,
+        ],
+        { type: options.mediaType },
+      ),
+      `audio.${mediaTypeToExtension(options.mediaType)}`,
+    );
+    formData.append(
+      'definition',
+      JSON.stringify({
+        enhancedMode: {
+          enabled: true,
+          model: isMAITranscribe2(this.modelId)
+            ? 'MAI-Transcribe-2'
+            : this.modelId,
+          modelOptions: {
+            timestamps: azureOptions.timestamps ?? 'segment',
+            transcribeStyle: azureOptions.transcribeStyle,
+          },
+        },
+        locales: azureOptions.locales,
+        diarization: azureOptions.diarization,
+        phraseList: azureOptions.phraseList,
+      }),
+    );
+
+    const { value, rawValue, responseHeaders } = await postFormDataToApi({
+      url: this.config.url(),
+      headers: combineHeaders(this.config.headers(), options.headers),
+      formData,
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+      failedResponseHandler: createJsonErrorResponseHandler({
+        errorSchema: z.union([
+          z.object({ error: z.object({ message: z.string() }) }),
+          z.object({ message: z.string() }),
+        ]),
+        errorToMessage: data =>
+          'error' in data ? data.error.message : data.message,
+      }),
+      successfulResponseHandler: createJsonResponseHandler(responseSchema),
+    });
+
+    const phrases = value.phrases ?? [];
+    // Consider every reported locale so mixed results (e.g. en + fil) are not
+    // collapsed to one language; only ISO-639-1 codes are reported.
+    const languages = new Set(
+      phrases.flatMap(phrase =>
+        phrase.locale ? [phrase.locale.split('-')[0].toLowerCase()] : [],
+      ),
+    );
+    const [language] = languages;
+    const reportedLanguage =
+      languages.size === 1 && /^[a-z]{2}$/.test(language)
+        ? language
+        : undefined;
+
+    return {
+      text: value.combinedPhrases.map(phrase => phrase.text).join(' '),
+      segments: phrases.flatMap(phrase =>
+        phrase.offsetMilliseconds != null && phrase.durationMilliseconds != null
+          ? [
+              {
+                text: phrase.text,
+                startSecond: phrase.offsetMilliseconds / 1000,
+                endSecond:
+                  (phrase.offsetMilliseconds + phrase.durationMilliseconds) /
+                  1000,
+              },
+            ]
+          : [],
+      ),
+      language: reportedLanguage,
+      durationInSeconds:
+        value.durationMilliseconds != null
+          ? value.durationMilliseconds / 1000
+          : undefined,
+      warnings: [],
+      providerMetadata: {
+        azure: { phrases },
+      } satisfies AzureTranscriptionProviderMetadata,
+      response: {
+        timestamp,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawValue,
+      },
+    };
+  }
+}
+
+const responseSchema = z.object({
+  combinedPhrases: z.array(z.object({ text: z.string() })),
+  durationMilliseconds: z.number().nullish(),
+  phrases: z
+    .array(
+      z.object({
+        text: z.string(),
+        offsetMilliseconds: z.number().nullish(),
+        durationMilliseconds: z.number().nullish(),
+        locale: z.string().nullish(),
+        speaker: z.number().nullish(),
+        confidence: z.number().nullish(),
+        words: z
+          .array(
+            z.object({
+              text: z.string(),
+              offsetMilliseconds: z.number().nullish(),
+              durationMilliseconds: z.number().nullish(),
+            }),
+          )
+          .nullish(),
+      }),
+    )
+    .nullish(),
+});

package/src/azure-transcription-model-options.ts

@@ -0,0 +1,27 @@
+import {
+  lazySchema,
+  zodSchema,
+  type InferSchema,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { azureSpeechTranscriptionModelOptionsShape } from './azure-speech-transcription-model-options';
+
+export const azureTranscriptionModelOptions = lazySchema(() =>
+  zodSchema(
+    z.strictObject({
+      /**
+       * API to use. Defaults to Speech for MAI-Transcribe-2, OpenAI otherwise.
+       */
+      api: z.enum(['openai', 'speech']).optional(),
+      ...azureSpeechTranscriptionModelOptionsShape(),
+    }),
+  ),
+);
+
+export type AzureTranscriptionModelOptions = InferSchema<
+  typeof azureTranscriptionModelOptions
+>;
+
+export function isMAITranscribe2(modelId: string): boolean {
+  return modelId.toLowerCase() === 'mai-transcribe-2';
+}

package/src/azure-transcription-provider-metadata.ts

@@ -0,0 +1,17 @@
+export type AzureTranscriptionProviderMetadata = {
+  azure: {
+    phrases: Array<{
+      text: string;
+      offsetMilliseconds?: number | null;
+      durationMilliseconds?: number | null;
+      locale?: string | null;
+      speaker?: number | null;
+      confidence?: number | null;
+      words?: Array<{
+        text: string;
+        offsetMilliseconds?: number | null;
+        durationMilliseconds?: number | null;
+      }> | null;
+    }>;
+  };
+};

package/src/index.ts

@@ -29,3 +29,5 @@ export type {
   AzureResponsesSourceDocumentProviderMetadata,
 } from './azure-openai-provider-metadata';
 export { VERSION } from './version';
+export type { AzureTranscriptionModelOptions } from './azure-transcription-model-options';
+export type { AzureTranscriptionProviderMetadata } from './azure-transcription-provider-metadata';