@ai-sdk/gateway 4.0.122 → 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">

package/package.json

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

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-speech-model.ts

@@ -1,4 +1,9 @@
 import type {
+  Experimental_SpeechModelV4StreamOptions as SpeechModelV4StreamOptions,
+  Experimental_SpeechModelV4StreamPart as SpeechModelV4StreamPart,
+  Experimental_SpeechModelV4StreamResult as SpeechModelV4StreamResult,
+  Experimental_SpeechModelV4StreamTextPart as SpeechModelV4StreamTextPart,
+  Experimental_StreamingSpeechModelV4 as StreamingSpeechModelV4,
   SharedV4ProviderMetadata,
   SharedV4Warning,
   SpeechModelV4,
@@ -7,19 +12,41 @@ import {
   lazySchema,
   zodSchema,
   combineHeaders,
+  connectToWebSocket,
   createJsonErrorResponseHandler,
   createJsonResponseHandler,
   getErrorMessage,
+  experimental_parseSpeechStreamPart as parseSpeechStreamPart,
   postJsonToApi,
   resolve,
+  EXPERIMENTAL_SPEECH_STREAM_START_FRAME_TYPE as SPEECH_STREAM_START_FRAME_TYPE,
+  EXPERIMENTAL_SPEECH_STREAM_TEXT_DELTA_FRAME_TYPE as SPEECH_STREAM_TEXT_DELTA_FRAME_TYPE,
+  EXPERIMENTAL_SPEECH_STREAM_TEXT_DONE_FRAME_TYPE as SPEECH_STREAM_TEXT_DONE_FRAME_TYPE,
+  waitForWebSocketBufferDrain,
+  type Experimental_SpeechStreamStartFrame,
+  type Experimental_SpeechStreamTextDeltaFrame,
   type Resolvable,
+  type WebSocketConnection,
+  type WebSocketConstructor,
+  type WebSocketLike,
 } from '@ai-sdk/provider-utils';
 import { z } from './zod';
 import { asGatewayError } from './errors';
 import { parseAuthMethod } from './errors/parse-auth-method';
 import type { GatewayConfig } from './gateway-config';
+import {
+  GATEWAY_SPEECH_SUBPROTOCOL,
+  getGatewaySpeechProtocols,
+} from './gateway-realtime-auth';
+import {
+  createErrorFromServerErrorPart,
+  errorControllerWithGatewayError,
+} from './gateway-stream-errors';
+import { getProtocolsFromHeaders } from './gateway-transcription-model';
 
-export class GatewaySpeechModel implements SpeechModelV4 {
+export class GatewaySpeechModel
+  implements SpeechModelV4, StreamingSpeechModelV4
+{
   readonly specificationVersion = 'v4' as const;
 
   constructor(
@@ -27,6 +54,9 @@ export class GatewaySpeechModel implements SpeechModelV4 {
     private readonly config: GatewayConfig & {
       provider: string;
       o11yHeaders: Resolvable<Record<string, string>>;
+      _internal?: {
+        currentDate?: () => Date;
+      };
     },
   ) {}
 
@@ -104,6 +134,59 @@ export class GatewaySpeechModel implements SpeechModelV4 {
     }
   }
 
+  async doStream(
+    options: SpeechModelV4StreamOptions,
+  ): Promise<SpeechModelV4StreamResult> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+
+    const headers = combineHeaders(
+      await resolve(this.config.headers ?? {}),
+      options.headers ?? {},
+      this.getModelConfigHeaders(),
+      await resolve(this.config.o11yHeaders),
+    );
+    const authMethod = await parseAuthMethod(headers);
+
+    // First frame after the WebSocket opens, per the speech-stream envelope.
+    // Optional keys are omitted so the frame stays minimal.
+    const startFrame: Experimental_SpeechStreamStartFrame = {
+      type: SPEECH_STREAM_START_FRAME_TYPE,
+      ...(options.voice != null && { voice: options.voice }),
+      ...(options.outputFormat != null && {
+        outputFormat: options.outputFormat,
+      }),
+      ...(options.instructions != null && {
+        instructions: options.instructions,
+      }),
+      ...(options.speed != null && { speed: options.speed }),
+      ...(options.language != null && { language: options.language }),
+      ...(options.providerOptions != null && {
+        providerOptions: options.providerOptions,
+      }),
+      ...(options.includeRawChunks != null && {
+        includeRawChunks: options.includeRawChunks,
+      }),
+    };
+
+    return {
+      stream: createGatewaySpeechStream({
+        webSocket: this.config.webSocket,
+        url: toGatewaySpeechUrl(this.config.baseURL, this.modelId),
+        protocols: getProtocolsFromHeaders(headers, {
+          marker: GATEWAY_SPEECH_SUBPROTOCOL,
+          getProtocols: getGatewaySpeechProtocols,
+        }),
+        headers,
+        startFrame,
+        text: options.text,
+        abortSignal: options.abortSignal,
+        authMethod,
+      }),
+      request: { body: startFrame },
+      response: { timestamp: currentDate, modelId: this.modelId },
+    };
+  }
+
   private getUrl() {
     return `${this.config.baseURL}/speech-model`;
   }
@@ -116,6 +199,227 @@ export class GatewaySpeechModel implements SpeechModelV4 {
   }
 }
 
+/**
+ * Gateway streaming speech WebSocket URL: HTTP(S) base upgraded to WS(S),
+ * model id in `?ai-model-id=` (browser `WebSocket` cannot set headers).
+ */
+export function toGatewaySpeechUrl(baseURL: string, modelId: string): string {
+  const url = new URL(`${baseURL.replace(/^http/, 'ws')}/speech-model`);
+  url.searchParams.set('ai-model-id', modelId);
+  return url.toString();
+}
+
+/**
+ * Keeps text-delta frames under 64 KiB (envelope rule 7) even when JSON
+ * escapes every code unit as `\uXXXX`.
+ */
+const MAX_TEXT_DELTA_CODE_UNITS = 8 * 1024;
+
+/**
+ * Splits a long text delta into pieces of at most `MAX_TEXT_DELTA_CODE_UNITS`
+ * UTF-16 code units without separating a surrogate pair.
+ */
+export function splitTextDelta(delta: string): string[] {
+  const pieces: string[] = [];
+  let offset = 0;
+  while (offset < delta.length) {
+    let end = Math.min(offset + MAX_TEXT_DELTA_CODE_UNITS, delta.length);
+    const lastCodeUnit = delta.charCodeAt(end - 1);
+    if (
+      end < delta.length &&
+      lastCodeUnit >= 0xd800 &&
+      lastCodeUnit <= 0xdbff
+    ) {
+      end--;
+    }
+    pieces.push(delta.slice(offset, end));
+    offset = end;
+  }
+  return pieces;
+}
+
+function createGatewaySpeechStream({
+  webSocket,
+  url,
+  protocols,
+  headers,
+  startFrame,
+  text,
+  abortSignal,
+  authMethod,
+}: {
+  webSocket: WebSocketConstructor | undefined;
+  url: string;
+  protocols: string[];
+  headers: Record<string, string | undefined>;
+  startFrame: Experimental_SpeechStreamStartFrame;
+  text: ReadableStream<SpeechModelV4StreamTextPart>;
+  abortSignal: AbortSignal | undefined;
+  authMethod: 'api-key' | 'oidc' | undefined;
+}): ReadableStream<SpeechModelV4StreamPart> {
+  let finished = false;
+  let cleanup: (closeCode?: number) => void = () => {};
+
+  return new ReadableStream<SpeechModelV4StreamPart>({
+    start: controller => {
+      let textReader:
+        | ReadableStreamDefaultReader<SpeechModelV4StreamTextPart>
+        | undefined;
+      let hasServerErrorPart = false;
+      let lastServerError: unknown;
+      let textStopped = false;
+      let connection: WebSocketConnection | undefined;
+
+      const cancelText = () => {
+        if (textReader != null) {
+          void textReader.cancel().catch(() => {});
+          textReader = undefined;
+        } else {
+          void text.cancel().catch(() => {});
+        }
+      };
+
+      cleanup = (closeCode?: number) => {
+        cancelText();
+        connection?.close(closeCode);
+      };
+
+      const finishWithError = (error: unknown) => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        void errorControllerWithGatewayError(controller, error, authMethod);
+      };
+
+      const sendText = async (socket: WebSocketLike) => {
+        const reader = text.getReader();
+        textReader = reader;
+        try {
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done || finished || textStopped) break;
+            let first = true;
+            // An empty part still carries its voice or provider options.
+            const pieces = splitTextDelta(value.text);
+            if (
+              pieces.length === 0 &&
+              (value.voice != null || value.providerOptions != null)
+            ) {
+              pieces.push('');
+            }
+            for (const delta of pieces) {
+              if (finished || textStopped) break;
+              // The voice applies to every frame of the part; provider
+              // options (e.g. a turn break) only to its first frame.
+              const frame: Experimental_SpeechStreamTextDeltaFrame = {
+                type: SPEECH_STREAM_TEXT_DELTA_FRAME_TYPE,
+                delta,
+                ...(value.voice != null && { voice: value.voice }),
+                ...(first &&
+                  value.providerOptions != null && {
+                    providerOptions: value.providerOptions,
+                  }),
+              };
+              first = false;
+              socket.send(JSON.stringify(frame));
+              await waitForWebSocketBufferDrain(socket);
+            }
+          }
+        } finally {
+          reader.releaseLock();
+          if (textReader === reader) {
+            textReader = undefined;
+          }
+        }
+        if (!finished && !textStopped) {
+          socket.send(
+            JSON.stringify({ type: SPEECH_STREAM_TEXT_DONE_FRAME_TYPE }),
+          );
+        }
+      };
+
+      connection = connectToWebSocket({
+        url,
+        protocols,
+        headers,
+        webSocket,
+        abortSignal,
+        onAbort: reason => {
+          if (finished) return;
+          finished = true;
+          cleanup();
+          controller.error(reason);
+        },
+        onProcessingError: finishWithError,
+        onOpen: socket => {
+          socket.send(JSON.stringify(startFrame));
+          void sendText(socket).catch(finishWithError);
+        },
+        onMessageText: async messageText => {
+          if (finished) return;
+          const part = parseSpeechStreamPart(messageText);
+          if (part == null) return;
+          if (part.type === 'finish') {
+            finished = true;
+            controller.enqueue(part);
+            controller.close();
+            cleanup(1000);
+            return;
+          }
+
+          if (part.type === 'error') {
+            // Error parts are terminal (envelope rule 5): stop sending text
+            // and surface the server's message when the socket closes.
+            hasServerErrorPart = true;
+            lastServerError = part.error;
+            textStopped = true;
+            cancelText();
+            part.error = await createErrorFromServerErrorPart(
+              part.error,
+              authMethod,
+              'speech',
+            );
+            if (finished) return;
+          }
+
+          controller.enqueue(part);
+        },
+        onSocketError: () => {
+          finishWithError(
+            new Error('Connection error on AI Gateway speech stream'),
+          );
+        },
+        onClose: ({ code, reason }) => {
+          if (hasServerErrorPart) {
+            if (finished) return;
+            void createErrorFromServerErrorPart(
+              lastServerError,
+              authMethod,
+              'speech',
+            ).then(finishWithError);
+            return;
+          }
+          finishWithError(
+            new Error(
+              'AI Gateway speech stream closed before a finish part was received' +
+                (code != null
+                  ? ` (code ${code}${reason ? `: ${reason}` : ''})`
+                  : '') +
+                '.',
+            ),
+          );
+        },
+      });
+    },
+
+    cancel: () => {
+      if (finished) return;
+      finished = true;
+      cleanup();
+    },
+  });
+}
+
 const providerMetadataEntrySchema = () => z.object({}).catchall(z.unknown());
 
 const gatewaySpeechWarningSchema = () =>

package/src/gateway-stream-errors.ts

@@ -0,0 +1,71 @@
+import { getErrorMessage } from '@ai-sdk/provider';
+import { asGatewayError, createGatewayErrorFromResponse } from './errors';
+
+/**
+ * `asGatewayError` is async while the WebSocket event handlers are
+ * synchronous, hence this helper.
+ */
+export async function errorControllerWithGatewayError<PART>(
+  controller: ReadableStreamDefaultController<PART>,
+  error: unknown,
+  authMethod: 'api-key' | 'oidc' | undefined,
+): Promise<void> {
+  controller.error(await asGatewayError(error, authMethod));
+}
+
+/**
+ * Extract a human-readable message from an `error` stream part's payload for
+ * the terminal close error.
+ */
+function getServerErrorMessage(error: unknown): string {
+  if (
+    error != null &&
+    typeof error === 'object' &&
+    'message' in error &&
+    typeof error.message === 'string'
+  ) {
+    return error.message;
+  }
+  // JSON-stringifies object payloads (`String` would yield '[object Object]').
+  return getErrorMessage(error);
+}
+
+/** Canonical status codes for server error-part types (no HTTP status exists on the WebSocket). */
+const SERVER_ERROR_STATUS_CODES: Record<string, number> = {
+  authentication_error: 401,
+  failed_dependency: 424,
+  forbidden: 403,
+  internal_server_error: 500,
+  invalid_request_error: 400,
+  model_not_found: 404,
+  rate_limit_exceeded: 429,
+};
+
+/**
+ * Maps a server error-part payload (`{ message, type }`) to the public
+ * Gateway error class for its type; unknown shapes keep the generic message.
+ */
+export async function createErrorFromServerErrorPart(
+  error: unknown,
+  authMethod: 'api-key' | 'oidc' | undefined,
+  streamLabel = 'transcription',
+): Promise<unknown> {
+  if (
+    typeof error === 'object' &&
+    error != null &&
+    'message' in error &&
+    typeof error.message === 'string' &&
+    'type' in error &&
+    typeof error.type === 'string' &&
+    error.type in SERVER_ERROR_STATUS_CODES
+  ) {
+    return createGatewayErrorFromResponse({
+      response: { error: { message: error.message, type: error.type } },
+      statusCode: SERVER_ERROR_STATUS_CODES[error.type],
+      authMethod,
+    });
+  }
+  return new Error(
+    `AI Gateway ${streamLabel} stream failed: ${getServerErrorMessage(error)}`,
+  );
+}