ai 7.0.123 → 7.0.124

package/docs/03-ai-sdk-core/36-transcription.mdx

@@ -30,6 +30,42 @@ const language = transcript.language; // language of the transcript e.g. "en", i
 const durationInSeconds = transcript.durationInSeconds; // duration of the transcript in seconds, if available
 ```
 
+## Telemetry
+
+`transcribe` and `experimental_streamTranscribe` accept the standard
+`telemetry` option. Registered integrations receive start, end, and error
+events with the provider and model, audio byte length and media type, final
+transcript, warnings, response metadata, provider metadata, and usage when the
+provider reports it. Because streaming transcription is experimental, custom
+integrations receive its lifecycle through
+`experimental_onStreamTranscriptionStart` and
+`experimental_onStreamTranscriptionEnd`; errors continue to use `onError`.
+Integrations that wrap or delegate to another telemetry integration must
+forward these experimental callbacks explicitly for streaming transcription
+to be observed.
+
+```ts highlight="5-7"
+const transcript = await transcribe({
+  model: openai.transcription('gpt-4o-transcribe'),
+  audio: await readFile('audio.mp3'),
+  telemetry: {
+    functionId: 'transcribe-customer-call',
+  },
+});
+```
+
+Raw audio is not included in telemetry events. For streaming transcription,
+the final byte length is emitted only after the input stream is consumed and
+the transcription finishes. Use `recordInputs: false` or
+`recordOutputs: false` to prevent integrations from recording sensitive input
+or output fields.
+
+For URL audio, the downloaded media type is passed to the provider and reported
+on successful telemetry events. If downloading or decoding input audio fails,
+the start event is still emitted before the correlated error event, but its
+audio byte length and media type can be undefined because preparation did not
+complete.
+
 ## Streaming Transcription
 
 <Note type="warning">Streaming transcription is an experimental feature.</Note>

package/docs/03-ai-sdk-core/37-speech.mdx

@@ -19,6 +19,27 @@ const result = await generateSpeech({
 });
 ```
 
+## Telemetry
+
+`generateSpeech` accepts the standard `telemetry` option. Registered
+integrations receive start, end, and error events with the provider and model,
+source text, generated audio byte length, media type and format, warnings,
+response metadata, provider metadata, and usage when the provider reports it.
+Raw generated audio is not included in telemetry events.
+
+```ts highlight="5-7"
+const result = await generateSpeech({
+  model: openai.speech('gpt-4o-mini-tts'),
+  text: 'Hello from the AI SDK!',
+  telemetry: {
+    functionId: 'speak-greeting',
+  },
+});
+```
+
+Use `recordInputs: false` or `recordOutputs: false` when the text or output
+metadata should not be recorded by telemetry integrations.
+
 To access the generated audio:
 
 ```ts

package/docs/03-ai-sdk-core/60-telemetry.mdx

@@ -53,7 +53,10 @@ For Node.js applications (without Next.js), register the integration at the top
 
 ### Step 2: Enabling Telemetry
 
-Once a telemetry integration is registered, all AI SDK calls emit telemetry events by default.
+Once a telemetry integration is registered, supported AI SDK calls emit
+telemetry events by default. This includes text and object generation,
+embeddings, reranking, speech generation, and both non-streaming and streaming
+transcription.
 You can still pass `telemetry` to attach metadata (like `functionId`) or to opt out of a specific call:
 
 ```ts highlight="4-6"
@@ -71,6 +74,34 @@ By default, both inputs and outputs are recorded. You can disable them by settin
 Disabling the recording of inputs and outputs can be useful for privacy, data transfer, and performance reasons.
 You might for example want to disable recording inputs if they contain sensitive information.
 
+For `generateSpeech`, input telemetry contains the source text and output
+telemetry contains the generated audio byte length, media type, and format.
+For `transcribe` and `experimental_streamTranscribe`, telemetry contains the
+input audio byte length and media type plus the output transcript. Raw audio is
+never included in telemetry events. Streaming transcription reports its final
+byte length when the audio stream has been consumed and the transcription
+finishes.
+
+Custom integrations receive stable `generateSpeech` and `transcribe`
+operations through `onStart` and `onEnd`. To keep the experimental API isolated,
+`experimental_streamTranscribe` uses
+`experimental_onStreamTranscriptionStart` and
+`experimental_onStreamTranscriptionEnd`; all three operations report failures
+through `onError`.
+
+An integration that wraps or delegates to another integration must explicitly
+forward the experimental streaming transcription callbacks. Forwarding only
+the stable `onStart` and `onEnd` callbacks does not observe
+`experimental_streamTranscribe`.
+
+The built-in OpenTelemetry integrations record numeric provider usage by
+default, preserving each reported unit. The modern integration uses attributes
+such as `gen_ai.usage.characters`, `gen_ai.usage.seconds`, and
+`gen_ai.usage.input_tokens`; `LegacyOpenTelemetry` uses the corresponding
+`ai.usage.*` attributes. The provider-native usage object remains available to
+callbacks, and can also be included as the supplemental `ai.response.usage`
+attribute by enabling `usage: true`.
+
 ### Opting out
 
 Telemetry is opt-out. To disable telemetry for a specific call, set `isEnabled: false`:
@@ -550,6 +581,23 @@ For `rerank`, the integration records spans with `CLIENT` kind:
   - `gen_ai.provider.name`: the provider
   - `gen_ai.request.model`: the model ID
 
+#### generateSpeech / transcribe / experimental_streamTranscribe
+
+Each call records a single `CLIENT` span named `{operationId} {modelId}`, where
+`operationId` is `ai.generateSpeech`, `ai.transcribe`, or `ai.streamTranscribe`.
+
+- `gen_ai.output.type`: `"speech"` for speech generation and `"text"` for transcription.
+- `gen_ai.request.stream`: `true` for streaming transcription and `false` otherwise.
+- `gen_ai.input.messages`: speech generation input text as a user message with a text part, when `recordInputs` is enabled.
+- `gen_ai.output.messages`: the completed transcript as an assistant message with a text part, when `recordOutputs` is enabled. Streaming transcription records this once on completion.
+
+The existing `ai.request.text` and `ai.response.text` attributes are also retained.
+Audio byte length, media type, and output format remain in the
+`ai.request.audio.*` and `ai.response.audio.*` attributes, subject to the
+corresponding input/output recording controls. Raw audio is not captured, so
+transcription input and speech output do not populate message attributes with
+audio content or placeholder audio parts.
+
 #### experimental_evaluate
 
 For `experimental_evaluate`, the integration records two spans with `CLIENT`

package/docs/07-reference/01-ai-sdk-core/11-stream-transcribe.mdx

@@ -88,6 +88,13 @@ console.log(await result.text);
       description:
         'When true, the provider includes raw provider chunks in the stream as `raw` parts.',
     },
+    {
+      name: 'telemetry',
+      type: 'TelemetryOptions',
+      isOptional: true,
+      description:
+        'Telemetry configuration. Experimental lifecycle callbacks use experimental_onStreamTranscriptionStart and experimental_onStreamTranscriptionEnd. The end event is emitted after the audio stream is consumed and includes the final input byte length.',
+    },
   ]}
 />
 

package/docs/07-reference/01-ai-sdk-core/11-transcribe.mdx

@@ -64,6 +64,13 @@ console.log(transcript);
       isOptional: true,
       description: 'Additional HTTP headers for the request.',
     },
+    {
+      name: 'telemetry',
+      type: 'TelemetryOptions',
+      isOptional: true,
+      description:
+        'Telemetry configuration. Supports functionId, recordInputs, recordOutputs, isEnabled, and per-call integrations.',
+    },
     {
       name: 'download',
       type: '(options: { url: URL; abortSignal?: AbortSignal }) => Promise<{ data: Uint8Array; mediaType: string | undefined }>',

package/docs/07-reference/01-ai-sdk-core/12-generate-speech.mdx

@@ -124,6 +124,13 @@ const { audio } = await generateSpeech({
       isOptional: true,
       description: 'Additional HTTP headers for the request.',
     },
+    {
+      name: 'telemetry',
+      type: 'TelemetryOptions',
+      isOptional: true,
+      description:
+        'Telemetry configuration. Supports functionId, recordInputs, recordOutputs, isEnabled, and per-call integrations.',
+    },
   ]}
 />
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.123",
+  "version": "7.0.124",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,20 +42,20 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.101",
-    "@ai-sdk/provider": "4.0.20",
-    "@ai-sdk/provider-utils": "5.0.52"
+    "@ai-sdk/gateway": "4.0.102",
+    "@ai-sdk/provider": "4.0.21",
+    "@ai-sdk/provider-utils": "5.0.53"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.102",
-    "@ai-sdk/deepseek": "3.0.57",
-    "@ai-sdk/google": "4.0.86",
-    "@ai-sdk/groq": "4.0.53",
-    "@ai-sdk/huggingface": "2.0.60",
-    "@ai-sdk/moonshotai": "3.0.61",
-    "@ai-sdk/openai": "4.0.82",
+    "@ai-sdk/amazon-bedrock": "5.0.103",
+    "@ai-sdk/deepseek": "3.0.58",
+    "@ai-sdk/google": "4.0.87",
+    "@ai-sdk/groq": "4.0.54",
+    "@ai-sdk/huggingface": "2.0.61",
+    "@ai-sdk/moonshotai": "3.0.62",
+    "@ai-sdk/openai": "4.0.83",
     "@ai-sdk/test-server": "2.0.3",
-    "@ai-sdk/xai": "5.0.13",
+    "@ai-sdk/xai": "5.0.14",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",

package/src/generate-speech/generate-speech.ts

@@ -1,5 +1,6 @@
 import type { JSONObject } from '@ai-sdk/provider';
 import {
+  createIdGenerator,
   detectMediaType,
   withUserAgentSuffix,
   type ProviderOptions,
@@ -7,16 +8,28 @@ import {
 import { NoSpeechGeneratedError } from '../error/no-speech-generated-error';
 import { logWarnings } from '../logger/log-warnings';
 import { resolveSpeechModel } from '../model/resolve-model';
+import { createTelemetryDispatcher } from '../telemetry/create-telemetry-dispatcher';
+import type { TelemetryOptions } from '../telemetry/telemetry-options';
 import type { SpeechModel } from '../types/speech-model';
 import type { SpeechModelResponseMetadata } from '../types/speech-model-response-metadata';
 import type { Warning } from '../types/warning';
 import { prepareRetries } from '../util/prepare-retries';
+import { notify } from '../util/notify';
 import { VERSION } from '../version';
 import type { SpeechResult } from './generate-speech-result';
 import {
   DefaultGeneratedAudioFile,
   type GeneratedAudioFile,
 } from './generated-audio-file';
+import type {
+  GenerateSpeechEndEvent,
+  GenerateSpeechStartEvent,
+} from './speech-events';
+
+const originalGenerateCallId = createIdGenerator({
+  prefix: 'call',
+  size: 24,
+});
 /**
  * Generates speech audio using a speech model.
  *
@@ -32,6 +45,7 @@ import {
  * @param maxRetries - Maximum number of retries. Set to 0 to disable retries. Default: 2.
  * @param abortSignal - An optional abort signal that can be used to cancel the call.
  * @param headers - Additional HTTP headers to be sent with the request. Only applicable for HTTP-based providers.
+ * @param telemetry - Optional telemetry configuration.
  *
  * @returns A result object that contains the generated audio data.
  */
@@ -47,6 +61,8 @@ export async function generateSpeech({
   maxRetries: maxRetriesArg,
   abortSignal,
   headers,
+  telemetry,
+  _internal: { generateCallId = originalGenerateCallId } = {},
 }: {
   /**
    * The speech model to use.
@@ -115,6 +131,18 @@ export async function generateSpeech({
    * Only applicable for HTTP-based providers.
    */
   headers?: Record<string, string>;
+
+  /**
+   * Optional telemetry configuration.
+   */
+  telemetry?: TelemetryOptions;
+
+  /**
+   * Internal. For test use only. May change without notice.
+   */
+  _internal?: {
+    generateCallId?: () => string;
+  };
 }): Promise<SpeechResult> {
   const resolvedModel = resolveSpeechModel(model);
   if (!resolvedModel) {
@@ -126,55 +154,152 @@ export async function generateSpeech({
     `ai/${VERSION}`,
   );
 
-  const { retry } = prepareRetries({
+  const { maxRetries, retry } = prepareRetries({
     maxRetries: maxRetriesArg,
     abortSignal,
   });
 
-  const result = await retry(() =>
-    resolvedModel.doGenerate({
-      text,
-      voice,
-      outputFormat,
-      instructions,
-      speed,
-      language,
-      abortSignal,
-      headers: headersWithUserAgent,
-      providerOptions,
-    }),
-  );
-
-  if (!result.audio || result.audio.length === 0) {
-    throw new NoSpeechGeneratedError({ responses: [result.response] });
-  }
+  const callId = generateCallId();
+  const telemetryDispatcher = createTelemetryDispatcher({ telemetry });
+  const runInTracingChannelSpan =
+    telemetryDispatcher.runInTracingChannelSpan ??
+    (async <T>({ execute }: { execute: () => PromiseLike<T> }) =>
+      await execute());
 
-  logWarnings({
-    warnings: result.warnings,
+  const startEvent: GenerateSpeechStartEvent = {
+    callId,
+    operationId: 'ai.generateSpeech',
     provider: resolvedModel.provider,
-    model: resolvedModel.modelId,
-  });
+    modelId: resolvedModel.modelId,
+    text,
+    voice,
+    outputFormat,
+    instructions,
+    speed,
+    language,
+    maxRetries,
+    headers,
+    providerOptions,
+  };
 
-  const detectedMediaType = detectMediaType({
-    data: result.audio,
-    topLevelType: 'audio',
-  });
+  return await runInTracingChannelSpan({
+    type: 'generateSpeech',
+    event: startEvent,
+    execute: async () => {
+      await notify({
+        event: startEvent,
+        callbacks: [telemetryDispatcher.onStart],
+      });
+
+      try {
+        const result = await retry(() =>
+          resolvedModel.doGenerate({
+            text,
+            voice,
+            outputFormat,
+            instructions,
+            speed,
+            language,
+            abortSignal,
+            headers: headersWithUserAgent,
+            providerOptions,
+          }),
+        );
+
+        if (!result.audio || result.audio.length === 0) {
+          throw new NoSpeechGeneratedError({ responses: [result.response] });
+        }
 
-  return new DefaultSpeechResult({
-    audio: new DefaultGeneratedAudioFile({
-      data: result.audio,
-      mediaType:
-        detectedMediaType ??
-        getResponseAudioMediaType(result.response.headers) ??
-        getOutputFormatMediaType(outputFormat) ??
-        'audio/mp3',
-    }),
-    warnings: result.warnings,
-    responses: [result.response],
-    providerMetadata: result.providerMetadata,
+        logWarnings({
+          warnings: result.warnings,
+          provider: resolvedModel.provider,
+          model: resolvedModel.modelId,
+        });
+
+        const detectedMediaType = detectMediaType({
+          data: result.audio,
+          topLevelType: 'audio',
+        });
+
+        const audio = new DefaultGeneratedAudioFile({
+          data: result.audio,
+          mediaType:
+            detectedMediaType ??
+            getResponseAudioMediaType(result.response.headers) ??
+            getOutputFormatMediaType(outputFormat) ??
+            'audio/mp3',
+        });
+
+        if (telemetryDispatcher.onEnd != null) {
+          const endEvent: GenerateSpeechEndEvent = {
+            callId,
+            operationId: 'ai.generateSpeech',
+            provider: resolvedModel.provider,
+            modelId: resolvedModel.modelId,
+            text,
+            audio: {
+              byteLength: getBase64OrBinaryByteLength(result.audio),
+              mediaType: audio.mediaType,
+              format: audio.format,
+            },
+            usage: result.usage,
+            warnings: result.warnings,
+            providerMetadata: result.providerMetadata,
+            response: getTelemetryResponseMetadata(result.response),
+          };
+
+          await notify({
+            event: endEvent,
+            callbacks: [telemetryDispatcher.onEnd],
+          });
+        }
+
+        return new DefaultSpeechResult({
+          audio,
+          warnings: result.warnings,
+          responses: [result.response],
+          providerMetadata: result.providerMetadata,
+        });
+      } catch (error) {
+        await telemetryDispatcher.onError?.({ callId, error });
+        throw error;
+      }
+    },
   });
 }
 
+function getBase64OrBinaryByteLength(audio: string | Uint8Array): number {
+  if (audio instanceof Uint8Array) {
+    return audio.byteLength;
+  }
+
+  let characterCount = 0;
+  let lastCharacter = '';
+  let secondLastCharacter = '';
+  for (const character of audio) {
+    if (/\s/.test(character)) {
+      continue;
+    }
+    characterCount++;
+    secondLastCharacter = lastCharacter;
+    lastCharacter = character;
+  }
+
+  const padding =
+    lastCharacter === '=' ? (secondLastCharacter === '=' ? 2 : 1) : 0;
+  return Math.floor((characterCount * 3) / 4) - padding;
+}
+
+function getTelemetryResponseMetadata(
+  response: SpeechModelResponseMetadata,
+): SpeechModelResponseMetadata {
+  return {
+    timestamp: response.timestamp,
+    modelId: response.modelId,
+    headers: response.headers,
+  };
+}
+
 function getResponseAudioMediaType(
   headers: Record<string, string> | undefined,
 ): string | undefined {

package/src/generate-speech/index.ts

@@ -4,6 +4,10 @@ import { generateSpeech } from './generate-speech';
 export { generateSpeech } from './generate-speech';
 export type { SpeechResult } from './generate-speech-result';
 export type { GeneratedAudioFile } from './generated-audio-file';
+export type {
+  GenerateSpeechEndEvent,
+  GenerateSpeechStartEvent,
+} from './speech-events';
 
 // deprecated exports
 

package/src/generate-speech/speech-events.ts

@@ -0,0 +1,91 @@
+import type { JSONObject } from '@ai-sdk/provider';
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
+import type { ProviderMetadata } from '../types';
+import type { SpeechModelResponseMetadata } from '../types/speech-model-response-metadata';
+import type { Warning } from '../types/warning';
+
+/**
+ * Event passed to telemetry integrations when speech generation begins.
+ */
+export type GenerateSpeechStartEvent = {
+  /** Unique identifier for this speech generation call. */
+  readonly callId: string;
+
+  /** Identifies the operation type (`ai.generateSpeech`). */
+  readonly operationId: 'ai.generateSpeech';
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The text to convert to speech. */
+  readonly text: string;
+
+  /** The requested voice. */
+  readonly voice: string | undefined;
+
+  /** The requested output format. */
+  readonly outputFormat: string | undefined;
+
+  /** Additional speech instructions. */
+  readonly instructions: string | undefined;
+
+  /** The requested speech speed. */
+  readonly speed: number | undefined;
+
+  /** The requested language. */
+  readonly language: string | undefined;
+
+  /** Maximum number of retries for failed requests. */
+  readonly maxRetries: number;
+
+  /** Additional HTTP headers sent with the request. */
+  readonly headers: Record<string, string> | undefined;
+
+  /** Additional provider-specific options. */
+  readonly providerOptions: ProviderOptions;
+};
+
+/**
+ * Event passed to telemetry integrations when speech generation completes.
+ *
+ * Raw audio is intentionally not included. Integrations receive only its size,
+ * media type, and format.
+ */
+export type GenerateSpeechEndEvent = {
+  /** Unique identifier for this speech generation call. */
+  readonly callId: string;
+
+  /** Identifies the operation type (`ai.generateSpeech`). */
+  readonly operationId: 'ai.generateSpeech';
+
+  /** The provider identifier. */
+  readonly provider: string;
+
+  /** The specific model identifier. */
+  readonly modelId: string;
+
+  /** The text that was converted to speech. */
+  readonly text: string;
+
+  /** Metadata about the generated audio. */
+  readonly audio: {
+    readonly byteLength: number;
+    readonly mediaType: string;
+    readonly format: string;
+  };
+
+  /** Usage reported by the provider, when available. */
+  readonly usage: JSONObject | undefined;
+
+  /** Warnings from the speech model. */
+  readonly warnings: Array<Warning>;
+
+  /** Optional provider-specific metadata. */
+  readonly providerMetadata: ProviderMetadata | undefined;
+
+  /** Response metadata from the provider. */
+  readonly response: SpeechModelResponseMetadata;
+};

package/src/telemetry/create-telemetry-dispatcher.ts

@@ -142,7 +142,7 @@ export function createTelemetryDispatcher({
 
   const mergeTelemetryCallback = <KEY extends TelemetryCallbackKey>(
     key: KEY,
-  ): Callback<TelemetryEvent<KEY>> => {
+  ): Callback<TelemetryEvent<KEY>> | undefined => {
     const integrationCallbacks = (
       integrations
         .map(integration => integration[key]?.bind(integration))
@@ -157,6 +157,10 @@ export function createTelemetryDispatcher({
         >,
     );
 
+    if (integrationCallbacks.length === 0) {
+      return undefined;
+    }
+
     const mergedIntegrationCallback = mergeCallbacks(...integrationCallbacks);
 
     return async (event: TelemetryEvent<KEY>) => {
@@ -164,6 +168,9 @@ export function createTelemetryDispatcher({
     };
   };
 
+  const onStepEnd = mergeTelemetryCallback('onStepEnd');
+  const onStepFinish = mergeTelemetryCallback('onStepFinish');
+
   const executeLanguageModelCallWrappers = integrations
     .map(integration => integration.executeLanguageModelCall?.bind(integration))
     .filter(Boolean) as Array<
@@ -205,10 +212,10 @@ export function createTelemetryDispatcher({
     // deprecated `onStepFinish` callback so integrations that still implement
     // only `onStepFinish` keep receiving step-end events during the deprecation
     // window.
-    onStepEnd: mergeCallbacks(
-      mergeTelemetryCallback('onStepEnd'),
-      mergeTelemetryCallback('onStepFinish'),
-    ),
+    onStepEnd:
+      onStepEnd == null && onStepFinish == null
+        ? undefined
+        : mergeCallbacks(onStepEnd, onStepFinish),
     onObjectStepStart: mergeTelemetryCallback('onObjectStepStart'),
     onObjectStepEnd: mergeTelemetryCallback('onObjectStepEnd'),
     onEmbedStart: mergeTelemetryCallback('onEmbedStart'),
@@ -227,6 +234,12 @@ export function createTelemetryDispatcher({
     experimental_onEvaluateEnd: mergeTelemetryCallback(
       'experimental_onEvaluateEnd',
     ),
+    experimental_onStreamTranscriptionStart: mergeTelemetryCallback(
+      'experimental_onStreamTranscriptionStart',
+    ),
+    experimental_onStreamTranscriptionEnd: mergeTelemetryCallback(
+      'experimental_onStreamTranscriptionEnd',
+    ),
     onEnd: mergeTelemetryCallback('onEnd'),
     onAbort: mergeTelemetryCallback('onAbort'),
     onError: mergeTelemetryCallback('onError'),