ai 7.0.22 → 7.0.25

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

@@ -83,10 +83,13 @@ const durationInSeconds = await result.durationInSeconds; // duration in seconds
 The `audio` stream must contain raw audio chunks. `Uint8Array` chunks are raw bytes; `string` chunks are base64-encoded raw bytes. Always set `inputAudioFormat` to match the chunks you send.
 
 <Note>
-  Streaming transcription requires a provider model instance (e.g.
-  `openai.transcription('gpt-realtime-whisper')`). String model IDs resolve
-  through the global provider (AI Gateway by default), which does not support
-  streaming transcription yet.
+  String model IDs resolve through the global provider (AI Gateway by
+  default). AI Gateway supports streaming transcription for supported models
+  (e.g. `openai/gpt-realtime-whisper`, `xai/grok-stt`), so string IDs work:
+  `experimental_streamTranscribe({ model: 'openai/gpt-realtime-whisper', ...
+  })`. You can also pass a provider model instance (e.g.
+  `openai.transcription('gpt-realtime-whisper')`) to stream directly against
+  the provider.
 </Note>
 
 OpenAI streaming transcription uses `openai.transcription('gpt-realtime-whisper')`. xAI uses the same `xai.transcription()` model for request/response and streaming transcription; `experimental_streamTranscribe` uses xAI's WebSocket STT transport under the hood.

package/docs/06-advanced/11-secure-url-fetching.mdx

@@ -0,0 +1,117 @@
+---
+title: Secure URL Fetching
+description: How the AI SDK protects server-side fetches of URLs returned by model providers, and how to harden your deployment further.
+---
+
+# Secure URL Fetching
+
+Many providers return a **URL in their response body** — a generated image,
+audio, or video to download, or a polling URL to check job status. The AI SDK
+fetches these server-side and returns the result to your code. Because that URL
+comes from an external service, a malicious or compromised provider (or anyone
+able to tamper with the response) could point it at an internal address such as
+a cloud-metadata endpoint (`http://169.254.169.254/…`), a private host
+(`http://10.0.0.5/…`), or `localhost`.
+
+To prevent that, the SDK validates every response-supplied URL before fetching
+it. This happens automatically inside the provider packages — you don't need to
+configure anything.
+
+## What the SDK protects against
+
+When the SDK fetches a URL taken from a provider response, it:
+
+- **Rejects private, loopback, and link-local targets** — IPv4 (`10/8`,
+  `172.16/12`, `192.168/16`, `127/8`, `169.254/16`, CGNAT, multicast, …) and the
+  equivalent IPv6 ranges, plus `localhost` and `.local`. Non-`http(s)` schemes
+  are rejected too.
+- **Re-validates every redirect hop** — a URL that passes but then redirects to
+  an internal address is blocked; the redirect is never followed blindly.
+- **Strips risky request headers** — proxy-forwarding, cloud-metadata, and
+  cookie headers are removed before the request.
+- **Drops credentials across origins** — caller headers (`Authorization`,
+  `Cookie`, and provider-specific API-key headers alike) are not sent to a host
+  on a different origin than the provider's; a redirect that crosses origin
+  drops all of them except the user-agent.
+
+A blocked URL surfaces as a `DownloadError`.
+
+## Self-hosted and local endpoints
+
+URLs that are same-origin with the provider endpoint **you configured** (e.g. a
+custom `baseURL` pointing at a self-hosted or `localhost` deployment) are
+exempt from these checks — they target exactly the host you told the SDK to
+talk to. Any redirect off that origin is still validated.
+
+## Limitation: DNS resolution and DNS rebinding
+
+The built-in guard inspects the URL **as a string**. It deliberately does
+**not resolve DNS**, so two attacks remain out of scope at this layer:
+
+1. **Hostname that resolves to a private IP** — a literal host that looks public
+   but whose DNS record points at an internal address.
+2. **DNS rebinding** — a host that resolves to a public IP when validated and a
+   private IP a moment later when the socket actually connects (a
+   time-of-check/time-of-use window).
+
+### Why this isn't built in
+
+Closing these requires resolving DNS and pinning the resolved IP **at connect
+time** — Node-only capabilities (`node:dns`, a custom `undici` dispatcher). The
+SDK's provider utilities are **cross-runtime**: they run on the edge, in the
+browser, and on Bun/Deno, with no Node-only dependencies, so those APIs aren't
+available there. The threat is also specifically a **server-side** one — on the
+edge and in the browser, outbound `fetch` cannot reach a host's internal network
+or metadata endpoint in the first place. So connect-time IP pinning is only
+meaningful, and only available, on a Node server — which is exactly where you
+can add it yourself.
+
+## Hardening your deployment
+
+If your server fetches provider-supplied URLs and you want to close the DNS
+gaps, use one (ideally both) of these:
+
+### 1. Restrict outbound egress at the network layer
+
+Deny your server's network egress to `169.254.0.0/16`, RFC-1918 ranges, and
+loopback. This is the most robust control and is independent of application
+code.
+
+### 2. Inject a hardened `fetch`
+
+Every provider accepts a custom `fetch`. On Node, back it with an `undici`
+`Agent` whose `connect.lookup` validates the resolved IP and lets the socket
+connect only to a safe address — closing both the hostname-to-private and the
+DNS-rebinding windows:
+
+```ts
+import { Agent, fetch as undiciFetch } from 'undici';
+import { lookup } from 'node:dns';
+
+// Your own check that returns true for private/loopback/link-local addresses.
+declare function isUnsafeAddress(ip: string): boolean;
+
+const safeLookup: typeof lookup = (hostname, options, callback) => {
+  lookup(hostname, options as any, (err, address, family) => {
+    if (!err && typeof address === 'string' && isUnsafeAddress(address)) {
+      callback(new Error(`Refusing to connect to ${address}`), '', 0);
+      return;
+    }
+    (callback as any)(err, address, family);
+  });
+};
+
+const safeDispatcher = new Agent({ connect: { lookup: safeLookup } });
+
+const safeFetch: typeof fetch = (input, init) =>
+  undiciFetch(input, { ...init, dispatcher: safeDispatcher }) as any;
+```
+
+```ts
+import { createFal } from '@ai-sdk/fal';
+
+const fal = createFal({ fetch: safeFetch });
+```
+
+The SDK's built-in validation and your connect-time pinning are complementary —
+keep both.

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

@@ -48,7 +48,7 @@ console.log(await result.text);
       name: 'model',
       type: 'TranscriptionModelV4',
       description:
-        'The transcription model to use. The model must support streaming (`doStream`). String model IDs resolve through the global provider (AI Gateway by default), which does not support streaming transcription yet.',
+        "The transcription model to use. The model must support streaming (`doStream`). String model IDs resolve through the global provider (AI Gateway by default), which supports streaming transcription for supported models (e.g. `openai/gpt-realtime-whisper`, `xai/grok-stt`): `experimental_streamTranscribe({ model: 'openai/gpt-realtime-whisper', ... })`.",
     },
     {
       name: 'audio',
@@ -147,3 +147,15 @@ console.log(await result.text);
   `fullStream` early (e.g. `break` out of the loop), the underlying provider
   connection is closed and pending result promises reject.
 </Note>
+
+## Wire format (experimental)
+
+Streaming transcription over WebSocket is serialized with the experimental
+transcription-stream envelope defined in `@ai-sdk/provider-utils`
+(`experimental_parseTranscriptionStreamClientFrame`,
+`experimental_serializeTranscriptionStreamPart`,
+`experimental_parseTranscriptionStreamPart`): the client sends one
+`transcription-stream.start` TEXT frame, audio as BINARY frames, and a
+`transcription-stream.audio-done` TEXT frame; each server TEXT frame is one
+JSON-serialized transcription stream part. AI Gateway implements the server
+side of this envelope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.22",
+  "version": "7.0.25",
   "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,9 +42,9 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.16",
+    "@ai-sdk/gateway": "4.0.19",
     "@ai-sdk/provider": "4.0.3",
-    "@ai-sdk/provider-utils": "5.0.7"
+    "@ai-sdk/provider-utils": "5.0.9"
   },
   "devDependencies": {
     "@edge-runtime/vm": "^5.0.0",

package/src/embed/embed-many.ts

@@ -171,236 +171,248 @@ export async function embedMany({
     telemetry,
   });
 
-  await notify({
-    event: {
-      callId,
-      operationId: 'ai.embedMany',
-      provider: model.provider,
-      modelId: model.modelId,
-      value: values,
-      maxRetries,
-      headers: headersWithUserAgent,
-      providerOptions,
-    },
-    callbacks: [resolvedOnStart, telemetryDispatcher.onStart],
-  });
-
-  try {
-    const [maxEmbeddingsPerCall, supportsParallelCalls] = await Promise.all([
-      model.maxEmbeddingsPerCall,
-      model.supportsParallelCalls,
-    ]);
+  const runInTracingChannelSpan =
+    telemetryDispatcher.runInTracingChannelSpan ??
+    (async <T>({ execute }: { execute: () => PromiseLike<T> }) =>
+      await execute());
+
+  const startEvent = {
+    callId,
+    operationId: 'ai.embedMany',
+    provider: model.provider,
+    modelId: model.modelId,
+    value: values,
+    maxRetries,
+    headers: headersWithUserAgent,
+    providerOptions,
+  };
 
-    if (maxEmbeddingsPerCall == null || maxEmbeddingsPerCall === Infinity) {
-      const { embeddings, usage, warnings, response, providerMetadata } =
-        await retry(async () => {
-          const embedCallId = generateCallId();
+  return await runInTracingChannelSpan({
+    type: 'embedMany',
+    event: startEvent,
+    execute: async () => {
+      await notify({
+        event: startEvent,
+        callbacks: [resolvedOnStart, telemetryDispatcher.onStart],
+      });
 
-          await notify({
-            event: {
-              callId,
-              embedCallId,
-              operationId: 'ai.embedMany.doEmbed',
-              provider: model.provider,
-              modelId: model.modelId,
-              values,
-            },
-            callbacks: [telemetryDispatcher.onEmbedStart],
-          });
+      try {
+        const [maxEmbeddingsPerCall, supportsParallelCalls] = await Promise.all(
+          [model.maxEmbeddingsPerCall, model.supportsParallelCalls],
+        );
+
+        if (maxEmbeddingsPerCall == null || maxEmbeddingsPerCall === Infinity) {
+          const { embeddings, usage, warnings, response, providerMetadata } =
+            await retry(async () => {
+              const embedCallId = generateCallId();
+
+              await notify({
+                event: {
+                  callId,
+                  embedCallId,
+                  operationId: 'ai.embedMany.doEmbed',
+                  provider: model.provider,
+                  modelId: model.modelId,
+                  values,
+                },
+                callbacks: [telemetryDispatcher.onEmbedStart],
+              });
+
+              const modelResponse = await model.doEmbed({
+                values,
+                abortSignal,
+                headers: headersWithUserAgent,
+                providerOptions,
+              });
+
+              const embeddings = modelResponse.embeddings;
+              const usage = modelResponse.usage ?? { tokens: NaN };
+
+              await notify({
+                event: {
+                  callId,
+                  embedCallId,
+                  operationId: 'ai.embedMany.doEmbed',
+                  provider: model.provider,
+                  modelId: model.modelId,
+                  values,
+                  embeddings,
+                  usage,
+                },
+                callbacks: [telemetryDispatcher.onEmbedEnd],
+              });
+
+              return {
+                embeddings,
+                usage,
+                warnings: modelResponse.warnings ?? [],
+                providerMetadata: modelResponse.providerMetadata,
+                response: modelResponse.response,
+              };
+            });
 
-          const modelResponse = await model.doEmbed({
-            values,
-            abortSignal,
-            headers: headersWithUserAgent,
-            providerOptions,
+          logWarnings({
+            warnings,
+            provider: model.provider,
+            model: model.modelId,
           });
 
-          const embeddings = modelResponse.embeddings;
-          const usage = modelResponse.usage ?? { tokens: NaN };
-
           await notify({
             event: {
               callId,
-              embedCallId,
-              operationId: 'ai.embedMany.doEmbed',
+              operationId: 'ai.embedMany',
               provider: model.provider,
               modelId: model.modelId,
-              values,
-              embeddings,
+              value: values,
+              embedding: embeddings,
               usage,
+              warnings,
+              providerMetadata,
+              response: [response],
             },
-            callbacks: [telemetryDispatcher.onEmbedEnd],
+            callbacks: [resolvedOnEnd, telemetryDispatcher.onEnd],
           });
 
-          return {
+          return new DefaultEmbedManyResult({
+            values,
             embeddings,
             usage,
-            warnings: modelResponse.warnings ?? [],
-            providerMetadata: modelResponse.providerMetadata,
-            response: modelResponse.response,
-          };
-        });
-
-      logWarnings({
-        warnings,
-        provider: model.provider,
-        model: model.modelId,
-      });
-
-      await notify({
-        event: {
-          callId,
-          operationId: 'ai.embedMany',
-          provider: model.provider,
-          modelId: model.modelId,
-          value: values,
-          embedding: embeddings,
-          usage,
-          warnings,
-          providerMetadata,
-          response: [response],
-        },
-        callbacks: [resolvedOnEnd, telemetryDispatcher.onEnd],
-      });
-
-      return new DefaultEmbedManyResult({
-        values,
-        embeddings,
-        usage,
-        warnings,
-        providerMetadata,
-        responses: [response],
-      });
-    }
-
-    const valueChunks = splitArray(values, maxEmbeddingsPerCall);
-
-    const embeddings: Array<Embedding> = [];
-    const warnings: Array<Warning> = [];
-    const responses: Array<
-      | {
-          headers?: Record<string, string>;
-          body?: unknown;
+            warnings,
+            providerMetadata,
+            responses: [response],
+          });
         }
-      | undefined
-    > = [];
-    let tokens = 0;
-    let providerMetadata: ProviderMetadata | undefined;
-
-    const parallelChunks = splitArray(
-      valueChunks,
-      supportsParallelCalls ? maxParallelCalls : 1,
-    );
-
-    for (const parallelChunk of parallelChunks) {
-      const results = await Promise.all(
-        parallelChunk.map(chunk => {
-          return retry(async () => {
-            const embedCallId = generateCallId();
-
-            await notify({
-              event: {
-                callId,
-                embedCallId,
-                operationId: 'ai.embedMany.doEmbed',
-                provider: model.provider,
-                modelId: model.modelId,
-                values: chunk,
-              },
-              callbacks: [telemetryDispatcher.onEmbedStart],
-            });
 
-            const modelResponse = await model.doEmbed({
-              values: chunk,
-              abortSignal,
-              headers: headersWithUserAgent,
-              providerOptions,
-            });
+        const valueChunks = splitArray(values, maxEmbeddingsPerCall);
 
-            const chunkEmbeddings = modelResponse.embeddings;
-            const usage = modelResponse.usage ?? { tokens: NaN };
-
-            await notify({
-              event: {
-                callId,
-                embedCallId,
-                operationId: 'ai.embedMany.doEmbed',
-                provider: model.provider,
-                modelId: model.modelId,
-                values: chunk,
-                embeddings: chunkEmbeddings,
-                usage,
-              },
-              callbacks: [telemetryDispatcher.onEmbedEnd],
-            });
-
-            return {
-              embeddings: chunkEmbeddings,
-              usage,
-              warnings: modelResponse.warnings ?? [],
-              providerMetadata: modelResponse.providerMetadata,
-              response: modelResponse.response,
-            };
-          });
-        }),
-      );
-
-      for (const result of results) {
-        embeddings.push(...result.embeddings);
-        warnings.push(...result.warnings);
-        responses.push(result.response);
-        tokens += result.usage.tokens;
-        if (result.providerMetadata) {
-          if (!providerMetadata) {
-            providerMetadata = { ...result.providerMetadata };
-          } else {
-            for (const [providerName, metadata] of Object.entries(
-              result.providerMetadata,
-            )) {
-              providerMetadata[providerName] = {
-                ...(providerMetadata[providerName] ?? {}),
-                ...metadata,
-              };
+        const embeddings: Array<Embedding> = [];
+        const warnings: Array<Warning> = [];
+        const responses: Array<
+          | {
+              headers?: Record<string, string>;
+              body?: unknown;
+            }
+          | undefined
+        > = [];
+        let tokens = 0;
+        let providerMetadata: ProviderMetadata | undefined;
+
+        const parallelChunks = splitArray(
+          valueChunks,
+          supportsParallelCalls ? maxParallelCalls : 1,
+        );
+
+        for (const parallelChunk of parallelChunks) {
+          const results = await Promise.all(
+            parallelChunk.map(chunk => {
+              return retry(async () => {
+                const embedCallId = generateCallId();
+
+                await notify({
+                  event: {
+                    callId,
+                    embedCallId,
+                    operationId: 'ai.embedMany.doEmbed',
+                    provider: model.provider,
+                    modelId: model.modelId,
+                    values: chunk,
+                  },
+                  callbacks: [telemetryDispatcher.onEmbedStart],
+                });
+
+                const modelResponse = await model.doEmbed({
+                  values: chunk,
+                  abortSignal,
+                  headers: headersWithUserAgent,
+                  providerOptions,
+                });
+
+                const chunkEmbeddings = modelResponse.embeddings;
+                const usage = modelResponse.usage ?? { tokens: NaN };
+
+                await notify({
+                  event: {
+                    callId,
+                    embedCallId,
+                    operationId: 'ai.embedMany.doEmbed',
+                    provider: model.provider,
+                    modelId: model.modelId,
+                    values: chunk,
+                    embeddings: chunkEmbeddings,
+                    usage,
+                  },
+                  callbacks: [telemetryDispatcher.onEmbedEnd],
+                });
+
+                return {
+                  embeddings: chunkEmbeddings,
+                  usage,
+                  warnings: modelResponse.warnings ?? [],
+                  providerMetadata: modelResponse.providerMetadata,
+                  response: modelResponse.response,
+                };
+              });
+            }),
+          );
+
+          for (const result of results) {
+            embeddings.push(...result.embeddings);
+            warnings.push(...result.warnings);
+            responses.push(result.response);
+            tokens += result.usage.tokens;
+            if (result.providerMetadata) {
+              if (!providerMetadata) {
+                providerMetadata = { ...result.providerMetadata };
+              } else {
+                for (const [providerName, metadata] of Object.entries(
+                  result.providerMetadata,
+                )) {
+                  providerMetadata[providerName] = {
+                    ...(providerMetadata[providerName] ?? {}),
+                    ...metadata,
+                  };
+                }
+              }
             }
           }
         }
+
+        logWarnings({
+          warnings,
+          provider: model.provider,
+          model: model.modelId,
+        });
+
+        await notify({
+          event: {
+            callId,
+            operationId: 'ai.embedMany',
+            provider: model.provider,
+            modelId: model.modelId,
+            value: values,
+            embedding: embeddings,
+            usage: { tokens },
+            warnings,
+            providerMetadata,
+            response: responses,
+          },
+          callbacks: [resolvedOnEnd, telemetryDispatcher.onEnd],
+        });
+
+        return new DefaultEmbedManyResult({
+          values,
+          embeddings,
+          usage: { tokens },
+          warnings,
+          providerMetadata: providerMetadata,
+          responses,
+        });
+      } catch (error) {
+        await telemetryDispatcher.onError?.({ callId, error });
+        throw error;
       }
-    }
-
-    logWarnings({
-      warnings,
-      provider: model.provider,
-      model: model.modelId,
-    });
-
-    await notify({
-      event: {
-        callId,
-        operationId: 'ai.embedMany',
-        provider: model.provider,
-        modelId: model.modelId,
-        value: values,
-        embedding: embeddings,
-        usage: { tokens },
-        warnings,
-        providerMetadata,
-        response: responses,
-      },
-      callbacks: [resolvedOnEnd, telemetryDispatcher.onEnd],
-    });
-
-    return new DefaultEmbedManyResult({
-      values,
-      embeddings,
-      usage: { tokens },
-      warnings,
-      providerMetadata: providerMetadata,
-      responses,
-    });
-  } catch (error) {
-    await telemetryDispatcher.onError?.({ callId, error });
-    throw error;
-  }
+    },
+  });
 }
 
 class DefaultEmbedManyResult implements EmbedManyResult {

package/src/telemetry/tracing-channel.ts

@@ -7,6 +7,7 @@ export type TelemetryTracingEventType =
   | 'languageModelCall'
   | 'executeTool'
   | 'embed'
+  | 'embedMany'
   | 'rerank';
 
 export type TelemetryTracingChannelMessage<EVENT = unknown> = {