@ai-sdk/gateway 4.0.121 → 4.0.123

package/docs/00-ai-gateway.mdx

@@ -464,6 +464,69 @@ console.log(ranking);
 
 Reranking models are useful for improving search results in retrieval-augmented generation (RAG) pipelines by re-scoring candidate documents after an initial retrieval step.
 
+## Streaming Speech Models
+
+<Note type="warning">
+  Streaming speech is experimental and the API may change in patch releases.
+</Note>
+
+Speech models that support streaming can be used with
+`experimental_streamSpeech`. The gateway provider connects to AI Gateway over a
+WebSocket, forwards text deltas as they arrive, and streams audio chunks back.
+Gateway WebSocket auth is carried in the subprotocols, so no header-capable
+WebSocket implementation is needed.
+
+Streaming speech works only with models that the
+[AI Gateway model catalog](https://vercel.com/ai-gateway/models) lists with
+streaming speech support. The model ID below is illustrative; check the catalog
+for current availability.
+
+```ts
+import { experimental_streamSpeech as streamSpeech } from 'ai';
+
+const result = streamSpeech({
+  model: 'elevenlabs/eleven-flash-v2.5',
+  text: textStream, // a string, or an array or stream of strings and/or text parts
+  outputFormat: { type: 'audio/pcm', rate: 24000 },
+});
+
+for await (const chunk of result.audioStream) {
+  // Uint8Array audio bytes
+}
+
+console.log(await result.usage); // { inputCharacters: ... }
+```
+
+### Streaming Speech in the Browser
+
+To stream speech from browser code without exposing your Gateway credential,
+mint a short-lived client secret on your server with
+`gateway.experimental_speech.getToken()` and pass the token to the browser.
+The token is bound to the streaming speech surface and the requested model.
+
+```ts
+// Server
+import { gateway } from '@ai-sdk/gateway';
+
+const { token } = await gateway.experimental_speech.getToken({
+  model: 'elevenlabs/eleven-flash-v2.5',
+  expiresAfterSeconds: 60,
+});
+```
+
+```ts
+// Browser
+import { createGateway } from '@ai-sdk/gateway';
+import { experimental_streamSpeech as streamSpeech } from 'ai';
+
+const gateway = createGateway({ apiKey: token });
+
+const result = streamSpeech({
+  model: gateway.experimental_speech('elevenlabs/eleven-flash-v2.5'),
+  text: textStream,
+});
+```
+
 ## Realtime Models
 
 <Note type="warning">
@@ -1232,7 +1295,7 @@ for await (const part of result.stream) {
 
 #### Parallel Search
 
-The Parallel Search tool enables models to search the web using [Parallel AI's Search API](https://docs.parallel.ai/api-reference/search-beta/search). This tool is optimized for LLM consumption, returning relevant excerpts from web pages that can replace multiple keyword searches with a single call.
+The Parallel Search tool enables models to search the web using [Parallel AI's Search API](https://docs.parallel.ai/api-reference/search/search). The model provides a research objective and a few keyword queries, and the tool returns relevant excerpts from web pages, optimized for LLM consumption.
 
 ```ts
 import { gateway, generateText } from 'ai';
@@ -1260,7 +1323,8 @@ const result = await generateText({
   prompt: 'Find detailed information about TypeScript 5.0 features.',
   tools: {
     parallel_search: gateway.tools.parallelSearch({
-      mode: 'agentic',
+      mode: 'advanced',
+      location: 'us',
       maxResults: 5,
       sourcePolicy: {
         includeDomains: ['typescriptlang.org', 'github.com'],
@@ -1279,11 +1343,15 @@ console.log('Tool results:', JSON.stringify(result.toolResults, null, 2));
 
 The Parallel Search tool supports the following optional configuration options:
 
-- **mode** _'one-shot' | 'agentic'_
+- **mode** _'turbo' | 'fast' | 'basic' | 'advanced'_
+
+  Search mode. Defaults to `'basic'`. See the [AI Gateway web search docs](https://vercel.com/docs/ai-gateway/models-and-providers/web-search#using-parallel-search) for pricing.
+  - `'turbo'` - Lowest latency, shorter excerpts. Supports English and Japanese only.
+  - `'fast'` - Low latency, shorter excerpts.
+  - `'basic'` - Balanced latency and excerpt depth (default).
+  - `'advanced'` - Most thorough retrieval, higher latency.
 
-  Mode preset for different use cases:
-  - `'one-shot'` - Comprehensive results with longer excerpts for single-response answers (default)
-  - `'agentic'` - Concise, token-efficient results optimized for multi-step agentic workflows
+  `'one-shot'` and `'agentic'` are deprecated but still accepted: `'one-shot'` runs as `'basic'` and `'agentic'` runs as `'advanced'`.
 
 - **maxResults** _number_
 
@@ -1292,20 +1360,34 @@ The Parallel Search tool supports the following optional configuration options:
 - **sourcePolicy** _object_
 
   Source policy for controlling which domains to include/exclude:
-  - `includeDomains` - List of domains to include in search results
-  - `excludeDomains` - List of domains to exclude from search results
-  - `afterDate` - Only include results published after this date (ISO 8601 format)
+  - `includeDomains` - Domains or domain/path prefixes to include, such as `'wikipedia.org'` or `'docs.python.org/3'`. When set, `excludeDomains` is ignored.
+  - `excludeDomains` - Domains or domain/path prefixes to exclude
+  - `afterDate` - Only include results published on or after this date (`YYYY-MM-DD`)
+
+  The include and exclude lists can hold up to 200 entries combined.
+
+- **maxCharsTotal** _number_
+
+  Maximum total characters across all result excerpts.
 
 - **excerpts** _object_
 
   Excerpt configuration for controlling result length:
   - `maxCharsPerResult` - Maximum characters per result
-  - `maxCharsTotal` - Maximum total characters across all results
+  - `maxCharsTotal` - Deprecated; use the top-level `maxCharsTotal`
 
 - **fetchPolicy** _object_
 
   Fetch policy for controlling content freshness:
-  - `maxAgeSeconds` - Maximum age in seconds for cached content (set to 0 for always fresh)
+  - `maxAgeSeconds` - Maximum age of cached content, in seconds, before a live fetch is attempted. Minimum 600; lower values are raised to 600.
+  - `timeoutSeconds` - Timeout for a live fetch, in seconds. The gateway caps it to stay within its own tool timeout.
+  - `disableCacheFallback` - Return an error instead of older cached content when a live fetch fails. Defaults to `false`.
+
+- **location** _string_
+
+  ISO 3166-1 alpha-2 country code to localize results, such as `'us'`. Invalid codes are ignored with a warning.
+
+Each tool result contains a `search_id` and `results`, ordered by decreasing relevance, and may include a `session_id`. Each result has a `url`, a `title`, a `publish_date` (both may be `null`), and `excerpts` (an array of markdown strings). The result can also include `warnings`, for example when an invalid `location` is ignored.
 
 The tool works with both `generateText` and `streamText`:
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-sdk/gateway",
   "private": false,
-  "version": "4.0.121",
+  "version": "4.0.123",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -30,8 +30,8 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "4.0.31",
-    "@ai-sdk/provider-utils": "5.0.65",
+    "@ai-sdk/provider": "4.0.33",
+    "@ai-sdk/provider-utils": "5.0.67",
     "@vercel/oidc": "3.2.0"
   },
   "devDependencies": {

package/src/gateway-decision-model-settings.ts

@@ -1,4 +1,6 @@
 export type GatewayDecisionModelId =
+  | 'baseten/elephant-1'
+  | 'baseten/mammoth-1'
   | 'convaiinnovations/laya'
   | 'convaiinnovations/laya-free'
   | 'liquid/d1'

package/src/gateway-language-model-settings.ts

@@ -271,6 +271,8 @@ export type GatewayModelId =
   | 'sakana/fugu-ultra'
   | 'sakana/fugu-ultra-v2'
   | 'sakana/namazu'
+  | 'scaledown/scaledown-extract-1'
+  | 'scaledown/scaledown-summarize-1'
   | 'spacexai/grok-4.1-fast-non-reasoning'
   | 'spacexai/grok-4.1-fast-reasoning'
   | 'spacexai/grok-4.20-multi-agent'

package/src/gateway-provider.ts

@@ -40,7 +40,7 @@ import { GatewayImageModel } from './gateway-image-model';
 import { GatewayVideoModel } from './gateway-video-model';
 import { GatewayDecisionModel } from './gateway-decision-model';
 import { GatewayRerankingModel } from './gateway-reranking-model';
-import { GatewaySpeechModel } from './gateway-speech-model';
+import { GatewaySpeechModel, toGatewaySpeechUrl } from './gateway-speech-model';
 import {
   GatewayTranscriptionModel,
   toGatewayTranscriptionUrl,
@@ -66,6 +66,7 @@ import type {
   TranscriptionModelV4,
   Experimental_VideoModelV4,
   Experimental_DecisionModelV4,
+  Experimental_StreamingSpeechModelV4,
   Experimental_RealtimeFactoryV4 as RealtimeFactoryV4,
   Experimental_RealtimeFactoryV4GetTokenOptions as RealtimeFactoryV4GetTokenOptions,
   ProviderV4,
@@ -216,6 +217,14 @@ export interface GatewayProvider extends ProviderV4 {
    */
   experimental_transcription: GatewayTranscriptionFactory;
 
+  /**
+   * Experimental streaming-speech entry point. Callable like
+   * `speech(modelId)`, plus `getToken` for minting a short-lived client
+   * secret (`vcst_`) a browser can use to open the streaming speech
+   * WebSocket without holding the Gateway credential.
+   */
+  experimental_speech: GatewaySpeechFactory;
+
   /**
    * Gateway-specific tools executed server-side.
    */
@@ -252,6 +261,36 @@ export interface GatewayTranscriptionFactory {
   ): Promise<GatewayTranscriptionFactoryGetTokenResult>;
 }
 
+export type GatewaySpeechFactoryGetTokenOptions = {
+  model: GatewaySpeechModelId;
+  /** Token lifetime in seconds. Gateway default is 60s (max 300s). */
+  expiresAfterSeconds?: number;
+};
+
+export type GatewaySpeechFactoryGetTokenResult = {
+  /** The minted `vcst_` client secret. */
+  token: string;
+  /** WebSocket URL of the streaming speech surface for this model. */
+  url: string;
+  /** Token expiry, epoch seconds. */
+  expiresAt?: number;
+};
+
+/**
+ * Streaming-speech factory: callable like `speech(modelId)`, plus a
+ * server-side `getToken` that mints a speech-bound short-lived client secret
+ * (`vcst_`). The browser connects with
+ * `createGateway({ apiKey: token }).speech(modelId)`; the token rides the
+ * same auth subprotocol an API key does, without exposing the credential.
+ */
+export interface GatewaySpeechFactory {
+  (modelId: GatewaySpeechModelId): Experimental_StreamingSpeechModelV4;
+
+  getToken(
+    options: GatewaySpeechFactoryGetTokenOptions,
+  ): Promise<GatewaySpeechFactoryGetTokenResult>;
+}
+
 export interface GatewayProviderSettings {
   /** Settings for downloading JSON Lines batch results. */
   batchResultDownloads?: {
@@ -288,10 +327,10 @@ export interface GatewayProviderSettings {
   fetch?: FetchFunction;
 
   /**
-   * Custom WebSocket implementation used for streaming transcription. This is
-   * useful for testing or for runtimes without a global WebSocket. A
-   * header-capable implementation is not required — Gateway WebSocket auth is
-   * carried in the subprotocols.
+   * Custom WebSocket implementation used for streaming transcription and
+   * streaming speech. This is useful for testing or for runtimes without a
+   * global WebSocket. A header-capable implementation is not required —
+   * Gateway WebSocket auth is carried in the subprotocols.
    */
   webSocket?: WebSocketConstructor;
 
@@ -391,7 +430,7 @@ export function createGateway(
   const mintClientSecret = async (params: {
     modelId: string;
     expiresAfterSeconds?: number;
-    routeKind?: 'transcription';
+    routeKind?: 'speech' | 'transcription';
   }): Promise<{ token: string; expiresAt?: number }> => {
     assertGatewayClientSecretServerEnvironment();
     const auth = await getRealtimeAuthToken();
@@ -624,10 +663,35 @@ export function createGateway(
       headers: getHeaders,
       fetch: options.fetch,
       o11yHeaders: createO11yHeaders(),
+      webSocket: options.webSocket,
     });
   };
   provider.speechModel = createSpeechModel;
   provider.speech = createSpeechModel;
+  // Callable like `speech(modelId)`; `getToken` mints a speech-bound client
+  // secret (server-side only) the browser uses to connect via
+  // `createGateway({ apiKey: token }).speech(modelId)`.
+  provider.experimental_speech = Object.assign(
+    (modelId: GatewaySpeechModelId) => createSpeechModel(modelId),
+    {
+      getToken: async (
+        tokenOptions: GatewaySpeechFactoryGetTokenOptions,
+      ): Promise<GatewaySpeechFactoryGetTokenResult> => {
+        const secret = await mintClientSecret({
+          modelId: tokenOptions.model,
+          routeKind: 'speech',
+          ...(tokenOptions.expiresAfterSeconds != null && {
+            expiresAfterSeconds: tokenOptions.expiresAfterSeconds,
+          }),
+        });
+        return {
+          token: secret.token,
+          url: toGatewaySpeechUrl(baseURL, tokenOptions.model),
+          ...(secret.expiresAt != null && { expiresAt: secret.expiresAt }),
+        };
+      },
+    },
+  ) as GatewaySpeechFactory;
   const createTranscriptionModel = (modelId: GatewayTranscriptionModelId) => {
     return new GatewayTranscriptionModel(modelId, {
       provider: 'gateway',
@@ -728,7 +792,7 @@ export async function getGatewayAuthToken(
 function assertGatewayClientSecretServerEnvironment(): void {
   if (typeof globalThis.window !== 'undefined') {
     throw new Error(
-      'AI Gateway client secrets must be minted server-side: minting needs your Gateway credential, which must never reach the browser. Call gateway.experimental_realtime.getToken() or gateway.experimental_transcription.getToken() from your server and pass the returned token to the client.',
+      'AI Gateway client secrets must be minted server-side: minting needs your Gateway credential, which must never reach the browser. Call gateway.experimental_realtime.getToken(), gateway.experimental_transcription.getToken(), or gateway.experimental_speech.getToken() from your server and pass the returned token to the client.',
     );
   }
 }

package/src/gateway-realtime-auth.ts

@@ -1,6 +1,6 @@
 /**
- * Shared WebSocket subprotocol contract for AI Gateway realtime and streaming
- * transcription auth.
+ * Shared WebSocket subprotocol contract for AI Gateway realtime, streaming
+ * transcription, and streaming speech auth.
  *
  * The browser `WebSocket` API cannot set request headers, so the Gateway auth
  * (bearer) token is carried through the `Sec-WebSocket-Protocol` handshake
@@ -9,7 +9,8 @@
  *
  * This module is the single source of truth for that contract so the client and
  * the Gateway server can't drift: the client encodes values with
- * `getGatewayRealtimeProtocols` / `getGatewayTranscriptionProtocols`, and the
+ * `getGatewayRealtimeProtocols` / `getGatewayTranscriptionProtocols` /
+ * `getGatewaySpeechProtocols`, and the
  * Gateway server decodes them with `getGatewayRealtimeAuthToken` /
  * `getGatewayRealtimeTeamIdOrSlug`.
  *
@@ -33,6 +34,12 @@ export const GATEWAY_REALTIME_SUBPROTOCOL = 'ai-gateway-realtime.v1';
  */
 export const GATEWAY_TRANSCRIPTION_SUBPROTOCOL = 'ai-gateway-transcription.v1';
 
+/**
+ * Marker subprotocol for streaming speech handshakes (same negotiation
+ * purpose as `GATEWAY_REALTIME_SUBPROTOCOL`).
+ */
+export const GATEWAY_SPEECH_SUBPROTOCOL = 'ai-gateway-speech.v1';
+
 /** Subprotocol prefix that carries the Gateway auth (bearer) token. */
 export const GATEWAY_AUTH_SUBPROTOCOL_PREFIX = 'ai-gateway-auth.';
 
@@ -65,6 +72,17 @@ export function getGatewayTranscriptionProtocols(
   );
 }
 
+/**
+ * Client-side: `getGatewayRealtimeProtocols`, but with the streaming speech
+ * marker subprotocol.
+ */
+export function getGatewaySpeechProtocols(
+  token: string,
+  options?: { teamIdOrSlug?: string },
+): string[] {
+  return buildGatewayProtocols(GATEWAY_SPEECH_SUBPROTOCOL, token, options);
+}
+
 function buildGatewayProtocols(
   marker: string,
   token: string,

package/src/gateway-realtime-model-settings.ts

@@ -6,6 +6,6 @@ export type GatewayRealtimeModelId =
   | 'openai/gpt-realtime-2'
   | 'openai/gpt-realtime-2.1'
   | 'openai/gpt-realtime-mini'
-  | 'spacexai/grok-voice-think-fast-1.0'
+  | 'spacexai/grok-voice-3.0'
   | 'spacexai/grok-voice-think-fast-2.0'
   | (string & {});

package/src/gateway-reranking-model-settings.ts

@@ -2,6 +2,8 @@ export type GatewayRerankingModelId =
   | 'cohere/rerank-v3.5'
   | 'cohere/rerank-v4-fast'
   | 'cohere/rerank-v4-pro'
+  | 'cohere/rerank-v5-fast'
+  | 'cohere/rerank-v5-pro'
   | 'voyage/rerank-2.5'
   | 'voyage/rerank-2.5-lite'
   | 'voyage/rerank-3'

package/src/gateway-speech-model-settings.ts

@@ -9,6 +9,7 @@ export type GatewaySpeechModelId =
   | 'microsoft/mai-voice-2-flash'
   | 'microsoft/mai-voice-2.1'
   | 'microsoft/mai-voice-2.1-flash'
+  | 'mistral/voxtral-mini-tts-3'
   | 'openai/tts-1'
   | 'openai/tts-1-hd'
   | 'spacexai/grok-tts'