feat(examples): add Cartesia Sonic 3.5 and Ink demo

.changeset/bright-dolphins-speak.md

@@ -0,0 +1,6 @@
+---
+'@ai-sdk/cartesia': patch
+'ai': patch
+---
+
+Add the Cartesia provider with Sonic 3.5 speech generation, Ink-Whisper batch transcription, and Ink 2 realtime transcription support.

.github/konsistent.json

@@ -371,6 +371,7 @@
   "kebabToPascalMap": {
     "assemblyai": "AssemblyAI",
     "bytedance": "ByteDance",
+    "cartesia": "Cartesia",
     "deepagents": "DeepAgents",
     "deepinfra": "DeepInfra",
     "deepseek": "DeepSeek",

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

@@ -306,5 +306,6 @@ try {
 | [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models) | `chirp_3`                |
 | [Google Vertex](/providers/ai-sdk-providers/google-vertex#transcription-models) | `telephony`              |
 | [xAI](/providers/ai-sdk-providers/xai#transcription-models)                     | `default`                |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#transcription-models)           | `ink-whisper`            |
 
 Above are a small subset of the transcription models supported by the AI SDK providers. For more, see the respective provider documentation.

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

@@ -168,5 +168,9 @@ try {
 | [Google Vertex](/providers/ai-sdk-providers/google-vertex#speech-models) | `gemini-2.5-flash-lite-preview-tts` |
 | [Google Vertex](/providers/ai-sdk-providers/google-vertex#speech-models) | `gemini-3.1-flash-tts-preview`      |
 | [xAI](/providers/ai-sdk-providers/xai#speech-models)                     | `default`                           |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-3.5`                         |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-3`                           |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-2`                           |
+| [Cartesia](/providers/ai-sdk-providers/cartesia#speech-models)           | `sonic-turbo`                       |
 
 Above are a small subset of the speech models supported by the AI SDK providers. For more, see the respective provider documentation.

content/providers/01-ai-sdk-providers/95-cartesia.mdx

@@ -0,0 +1,262 @@
+---
+title: Cartesia
+description: Learn how to use the Cartesia provider for the AI SDK.
+---
+
+# Cartesia Provider
+
+The [Cartesia](https://cartesia.ai/) provider contains Sonic speech generation,
+Ink-Whisper batch transcription, and Ink 2 realtime transcription support.
+
+## Setup
+
+The Cartesia provider is available in the `@ai-sdk/cartesia` module. You can install it with
+
+<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/cartesia" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/cartesia" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/cartesia" dark />
+  </Tab>
+
+  <Tab>
+    <Snippet text="bun add @ai-sdk/cartesia" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `cartesia` from `@ai-sdk/cartesia`:
+
+```ts
+import { cartesia } from '@ai-sdk/cartesia';
+```
+
+If you need a customized setup, you can import `createCartesia` from `@ai-sdk/cartesia` and create a provider instance with your settings:
+
+```ts
+import { createCartesia } from '@ai-sdk/cartesia';
+
+const cartesia = createCartesia({
+  // custom settings, e.g.
+  fetch: customFetch,
+});
+```
+
+You can use the following optional settings to customize the Cartesia provider instance:
+
+- **apiKey** _string_
+
+  API key that is being sent using the `Authorization` header.
+  It defaults to the `CARTESIA_API_KEY` environment variable.
+
+- **version** _string_
+
+  The Cartesia API version to use (sent via the `Cartesia-Version` header).
+
+- **headers** _Record&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
+  Defaults to the global `fetch` function.
+  You can use it as a middleware to intercept requests,
+  or to provide a custom fetch implementation for e.g. testing.
+
+## Speech Models
+
+You can create models that call the [Cartesia text-to-speech API](https://docs.cartesia.ai/api-reference/tts/bytes)
+using the `.speech()` factory method.
+
+The first argument is the model id, e.g. `sonic-3.5`.
+
+```ts
+const model = cartesia.speech('sonic-3.5');
+```
+
+You can use the model with the `generateSpeech` function. Cartesia requires a `voice` id:
+
+```ts
+import { generateSpeech } from 'ai';
+import { cartesia } from '@ai-sdk/cartesia';
+
+const result = await generateSpeech({
+  model: cartesia.speech('sonic-3.5'),
+  text: 'Hello, world!',
+  voice: '694f9389-aac1-45b6-b726-9d9369183238',
+});
+```
+
+You can also pass additional provider-specific options using the `providerOptions` argument:
+
+```ts highlight="7-12"
+import { generateSpeech } from 'ai';
+import { cartesia, type CartesiaSpeechModelOptions } from '@ai-sdk/cartesia';
+
+const result = await generateSpeech({
+  model: cartesia.speech('sonic-3.5'),
+  text: 'Hello, world!',
+  voice: '694f9389-aac1-45b6-b726-9d9369183238',
+  providerOptions: {
+    cartesia: {
+      container: 'wav',
+      encoding: 'pcm_s16le',
+      sampleRate: 24000,
+    } satisfies CartesiaSpeechModelOptions,
+  },
+});
+```
+
+The following provider options are available:
+
+- **container** _string_
+
+  Container format for the output audio.
+  Supported values: `'raw'`, `'wav'`, `'mp3'`.
+  Optional.
+
+- **encoding** _string_
+
+  Encoding type for the audio output.
+  Supported values: `'pcm_f32le'`, `'pcm_s16le'`, `'pcm_mulaw'`, `'pcm_alaw'`.
+  Optional.
+
+- **sampleRate** _number_
+
+  Sample rate for the output audio in Hz (e.g. `8000`, `16000`, `22050`, `24000`, `44100`, `48000`).
+  Optional.
+
+- **bitRate** _number_
+
+  Bitrate for `mp3` output in bits per second (e.g. `32000`, `64000`, `128000`, `192000`).
+  Optional.
+
+- **speed** _number_
+
+  Controls the speed of the generated speech between `0.6` and `1.5`.
+  Optional.
+
+- **language** _string_
+
+  The language to generate speech in (ISO 639-1 code).
+  Optional.
+
+### Model Capabilities
+
+| Model          |
+| -------------- |
+| `sonic-3.5`    |
+| `sonic-3`      |
+| `sonic-2`      |
+| `sonic-turbo`  |
+| `sonic-latest` |
+
+## Realtime Transcription Models
+
+<Note type="warning">Realtime is an experimental feature.</Note>
+
+You can create a model for Cartesia's realtime [Ink 2](https://docs.cartesia.ai/build-with-cartesia/stt/latest)
+API using the `.experimental_realtime()` factory method:
+
+```ts
+import { cartesia } from '@ai-sdk/cartesia';
+
+const model = cartesia.experimental_realtime('ink-2');
+```
+
+Realtime sessions run in the browser and require a short-lived access token
+created on your server with `cartesia.experimental_realtime.getToken()`:
+
+```ts
+const token = await cartesia.experimental_realtime.getToken({
+  model: 'ink-2',
+  sessionConfig: {
+    inputAudioFormat: { type: 'audio/pcm', rate: 24000 },
+    inputAudioTranscription: { language: 'en' },
+    turnDetection: { type: 'server-vad' },
+  },
+});
+```
+
+Ink 2 produces input transcription events and supports English audio. Turn
+detection is enabled by default. To use manual finalization instead, set
+`turnDetection` to `null` in the session config and call `commitAudio()` when
+the current input is complete.
+
+See [Realtime](/docs/ai-sdk-core/realtime) for the complete browser session
+setup.
+
+### Model Capabilities
+
+| Model   | Streaming Transcription | Turn Detection      |
+| ------- | ----------------------- | ------------------- |
+| `ink-2` | <Check size={18} />     | <Check size={18} /> |
+
+## Batch Transcription Models
+
+You can create models that call the [Cartesia transcription API](https://docs.cartesia.ai/api-reference/stt/transcribe)
+using the `.transcription()` factory method.
+
+The first argument is the model id e.g. `ink-whisper`.
+
+```ts
+const model = cartesia.transcription('ink-whisper');
+```
+
+You can use the model with the `transcribe` function:
+
+```ts
+import { transcribe } from 'ai';
+import { cartesia } from '@ai-sdk/cartesia';
+import { readFile } from 'fs/promises';
+
+const result = await transcribe({
+  model: cartesia.transcription('ink-whisper'),
+  audio: await readFile('audio.mp3'),
+});
+```
+
+You can also pass additional provider-specific options using the `providerOptions` argument:
+
+```ts highlight="6"
+import { transcribe } from 'ai';
+import {
+  cartesia,
+  type CartesiaTranscriptionModelOptions,
+} from '@ai-sdk/cartesia';
+import { readFile } from 'fs/promises';
+
+const result = await transcribe({
+  model: cartesia.transcription('ink-whisper'),
+  audio: await readFile('audio.mp3'),
+  providerOptions: {
+    cartesia: {
+      language: 'en',
+    } satisfies CartesiaTranscriptionModelOptions,
+  },
+});
+```
+
+The following provider options are available:
+
+- **language** _string_
+
+  The language of the audio (ISO 639-1 code). If not specified, it defaults to English.
+  Optional.
+
+- **timestampGranularities** _array of strings_
+
+  The timestamp granularities to populate. Currently only `'word'` is supported.
+  Optional.
+
+### Model Capabilities
+
+| Model         | Transcription       | Duration            | Segments            | Language            |
+| ------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `ink-whisper` | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> |

examples/ai-functions/package.json

@@ -13,6 +13,7 @@
     "@ai-sdk/baseten": "workspace:*",
     "@ai-sdk/black-forest-labs": "workspace:*",
     "@ai-sdk/bytedance": "workspace:*",
+    "@ai-sdk/cartesia": "workspace:*",
     "@ai-sdk/cerebras": "workspace:*",
     "@ai-sdk/cohere": "workspace:*",
     "@ai-sdk/deepgram": "workspace:*",

examples/ai-functions/src/generate-speech/cartesia/basic.ts

@@ -0,0 +1,19 @@
+import { cartesia } from '@ai-sdk/cartesia';
+import { generateSpeech } from 'ai';
+import { saveAudioFile } from '../../lib/save-audio';
+import { run } from '../../lib/run';
+
+run(async () => {
+  const result = await generateSpeech({
+    model: cartesia.speech('sonic-3.5'),
+    text: 'Hello, welcome to Cartesia! This is a test of the text-to-speech API.',
+    voice: 'a0e99841-438c-4a64-b679-ae501e7d6091',
+  });
+
+  console.log('Audio:', result.audio);
+  console.log('Warnings:', result.warnings);
+  console.log('Responses:', result.responses);
+  console.log('Provider Metadata:', result.providerMetadata);
+
+  await saveAudioFile(result.audio);
+});

examples/ai-functions/src/transcribe/cartesia/basic.ts

@@ -0,0 +1,18 @@
+import { cartesia } from '@ai-sdk/cartesia';
+import { transcribe } from 'ai';
+import { readFile } from 'fs/promises';
+import { run } from '../../lib/run';
+
+run(async () => {
+  const result = await transcribe({
+    model: cartesia.transcription('ink-whisper'),
+    audio: await readFile('data/galileo.mp3'),
+  });
+
+  console.log('Text:', result.text);
+  console.log('Duration:', result.durationInSeconds);
+  console.log('Language:', result.language);
+  console.log('Segments:', result.segments);
+  console.log('Warnings:', result.warnings);
+  console.log('Responses:', result.responses);
+});

examples/ai-functions/tsconfig.json

@@ -54,6 +54,9 @@
     {
       "path": "../../packages/bytedance"
     },
+    {
+      "path": "../../packages/cartesia"
+    },
     {
       "path": "../../packages/cerebras"
     },

examples/cartesia-tts-demo/.env.example

@@ -0,0 +1,10 @@
+# cartesia-tts-demo credentials — read as environment variables by server.mjs.
+# Copy this file to `.env` and fill in your key, then run `pnpm start`.
+# Do NOT commit your real `.env`.
+
+# Cartesia API key from https://play.cartesia.ai/
+CARTESIA_API_KEY=
+
+# Default voice ID for Sonic TTS (optional — the UI also accepts a voice ID).
+# Find voice IDs in the Cartesia playground or API docs.
+CARTESIA_VOICE_ID=a0e99841-438c-4a64-b679-ae501e7d6091

examples/cartesia-tts-demo/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@example/cartesia-tts-demo",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Local browser demo for Cartesia Sonic 3.5 speech and Ink-Whisper batch transcription via @ai-sdk/cartesia (uses workspace source).",
+  "scripts": {
+    "prestart": "pnpm --filter ai... --filter @ai-sdk/cartesia... build",
+    "start": "NODE_EXTRA_CA_CERTS=${NODE_EXTRA_CA_CERTS:-/etc/ssl/cert.pem} node --env-file-if-exists=.env server.mjs"
+  },
+  "dependencies": {
+    "@ai-sdk/cartesia": "workspace:*",
+    "ai": "workspace:*"
+  }
+}