@ai-sdk/cartesia 3.0.2 → 3.0.4

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @ai-sdk/cartesia
 
+## 3.0.4
+
+### Patch Changes
+
+- 529a5ef: Add Ink 2 streaming transcription through `TranscriptionModelV4.doStream` and the shared WebSocket transport.
+
+## 3.0.3
+
+### Patch Changes
+
+- Updated dependencies [31c7be8]
+  - @ai-sdk/provider-utils@5.0.10
+
 ## 3.0.2
 
 ### Patch Changes

package/README.md

@@ -1,7 +1,7 @@
 # AI SDK - Cartesia Provider
 
 The **[Cartesia provider](https://ai-sdk.dev/providers/ai-sdk-providers/cartesia)** for the [AI SDK](https://ai-sdk.dev/docs)
-contains Sonic 3.5 speech generation, Ink-Whisper batch transcription, and Ink 2 realtime transcription support.
+contains Sonic 3.5 speech generation, Ink-Whisper batch transcription, and Ink 2 realtime and streaming transcription support.
 
 > **Deploying to Vercel?** With Vercel's AI Gateway you can access Cartesia (and hundreds of models from other providers) — no additional packages, API keys, or extra cost. [Get started with AI Gateway](https://vercel.com/ai-gateway).
 

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import * as _ai_sdk_provider from '@ai-sdk/provider';
-import { SpeechModelV4, ProviderV4, TranscriptionModelV4, Experimental_RealtimeFactoryV4, Experimental_RealtimeModelV4, Experimental_RealtimeModelV4ClientSecretOptions, Experimental_RealtimeModelV4ClientSecretResult, Experimental_RealtimeModelV4ServerEvent, Experimental_RealtimeModelV4ClientEvent, Experimental_RealtimeModelV4SessionConfig } from '@ai-sdk/provider';
-import { FetchFunction, WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@ai-sdk/provider-utils';
+import { SpeechModelV4, ProviderV4, TranscriptionModelV4, Experimental_RealtimeFactoryV4, Experimental_TranscriptionModelV4StreamOptions, Experimental_RealtimeModelV4, Experimental_RealtimeModelV4ClientSecretOptions, Experimental_RealtimeModelV4ClientSecretResult, Experimental_RealtimeModelV4ServerEvent, Experimental_RealtimeModelV4ClientEvent, Experimental_RealtimeModelV4SessionConfig } from '@ai-sdk/provider';
+import { FetchFunction, WebSocketConstructor, WORKFLOW_SERIALIZE, WORKFLOW_DESERIALIZE } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 
-type CartesiaTranscriptionModelId = 'ink-whisper' | (string & {});
+type CartesiaTranscriptionModelId = 'ink-whisper' | 'ink-2' | (string & {});
 
 type CartesiaConfig = {
     provider: string;
@@ -13,6 +13,8 @@ type CartesiaConfig = {
     }) => string;
     headers?: () => Record<string, string | undefined>;
     fetch?: FetchFunction;
+    version?: string;
+    webSocket?: WebSocketConstructor;
     generateId?: () => string;
 };
 
@@ -81,6 +83,10 @@ interface CartesiaProviderSettings {
      * or to provide a custom fetch implementation for e.g. testing.
      */
     fetch?: FetchFunction;
+    /**
+     * Custom WebSocket implementation for streaming transcription.
+     */
+    webSocket?: WebSocketConstructor;
 }
 /**
  * Create a Cartesia provider instance.
@@ -112,6 +118,8 @@ declare class CartesiaTranscriptionModel implements TranscriptionModelV4 {
     constructor(modelId: CartesiaTranscriptionModelId, config: CartesiaTranscriptionModelConfig);
     private getArgs;
     doGenerate(options: Parameters<TranscriptionModelV4['doGenerate']>[0]): Promise<Awaited<ReturnType<TranscriptionModelV4['doGenerate']>>>;
+    doStream(options: Experimental_TranscriptionModelV4StreamOptions): Promise<Awaited<ReturnType<NonNullable<TranscriptionModelV4['doStream']>>>>;
+    private createStreamingAccessToken;
 }
 
 type CartesiaRealtimeModelId = 'ink-2' | (string & {});
@@ -160,10 +168,10 @@ declare const cartesiaSpeechModelOptionsSchema: z.ZodObject<{
         mp3: "mp3";
     }>>>;
     encoding: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
-        pcm_f32le: "pcm_f32le";
         pcm_s16le: "pcm_s16le";
         pcm_mulaw: "pcm_mulaw";
         pcm_alaw: "pcm_alaw";
+        pcm_f32le: "pcm_f32le";
     }>>>;
     sampleRate: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<8000>, z.ZodLiteral<16000>, z.ZodLiteral<22050>, z.ZodLiteral<24000>, z.ZodLiteral<44100>, z.ZodLiteral<48000>]>>>;
     bitRate: z.ZodOptional<z.ZodNullable<z.ZodUnion<readonly [z.ZodLiteral<32000>, z.ZodLiteral<64000>, z.ZodLiteral<96000>, z.ZodLiteral<128000>, z.ZodLiteral<192000>]>>>;
@@ -177,6 +185,9 @@ declare const cartesiaTranscriptionModelOptionsSchema: z.ZodObject<{
     timestampGranularities: z.ZodOptional<z.ZodNullable<z.ZodArray<z.ZodEnum<{
         word: "word";
     }>>>>;
+    streaming: z.ZodOptional<z.ZodObject<{
+        turnDetection: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 type CartesiaTranscriptionModelOptions = z.infer<typeof cartesiaTranscriptionModelOptionsSchema>;
 

package/dist/index.js

@@ -8,14 +8,23 @@ import {
 } from "@ai-sdk/provider-utils";
 
 // src/cartesia-transcription-model.ts
+import {
+  InvalidArgumentError,
+  UnsupportedFunctionalityError
+} from "@ai-sdk/provider";
 import {
   combineHeaders,
+  connectToWebSocket,
   convertBase64ToUint8Array,
   createJsonResponseHandler,
   mediaTypeToExtension,
   parseProviderOptions,
   postFormDataToApi,
+  postJsonToApi,
+  safeParseJSON,
   serializeModelOptions,
+  toWebSocketUrl,
+  waitForWebSocketBufferDrain,
   WORKFLOW_SERIALIZE,
   WORKFLOW_DESERIALIZE
 } from "@ai-sdk/provider-utils";
@@ -42,7 +51,15 @@ var cartesiaTranscriptionModelOptionsSchema = z2.object({
   /** The language of the audio (ISO 639-1 code). Defaults to English. */
   language: z2.string().nullish(),
   /** The timestamp granularities to populate. Currently only `word` is supported. */
-  timestampGranularities: z2.array(z2.enum(["word"])).nullish()
+  timestampGranularities: z2.array(z2.enum(["word"])).nullish(),
+  /** Options for realtime Ink 2 transcription over WebSocket. */
+  streaming: z2.object({
+    /**
+     * Use Cartesia's native turn detection endpoint. Defaults to true.
+     * Disable this to finalize the transcript only when the audio stream ends.
+     */
+    turnDetection: z2.boolean().optional()
+  }).optional()
 });
 
 // src/cartesia-transcription-model.ts
@@ -75,6 +92,13 @@ var CartesiaTranscriptionModel = class _CartesiaTranscriptionModel {
       providerOptions,
       schema: cartesiaTranscriptionModelOptionsSchema
     });
+    if ((cartesiaOptions == null ? void 0 : cartesiaOptions.streaming) != null) {
+      warnings.push({
+        type: "unsupported",
+        feature: "providerOptions.cartesia.streaming",
+        details: "Cartesia batch transcription does not support streaming options."
+      });
+    }
     const formData = new FormData();
     const blob = audio instanceof Uint8Array ? new Blob([audio]) : new Blob([convertBase64ToUint8Array(audio)]);
     const fileExtension = mediaTypeToExtension(mediaType);
@@ -101,6 +125,11 @@ var CartesiaTranscriptionModel = class _CartesiaTranscriptionModel {
   }
   async doGenerate(options) {
     var _a, _b, _c, _d, _e, _f, _g, _h, _i;
+    if (isStreamingTranscriptionModelId(this.modelId)) {
+      throw new UnsupportedFunctionalityError({
+        functionality: `non-streaming transcription with ${this.modelId}`
+      });
+    }
     const currentDate = (_c = (_b = (_a = this.config._internal) == null ? void 0 : _a.currentDate) == null ? void 0 : _b.call(_a)) != null ? _c : /* @__PURE__ */ new Date();
     const { formData, warnings } = await this.getArgs(options);
     const {
@@ -139,7 +168,287 @@ var CartesiaTranscriptionModel = class _CartesiaTranscriptionModel {
       }
     };
   }
+  async doStream(options) {
+    var _a, _b, _c, _d, _e, _f;
+    if (!isStreamingTranscriptionModelId(this.modelId)) {
+      throw new UnsupportedFunctionalityError({
+        functionality: `streaming transcription with ${this.modelId}`
+      });
+    }
+    const currentDate = (_c = (_b = (_a = this.config._internal) == null ? void 0 : _a.currentDate) == null ? void 0 : _b.call(_a)) != null ? _c : /* @__PURE__ */ new Date();
+    const warnings = [];
+    const cartesiaOptions = await parseProviderOptions({
+      provider: "cartesia",
+      providerOptions: options.providerOptions,
+      schema: cartesiaTranscriptionModelOptionsSchema
+    });
+    if ((cartesiaOptions == null ? void 0 : cartesiaOptions.language) != null && cartesiaOptions.language !== "en") {
+      throw new InvalidArgumentError({
+        argument: "providerOptions",
+        message: "Cartesia Ink 2 currently supports English only."
+      });
+    }
+    if ((cartesiaOptions == null ? void 0 : cartesiaOptions.timestampGranularities) != null) {
+      warnings.push({
+        type: "unsupported",
+        feature: "providerOptions.cartesia.timestampGranularities",
+        details: "Cartesia streaming transcription does not support timestamp granularities."
+      });
+    }
+    const token = await this.createStreamingAccessToken(options);
+    const useTurnDetection = ((_d = cartesiaOptions == null ? void 0 : cartesiaOptions.streaming) == null ? void 0 : _d.turnDetection) !== false;
+    const url = buildCartesiaStreamingTranscriptionUrl({
+      baseURL: this.config.url({ path: "/", modelId: this.modelId }),
+      version: (_e = this.config.version) != null ? _e : "2026-03-01",
+      modelId: this.modelId,
+      inputAudioFormat: options.inputAudioFormat,
+      providerOptions: cartesiaOptions,
+      token,
+      useTurnDetection
+    });
+    const requestUrl = new URL(url);
+    requestUrl.searchParams.delete("access_token");
+    return {
+      request: { body: requestUrl.toString() },
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId
+      },
+      stream: createCartesiaStreamingTranscriptionStream({
+        webSocket: this.config.webSocket,
+        url,
+        warnings,
+        language: (_f = cartesiaOptions == null ? void 0 : cartesiaOptions.language) != null ? _f : "en",
+        useTurnDetection,
+        audio: options.audio,
+        abortSignal: options.abortSignal,
+        includeRawChunks: options.includeRawChunks
+      })
+    };
+  }
+  async createStreamingAccessToken(options) {
+    var _a, _b;
+    const { value } = await postJsonToApi({
+      url: this.config.url({ path: "/access-token", modelId: this.modelId }),
+      headers: combineHeaders((_b = (_a = this.config).headers) == null ? void 0 : _b.call(_a), options.headers),
+      body: { grants: { stt: true } },
+      failedResponseHandler: cartesiaFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        cartesiaAccessTokenResponseSchema
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch
+    });
+    return value.token;
+  }
 };
+function createCartesiaStreamingTranscriptionStream({
+  webSocket,
+  url,
+  warnings,
+  language,
+  useTurnDetection,
+  audio,
+  abortSignal,
+  includeRawChunks
+}) {
+  let finished = false;
+  let cleanup = () => {
+  };
+  return new ReadableStream({
+    start: (controller) => {
+      const finalTexts = [];
+      let durationInSeconds = 0;
+      let audioReader;
+      let connection;
+      cleanup = (closeCode) => {
+        if (audioReader != null) {
+          void audioReader.cancel().catch(() => {
+          });
+        } else {
+          void audio.cancel().catch(() => {
+          });
+        }
+        connection == null ? void 0 : connection.close(closeCode);
+      };
+      const finishWithError = (error) => {
+        if (finished) return;
+        finished = true;
+        cleanup();
+        controller.error(error);
+      };
+      const finish = () => {
+        if (finished) return;
+        finished = true;
+        controller.enqueue({
+          type: "finish",
+          text: finalTexts.join(useTurnDetection ? " " : ""),
+          segments: [],
+          language,
+          ...durationInSeconds > 0 ? { durationInSeconds } : {}
+        });
+        controller.close();
+        cleanup(1e3);
+      };
+      const sendAudio = async (socket) => {
+        audioReader = audio.getReader();
+        try {
+          while (true) {
+            const { done, value } = await audioReader.read();
+            if (done || finished) break;
+            socket.send(
+              value instanceof Uint8Array ? value : convertBase64ToUint8Array(value)
+            );
+            await waitForWebSocketBufferDrain(socket);
+          }
+        } finally {
+          audioReader.releaseLock();
+          audioReader = void 0;
+        }
+        if (!finished) {
+          socket.send(
+            useTurnDetection ? JSON.stringify({ type: "close" }) : "finalize"
+          );
+        }
+      };
+      connection = connectToWebSocket({
+        url,
+        webSocket,
+        abortSignal,
+        onAbort: finishWithError,
+        onProcessingError: finishWithError,
+        onOpen: (socket) => {
+          controller.enqueue({ type: "stream-start", warnings });
+          void sendAudio(socket).catch(finishWithError);
+        },
+        onMessageText: async (text) => {
+          var _a, _b, _c, _d, _e, _f, _g;
+          const parsed = await safeParseJSON({ text });
+          if (!parsed.success) return;
+          const raw = parsed.value;
+          if (includeRawChunks) {
+            controller.enqueue({ type: "raw", rawValue: raw });
+          }
+          switch (raw.type) {
+            case "turn.update":
+            case "turn.eager_end": {
+              controller.enqueue({
+                type: "transcript-partial",
+                id: raw.request_id,
+                text: (_a = raw.transcript) != null ? _a : ""
+              });
+              break;
+            }
+            case "turn.end": {
+              const text2 = (_b = raw.transcript) != null ? _b : "";
+              finalTexts.push(text2);
+              controller.enqueue({
+                type: "transcript-final",
+                id: raw.request_id,
+                text: text2
+              });
+              break;
+            }
+            case "transcript": {
+              const transcript = (_c = raw.text) != null ? _c : "";
+              if (raw.is_final === true) {
+                finalTexts.push(transcript);
+                durationInSeconds += (_d = raw.duration) != null ? _d : 0;
+                controller.enqueue({
+                  type: "transcript-final",
+                  id: raw.request_id,
+                  text: transcript
+                });
+              } else {
+                controller.enqueue({
+                  type: "transcript-partial",
+                  id: raw.request_id,
+                  text: transcript,
+                  ...raw.duration != null ? { durationInSeconds: raw.duration } : {}
+                });
+              }
+              break;
+            }
+            case "flush_done": {
+              (_e = connection == null ? void 0 : connection.socket) == null ? void 0 : _e.send("close");
+              break;
+            }
+            case "done": {
+              finish();
+              break;
+            }
+            case "error": {
+              finishWithError(
+                new Error(
+                  (_g = (_f = raw.message) != null ? _f : raw.error_code) != null ? _g : "Cartesia streaming transcription error"
+                )
+              );
+              break;
+            }
+          }
+        },
+        onSocketError: () => {
+          finishWithError(new Error("Cartesia streaming transcription error"));
+        },
+        onClose: () => {
+          if (!finished) finish();
+        }
+      });
+    },
+    cancel: () => {
+      if (finished) return;
+      finished = true;
+      cleanup();
+    }
+  });
+}
+function buildCartesiaStreamingTranscriptionUrl({
+  baseURL,
+  version,
+  modelId,
+  inputAudioFormat,
+  providerOptions,
+  token,
+  useTurnDetection
+}) {
+  var _a;
+  const url = toWebSocketUrl(
+    new URL(
+      useTurnDetection ? "/stt/turns/websocket" : "/stt/websocket",
+      baseURL
+    )
+  );
+  url.searchParams.set("model", modelId);
+  url.searchParams.set(
+    "encoding",
+    cartesiaEncodingFromInputAudioFormat(inputAudioFormat.type)
+  );
+  url.searchParams.set("sample_rate", String((_a = inputAudioFormat.rate) != null ? _a : 24e3));
+  url.searchParams.set("cartesia_version", version);
+  url.searchParams.set("access_token", token);
+  if (!useTurnDetection && (providerOptions == null ? void 0 : providerOptions.language) != null) {
+    url.searchParams.set("language", providerOptions.language);
+  }
+  return url;
+}
+function cartesiaEncodingFromInputAudioFormat(type) {
+  switch (type) {
+    case "audio/pcm":
+      return "pcm_s16le";
+    case "audio/pcmu":
+      return "pcm_mulaw";
+    case "audio/pcma":
+      return "pcm_alaw";
+    default:
+      throw new InvalidArgumentError({
+        argument: "inputAudioFormat",
+        message: `Unsupported Cartesia streaming audio format: ${type}`
+      });
+  }
+}
+function isStreamingTranscriptionModelId(modelId) {
+  return modelId === "ink-2" || modelId.startsWith("ink-2-");
+}
 var cartesiaTranscriptionResponseSchema = z3.object({
   text: z3.string(),
   language: z3.string().nullish(),
@@ -152,13 +461,16 @@ var cartesiaTranscriptionResponseSchema = z3.object({
     })
   ).nullish()
 });
+var cartesiaAccessTokenResponseSchema = z3.object({
+  token: z3.string().min(1)
+});
 
 // src/cartesia-speech-model.ts
 import {
   combineHeaders as combineHeaders2,
   createBinaryResponseHandler,
   parseProviderOptions as parseProviderOptions2,
-  postJsonToApi,
+  postJsonToApi as postJsonToApi2,
   serializeModelOptions as serializeModelOptions2,
   WORKFLOW_SERIALIZE as WORKFLOW_SERIALIZE2,
   WORKFLOW_DESERIALIZE as WORKFLOW_DESERIALIZE2
@@ -359,7 +671,7 @@ var CartesiaSpeechModel = class _CartesiaSpeechModel {
       value: audio,
       responseHeaders,
       rawValue: rawResponse
-    } = await postJsonToApi({
+    } = await postJsonToApi2({
       url: this.config.url({
         path: "/tts/bytes",
         modelId: this.modelId
@@ -617,7 +929,7 @@ function resolveCartesiaEncoding(type) {
 }
 
 // src/version.ts
-var VERSION = true ? "3.0.2" : "0.0.0-test";
+var VERSION = true ? "3.0.4" : "0.0.0-test";
 
 // src/cartesia-provider.ts
 var CARTESIA_API_VERSION = "2026-03-01";
@@ -637,12 +949,17 @@ function createCartesia(options = {}) {
       `ai-sdk/cartesia/${VERSION}`
     );
   };
-  const createTranscriptionModel = (modelId) => new CartesiaTranscriptionModel(modelId, {
-    provider: `cartesia.transcription`,
-    url: ({ path }) => `https://api.cartesia.ai${path}`,
-    headers: getHeaders,
-    fetch: options.fetch
-  });
+  const createTranscriptionModel = (modelId) => {
+    var _a;
+    return new CartesiaTranscriptionModel(modelId, {
+      provider: `cartesia.transcription`,
+      url: ({ path }) => `https://api.cartesia.ai${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+      version: (_a = options.version) != null ? _a : CARTESIA_API_VERSION,
+      webSocket: options.webSocket
+    });
+  };
   const createSpeechModel = (modelId) => new CartesiaSpeechModel(modelId, {
     provider: `cartesia.speech`,
     url: ({ path }) => `https://api.cartesia.ai${path}`,