@opencode/ai 0.0.0-dev-20039 → 0.0.0-dev-20041

package/README.md

@@ -682,6 +682,90 @@ const generation = await ai.video.start({ model, prompt })
 const video = await generation.await({ poll: { interval: 10_000 }, signal })
 ```
 
+## Speech generation
+
+Speech (text-to-speech) is one request whose response is parsed incrementally, so every route supports both
+`Speech.generate` (the whole file) and `Speech.stream` (audio chunks as they arrive). Models come from `.speech(...)`
+selectors on the `OpenAI`, `Google` (Gemini TTS), `ElevenLabs`, `Cartesia`, and `Deepgram` facades. Common fields
+(`voice`, `format`, `speed`, `language`, `instructions`, `timestamps`) lower natively or fail with a typed `AIError`
+before any network call; provider-native controls live under `providerOptions`, inferred from the selected model.
+
+```ts
+import { Media, Speech, SpeechClient, SpeechEvent } from "@opencode/ai"
+import { ElevenLabs, OpenAI } from "@opencode/ai/providers"
+
+const openai = OpenAI.configure({ apiKey: process.env.OPENAI_API_KEY })
+
+// The whole file, written to disk.
+const program = Effect.gen(function* () {
+  const response = yield* Speech.generate({
+    model: openai.speech("gpt-4o-mini-tts"),
+    text: "Hello from OpenCode.",
+    voice: "coral",
+    format: "mp3",
+    instructions: "Warm and unhurried.",
+  })
+  response.audio // Media.Asset with bytes; headerless PCM carries info.encoding / sampleRate / channels
+  response.usage // undefined: OpenAI reports tokens only on SSE streams (Gemini: tokens; ElevenLabs: credits; Deepgram: characters)
+  yield* Media.write(response.audio, "hello.mp3")
+})
+
+// Chunks as they arrive: audio-delta* (interleaved with timestamps) then one finish carrying the assembled asset.
+const events = Speech.stream({
+  model: ElevenLabs.configure({ apiKey }).speech("eleven_flash_v2_5"),
+  text: "Hello from OpenCode.",
+  voice: "JBFqnCBsd6RMkjVDRZzb",
+  format: "pcm",
+  timestamps: true,
+}).pipe(
+  Stream.tap((event) => {
+    if (SpeechEvent.is.audioDelta(event)) return play(event.chunk)
+    if (SpeechEvent.is.timestamps(event)) return highlight(event.items) // { text, startSeconds, endSeconds }[]
+    return Effect.void
+  }),
+)
+```
+
+`voice` is the provider's own identifier — a name on OpenAI and Gemini (`"coral"`, `"Kore"`), a voice id on
+ElevenLabs and Cartesia. `{ id }` selects an OpenAI custom voice (`{ id: "voice_1234" }`) and means the same as the
+plain string elsewhere. There is no cross-provider voice catalog. `format` is the container-level word (`mp3`, `wav`,
+`pcm`, `opus`, `aac`, `flac`); sample rates and bitrates live under `providerOptions`, and a value the route cannot
+produce fails as `UnsupportedOperation`. Streams buffer every chunk so `finish` can carry the whole clip.
+`SpeechClient.layer` needs `RequestExecutor.Service`.
+
+Provider notes:
+
+- **OpenAI** streams over SSE (`stream_format: "sse"`), which is also the only place it reports token usage; `tts-1`
+  and `tts-1-hd` do not support SSE and stream the raw audio body instead. `pcm` is 24 kHz 16-bit mono. `language`
+  and `timestamps` are not supported.
+- **Gemini TTS** returns raw 16-bit PCM only (`audio/L16;codec=pcm;rate=24000`), so any `format` other than `pcm`
+  fails typed; wrap the samples yourself. Style is directed in the text, so `instructions` and `speed` fail typed.
+  Only `gemini-3.1-flash-tts-preview` and later support streaming. Two-speaker audio goes through
+  `providerOptions.speechConfig.multiSpeakerVoiceConfig`.
+- **ElevenLabs** requires `voice` (the path voice id) and authenticates with `xi-api-key`. `format` maps to the
+  `output_format` query parameter (`mp3_44100_128`, `pcm_24000`, `wav_24000`, `opus_48000_64`);
+  `providerOptions.outputFormat` sets the exact string. WAV is only available from `generate`. `timestamps: true`
+  selects the `with-timestamps` endpoints and yields character-level alignment. `instructions` is not supported.
+- **Cartesia** requires `voice` and pins `Cartesia-Version`. `generate` defaults to MP3 from `/tts/bytes`; streams
+  and `timestamps: true` (word-level) use `/tts/sse`, which only serves raw PCM. `providerOptions.sampleRate`,
+  `bitRate`, and `encoding` complete `output_format`. No usage is reported.
+- **Deepgram** Aura's voice is the model id (`aura-2-thalia-en`), so `voice` and `language` fail typed. `format`
+  and `providerOptions` lower to query parameters (`encoding`, `container`, `sample_rate`, `bit_rate`); `pcm` is
+  `linear16` without a container. Auth is `Authorization: Token <DEEPGRAM_API_KEY>`.
+
+The promise client mirrors the Effect API; `ai.speech.stream` is an `AsyncIterable`.
+
+```ts
+import { ai } from "@opencode/ai/promise"
+
+const response = await ai.speech.generate({ model, text: "Hello from OpenCode.", voice: "coral" })
+await Bun.write("hello.mp3", await ai.run(response.audio.bytes()))
+
+for await (const event of ai.speech.stream({ model, text: "Hello from OpenCode.", voice: "coral" })) {
+  if (event.type === "audio-delta") player.write(event.chunk)
+}
+```
+
 ## Public API
 
 - **`LLM.request({...})`** — build a provider-neutral `LLMRequest`. Accepts ergonomic inputs (`system: string`, `prompt: string`) that normalize into the canonical Schema classes.
@@ -693,7 +777,8 @@ const video = await generation.await({ poll: { interval: 10_000 }, signal })
 - **`ImageClient`** — Effect service and layer for image execution, parallel to `LLMClient`.
 - **`Media`** — the shared asset type (`Media.Asset`, `Media.Source`) and constructors used by messages, tool results, and media requests.
 - **`Generation`** — provider-neutral handle for an in-flight media generation (`await`, `refresh`, `cancel`, `events`) used by queued media routes.
-- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm` and `image` as Promise / `AsyncIterable` APIs.
+- **`Speech.request` / `Speech.generate` / `Speech.stream`** — text-to-speech through a provider-neutral request; `SpeechClient` is its Effect service and layer.
+- **`@opencode/ai/promise`** — `AI.make({ layer? })` and a default `ai` client exposing `llm`, `image`, `video`, and `speech` as Promise / `AsyncIterable` APIs.
 
 ## Testing
 

package/dist/index.d.ts

@@ -13,6 +13,10 @@ export { VideoClient } from "./video-client.js";
 export { VideoAspectRatio, VideoEvent, VideoFrames, VideoModel, VideoModelSchema, VideoRequest, VideoResponse, } from "./video.js";
 export type { VideoModelOptions, VideoOptions, VideoRequestFor, VideoRequestInput, VideoResolution, VideoRoute, } from "./video.js";
 export { Video } from "./video.js";
+export { SpeechClient } from "./speech-client.js";
+export { SpeechEvent, SpeechModel, SpeechModelSchema, SpeechRequest, SpeechResponse, SpeechTimestamp, SpeechVoice, } from "./speech.js";
+export type { SpeechFormat, SpeechModelOptions, SpeechOptions, SpeechRequestFor, SpeechRequestInput, SpeechRoute, } from "./speech.js";
+export { Speech } from "./speech.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
 export type { AwaitOptions as GenerationAwaitOptions, Event as GenerationEvent, Poll, Route as GenerationRoute, Snapshot as GenerationSnapshot, Status as GenerationStatus, } from "./generation.js";

package/dist/index.js

@@ -10,6 +10,9 @@ export { Image } from "./image.js";
 export { VideoClient } from "./video-client.js";
 export { VideoAspectRatio, VideoEvent, VideoFrames, VideoModel, VideoModelSchema, VideoRequest, VideoResponse, } from "./video.js";
 export { Video } from "./video.js";
+export { SpeechClient } from "./speech-client.js";
+export { SpeechEvent, SpeechModel, SpeechModelSchema, SpeechRequest, SpeechResponse, SpeechTimestamp, SpeechVoice, } from "./speech.js";
+export { Speech } from "./speech.js";
 export { Media } from "./media.js";
 export { Generation } from "./generation.js";
 export { Tool, ToolFailure, toDefinitions } from "./tool.js";

package/dist/media-model.d.ts

@@ -5,8 +5,8 @@ import type { MediaProtocol } from "./route/media-protocol.js";
 import { AIError, HttpOptions, ModelID, ProviderID } from "./schema/index.js";
 /**
  * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
- * (`ImageModel`, `VideoModel`) extend it with their route type and a nominal marker so one cannot stand in for the
- * other in requests.
+ * (`ImageModel`, `VideoModel`, `SpeechModel`) extend it with their route type and a nominal marker so one cannot stand
+ * in for the other in requests.
  */
 export declare class MediaModel<Route, Options> {
     protected readonly _Options: (options: Options) => Options;
@@ -34,7 +34,7 @@ export declare namespace MediaModel {
         readonly headers?: Record<string, string>;
     }
 }
-/** Compose a protocol route input with one deployment through `MediaRoute.inline` or `MediaRoute.queued`. */
+/** Compose a protocol route input with one deployment through `MediaRoute.inline`, `queued`, or `stream`. */
 export declare const composeRoute: <Request extends MediaRoute.MediaRequest, Protocol, Route>(compose: (input: MediaRoute.Composition<Request> & {
     readonly protocol: Protocol;
 }) => Route, route: MediaModel.RouteInput<Request, Protocol>, input: MediaRoute.ModelInput) => Route;

package/dist/media-model.js

@@ -3,8 +3,8 @@ import { Endpoint } from "./route/endpoint.js";
 import { AIError, HttpOptions, InvalidRequestError, ModelID, ProviderID } from "./schema/index.js";
 /**
  * What every media model carries: ids, the configured route, and deployment `http` overlays. Modality classes
- * (`ImageModel`, `VideoModel`) extend it with their route type and a nominal marker so one cannot stand in for the
- * other in requests.
+ * (`ImageModel`, `VideoModel`, `SpeechModel`) extend it with their route type and a nominal marker so one cannot stand
+ * in for the other in requests.
  */
 export class MediaModel {
     id;
@@ -18,7 +18,7 @@ export class MediaModel {
         this.http = input.http;
     }
 }
-/** Compose a protocol route input with one deployment through `MediaRoute.inline` or `MediaRoute.queued`. */
+/** Compose a protocol route input with one deployment through `MediaRoute.inline`, `queued`, or `stream`. */
 export const composeRoute = (compose, route, input) => compose({
     id: route.id,
     provider: route.provider,

package/dist/promise.d.ts

@@ -6,11 +6,13 @@ import { LLMClient } from "./route/client.js";
 import { RequestExecutor } from "./route/executor.js";
 import { LanguageModel, LLMRequest } from "./schema/index.js";
 import type { RequestInput } from "./llm.js";
+import { SpeechModel, SpeechRequest, type SpeechRequestInput } from "./speech.js";
+import { SpeechClient } from "./speech-client.js";
 import { VideoModel, VideoRequest, type VideoOptions, type VideoRequestInput } from "./video.js";
 import { VideoClient } from "./video-client.js";
 /**
- * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM, image, and video
- * clients over a request executor; every method runs the corresponding Effect API and rethrows `AIError` unchanged.
+ * Promise-first entrypoint for scripts and non-Effect callers. One `ManagedRuntime` hosts the LLM, image, video, and
+ * speech clients over a request executor; every method runs the corresponding Effect API and rethrows `AIError` unchanged.
  */
 export interface Options {
     /** Executor layer; defaults to `RequestExecutor.fetchLayer`. Inject a recorder or middleware here. */
@@ -19,7 +21,7 @@ export interface Options {
 export interface RunOptions {
     readonly signal?: AbortSignal;
 }
-export type Services = Layer.Success<typeof LLMClient.layer> | Layer.Success<typeof ImageClient.layer> | Layer.Success<typeof VideoClient.layer> | RequestExecutor.Service;
+export type Services = Layer.Success<typeof LLMClient.layer> | Layer.Success<typeof ImageClient.layer> | Layer.Success<typeof VideoClient.layer> | Layer.Success<typeof SpeechClient.layer> | RequestExecutor.Service;
 /** Promise view of a `Generation`: its snapshot plus `await`, `refresh`, and `cancel` returning promises. */
 export type GenerationHandle<Response> = Snapshot & {
     /** Serializable JSON; pass it back to `resume` from another process. */
@@ -348,6 +350,59 @@ export declare const make: (options?: Options) => {
             }[] | undefined;
         }>;
     };
+    speech: {
+        request: typeof import("./speech.js").request;
+        generate: <const Model extends SpeechModel>(input: SpeechRequestInput<Model> | SpeechRequest, options?: RunOptions) => Promise<import("./speech.js").SpeechResponse>;
+        stream: <const Model extends SpeechModel>(input: SpeechRequestInput<Model> | SpeechRequest, options?: RunOptions) => AsyncIterable<{
+            readonly type: "audio-delta";
+            readonly chunk: Uint8Array<ArrayBufferLike>;
+        } | {
+            readonly type: "timestamps";
+            readonly items: readonly {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+            }[];
+        } | {
+            readonly type: "finish";
+            readonly audio: import("./media.js").Asset;
+            readonly providerMetadata?: {
+                readonly [x: string]: {
+                    readonly [x: string]: unknown;
+                };
+            } | undefined;
+            readonly usage?: {
+                readonly type: "tokens";
+                readonly input?: number | undefined;
+                readonly output?: number | undefined;
+                readonly total?: number | undefined;
+                readonly details?: {
+                    readonly [x: string]: unknown;
+                } | undefined;
+            } | {
+                readonly type: "seconds";
+                readonly seconds: number;
+            } | {
+                readonly type: "characters";
+                readonly characters: number;
+            } | {
+                readonly type: "credits";
+                readonly credits: number;
+            } | {
+                readonly type: "compute";
+                readonly seconds: number;
+            } | undefined;
+            readonly notices?: readonly {
+                readonly type: "other" | "moderated" | "filtered";
+                readonly message: string;
+                readonly providerMetadata?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                    };
+                } | undefined;
+            }[] | undefined;
+        }>;
+    };
     dispose: () => Promise<void>;
 };
 export type Client = ReturnType<typeof make>;
@@ -672,6 +727,59 @@ export declare const ai: {
             }[] | undefined;
         }>;
     };
+    speech: {
+        request: typeof import("./speech.js").request;
+        generate: <const Model extends SpeechModel>(input: SpeechRequestInput<Model> | SpeechRequest, options?: RunOptions) => Promise<import("./speech.js").SpeechResponse>;
+        stream: <const Model extends SpeechModel>(input: SpeechRequestInput<Model> | SpeechRequest, options?: RunOptions) => AsyncIterable<{
+            readonly type: "audio-delta";
+            readonly chunk: Uint8Array<ArrayBufferLike>;
+        } | {
+            readonly type: "timestamps";
+            readonly items: readonly {
+                readonly text: string;
+                readonly startSeconds: number;
+                readonly endSeconds: number;
+            }[];
+        } | {
+            readonly type: "finish";
+            readonly audio: import("./media.js").Asset;
+            readonly providerMetadata?: {
+                readonly [x: string]: {
+                    readonly [x: string]: unknown;
+                };
+            } | undefined;
+            readonly usage?: {
+                readonly type: "tokens";
+                readonly input?: number | undefined;
+                readonly output?: number | undefined;
+                readonly total?: number | undefined;
+                readonly details?: {
+                    readonly [x: string]: unknown;
+                } | undefined;
+            } | {
+                readonly type: "seconds";
+                readonly seconds: number;
+            } | {
+                readonly type: "characters";
+                readonly characters: number;
+            } | {
+                readonly type: "credits";
+                readonly credits: number;
+            } | {
+                readonly type: "compute";
+                readonly seconds: number;
+            } | undefined;
+            readonly notices?: readonly {
+                readonly type: "other" | "moderated" | "filtered";
+                readonly message: string;
+                readonly providerMetadata?: {
+                    readonly [x: string]: {
+                        readonly [x: string]: unknown;
+                    };
+                } | undefined;
+            }[] | undefined;
+        }>;
+    };
     dispose: () => Promise<void>;
 };
 export * as AI from "./promise.js";

package/dist/promise.js

@@ -5,6 +5,8 @@ import { LLM } from "./index.js";
 import { LLMClient } from "./route/client.js";
 import { RequestExecutor } from "./route/executor.js";
 import { LanguageModel, LLMRequest } from "./schema/index.js";
+import { Speech, SpeechModel, SpeechRequest } from "./speech.js";
+import { SpeechClient } from "./speech-client.js";
 import { Video, VideoModel, VideoRequest } from "./video.js";
 import { VideoClient } from "./video-client.js";
 const abortEffect = (signal) => signal === undefined
@@ -19,7 +21,7 @@ const abortEffect = (signal) => signal === undefined
         return Effect.sync(() => signal.removeEventListener("abort", onAbort));
     });
 export const make = (options = {}) => {
-    const runtime = ManagedRuntime.make(Layer.mergeAll(LLMClient.layer, ImageClient.layer, VideoClient.layer).pipe(Layer.provideMerge(options.layer ?? RequestExecutor.fetchLayer)));
+    const runtime = ManagedRuntime.make(Layer.mergeAll(LLMClient.layer, ImageClient.layer, VideoClient.layer, SpeechClient.layer).pipe(Layer.provideMerge(options.layer ?? RequestExecutor.fetchLayer)));
     /** Run any package Effect (for example `asset.bytes()`) inside this runtime. */
     const run = (effect, options) => runtime.runPromise(effect, { signal: options?.signal });
     const iterate = (stream, options) => Stream.toAsyncIterable(Stream.unwrap(runtime.contextEffect.pipe(Effect.map((context) => stream.pipe(Stream.interruptWhen(abortEffect(options?.signal)), Stream.provideContext(context))))));
@@ -34,6 +36,7 @@ export const make = (options = {}) => {
     const llmRequest = (input) => (input instanceof LLMRequest ? input : LLM.request(input));
     const imageRequest = (input) => input instanceof ImageRequest ? input : Image.request(input);
     const videoRequest = (input) => input instanceof VideoRequest ? input : Video.request(input);
+    const speechRequest = (input) => input instanceof SpeechRequest ? input : Speech.request(input);
     return {
         run,
         llm: {
@@ -53,6 +56,11 @@ export const make = (options = {}) => {
             resume: (model, token, options) => run(Video.resume(model, token), options).then(handle),
             stream: (input, options) => iterate(Video.stream(videoRequest(input), { poll: options?.poll }), options),
         },
+        speech: {
+            request: Speech.request,
+            generate: (input, options) => run(Speech.generate(speechRequest(input)), options),
+            stream: (input, options) => iterate(Speech.stream(speechRequest(input)), options),
+        },
         dispose: () => runtime.dispose(),
     };
 };

package/dist/protocols/bedrock-converse.js

@@ -13,6 +13,7 @@ import { Lifecycle } from "./utils/lifecycle.js";
 import { MistralToolID } from "./utils/mistral-tool-id.js";
 import { ToolSchemaProjection } from "./utils/tool-schema.js";
 import { ToolStream } from "./utils/tool-stream.js";
+import { concatBytes } from "../utils/bytes.js";
 const ADAPTER = "bedrock-converse";
 // =============================================================================
 // Request Body Schema
@@ -413,14 +414,7 @@ const mapUsage = (usage, providerMetadataKey) => {
         providerMetadata: { [providerMetadataKey]: usage },
     });
 };
-const encodeRedactedContent = (chunks) => {
-    const bytes = new Uint8Array(chunks.reduce((total, chunk) => total + chunk.length, 0));
-    chunks.reduce((offset, chunk) => {
-        bytes.set(chunk, offset);
-        return offset + chunk.length;
-    }, 0);
-    return Encoding.encodeBase64(bytes);
-};
+const encodeRedactedContent = (chunks) => Encoding.encodeBase64(concatBytes(chunks));
 const step = (state, event) => Effect.gen(function* () {
     if (event.contentBlockStart?.start?.toolUse) {
         const index = event.contentBlockStart.contentBlockIndex;

package/dist/protocols/cartesia-speech.d.ts

@@ -0,0 +1,127 @@
+import { MediaProtocol } from "../route/media-protocol.js";
+import { MediaRoute } from "../route/media.js";
+import { SpeechModel, type SpeechRequestFor } from "../speech.js";
+import { SpeechStream } from "./utils/speech-stream.js";
+export declare const DEFAULT_BASE_URL = "https://api.cartesia.ai";
+export declare const API_VERSION = "2026-08-14";
+export declare const BYTES_PATH = "/tts/bytes";
+export declare const SSE_PATH = "/tts/sse";
+export type CartesiaSpeechString<Known extends string> = Known | (string & {});
+export type CartesiaEncoding = SpeechStream.PcmEncoding;
+export type CartesiaSpeechOptions = {
+    readonly sampleRate?: 8000 | 16000 | 22050 | 24000 | 44100 | 48000;
+    readonly bitRate?: 32000 | 64000 | 96000 | 128000 | 192000;
+    readonly encoding?: CartesiaEncoding;
+    readonly generation_config?: {
+        readonly volume?: number;
+        readonly emotion?: CartesiaSpeechString<"neutral" | "calm" | "angry" | "content" | "sad" | "scared">;
+    };
+    readonly pronunciation_dict_id?: string;
+} & Record<string, unknown>;
+export type Request = SpeechRequestFor<CartesiaSpeechOptions>;
+interface State extends SpeechStream.Audio {
+    readonly done: boolean;
+}
+export declare const protocol: MediaProtocol.Streamed<Request, {
+    readonly type: "audio-delta";
+    readonly chunk: Uint8Array<ArrayBufferLike>;
+} | {
+    readonly type: "timestamps";
+    readonly items: readonly {
+        readonly text: string;
+        readonly startSeconds: number;
+        readonly endSeconds: number;
+    }[];
+} | {
+    readonly type: "finish";
+    readonly audio: import("../media.js").Asset;
+    readonly providerMetadata?: {
+        readonly [x: string]: {
+            readonly [x: string]: unknown;
+        };
+    } | undefined;
+    readonly usage?: {
+        readonly type: "tokens";
+        readonly input?: number | undefined;
+        readonly output?: number | undefined;
+        readonly total?: number | undefined;
+        readonly details?: {
+            readonly [x: string]: unknown;
+        } | undefined;
+    } | {
+        readonly type: "seconds";
+        readonly seconds: number;
+    } | {
+        readonly type: "characters";
+        readonly characters: number;
+    } | {
+        readonly type: "credits";
+        readonly credits: number;
+    } | {
+        readonly type: "compute";
+        readonly seconds: number;
+    } | undefined;
+    readonly notices?: readonly {
+        readonly type: "other" | "moderated" | "filtered";
+        readonly message: string;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+    }[] | undefined;
+}, string | Uint8Array<ArrayBufferLike>, State>;
+export declare const model: (input: MediaRoute.ModelInput) => SpeechModel<CartesiaSpeechOptions>;
+export declare const CartesiaSpeech: {
+    readonly protocol: MediaProtocol.Streamed<Request, {
+        readonly type: "audio-delta";
+        readonly chunk: Uint8Array<ArrayBufferLike>;
+    } | {
+        readonly type: "timestamps";
+        readonly items: readonly {
+            readonly text: string;
+            readonly startSeconds: number;
+            readonly endSeconds: number;
+        }[];
+    } | {
+        readonly type: "finish";
+        readonly audio: import("../media.js").Asset;
+        readonly providerMetadata?: {
+            readonly [x: string]: {
+                readonly [x: string]: unknown;
+            };
+        } | undefined;
+        readonly usage?: {
+            readonly type: "tokens";
+            readonly input?: number | undefined;
+            readonly output?: number | undefined;
+            readonly total?: number | undefined;
+            readonly details?: {
+                readonly [x: string]: unknown;
+            } | undefined;
+        } | {
+            readonly type: "seconds";
+            readonly seconds: number;
+        } | {
+            readonly type: "characters";
+            readonly characters: number;
+        } | {
+            readonly type: "credits";
+            readonly credits: number;
+        } | {
+            readonly type: "compute";
+            readonly seconds: number;
+        } | undefined;
+        readonly notices?: readonly {
+            readonly type: "other" | "moderated" | "filtered";
+            readonly message: string;
+            readonly providerMetadata?: {
+                readonly [x: string]: {
+                    readonly [x: string]: unknown;
+                };
+            } | undefined;
+        }[] | undefined;
+    }, string | Uint8Array<ArrayBufferLike>, State>;
+    readonly model: (input: MediaRoute.ModelInput) => SpeechModel<CartesiaSpeechOptions>;
+};
+export {};

package/dist/protocols/cartesia-speech.js

@@ -0,0 +1,126 @@
+import { Effect, Schema } from "effect";
+import { classifyProviderFailure } from "../provider-error.js";
+import { Framing } from "../route/framing.js";
+import { MediaProtocol } from "../route/media-protocol.js";
+import { MediaRoute } from "../route/media.js";
+import { AIError, ProviderID, mergeJsonRecords } from "../schema/index.js";
+import { SpeechModel } from "../speech.js";
+import { ProviderShared, optionalNull } from "./shared.js";
+import { SpeechStream } from "./utils/speech-stream.js";
+const ADAPTER = "cartesia-speech";
+const NAME = "Cartesia";
+const PROVIDER = ProviderID.make("cartesia");
+export const DEFAULT_BASE_URL = "https://api.cartesia.ai";
+export const API_VERSION = "2026-08-14";
+export const BYTES_PATH = "/tts/bytes";
+export const SSE_PATH = "/tts/sse";
+const DEFAULT_SAMPLE_RATE = 44100;
+const DEFAULT_BIT_RATE = 128000;
+// ---------------------------------------------------------------------------
+// 3. Streaming event schema
+// ---------------------------------------------------------------------------
+/** `phoneme_timestamps` and future record types are ignored. */
+const SseEvent = Schema.Struct({
+    type: Schema.String,
+    data: Schema.optional(Schema.Uint8ArrayFromBase64),
+    word_timestamps: Schema.optional(Schema.Struct({
+        words: Schema.Array(Schema.String),
+        start: Schema.Array(Schema.Number),
+        end: Schema.Array(Schema.Number),
+    })),
+    status_code: Schema.optional(Schema.Number),
+    title: Schema.optional(Schema.String),
+    message: Schema.optional(Schema.String),
+    error_code: optionalNull(Schema.String),
+});
+const decodeEvent = MediaProtocol.decodeFrame(ADAPTER, NAME, SseEvent);
+// ---------------------------------------------------------------------------
+// 5. Request body construction
+// ---------------------------------------------------------------------------
+/** Timestamps exist only on the SSE endpoint, so a `generate` that asks for them collects an SSE stream. */
+const usesSse = (request) => request.mode === "stream" || request.timestamps === true;
+const CONTAINERS = { pcm: "raw", wav: "wav", mp3: "mp3" };
+const outputFormat = Effect.fn("CartesiaSpeech.outputFormat")(function* (request) {
+    const sse = usesSse(request);
+    const format = request.format ?? (sse ? "pcm" : "mp3");
+    const container = CONTAINERS[format];
+    if (container === undefined)
+        return yield* SpeechStream.unsupportedFormat(PROVIDER, ADAPTER, `${NAME} supports the pcm, wav, and mp3 formats, not "${format}"`);
+    if (sse && container !== "raw")
+        return yield* SpeechStream.unsupportedFormat(PROVIDER, ADAPTER, `${NAME} streams and timestamps only raw PCM; request format "pcm" instead of "${format}"`);
+    const sampleRate = request.providerOptions?.sampleRate ?? DEFAULT_SAMPLE_RATE;
+    if (container === "mp3")
+        return { container, sample_rate: sampleRate, bit_rate: request.providerOptions?.bitRate ?? DEFAULT_BIT_RATE };
+    return { container, encoding: request.providerOptions?.encoding ?? "pcm_s16le", sample_rate: sampleRate };
+});
+const fromRequest = Effect.fn("CartesiaSpeech.fromRequest")(function* (request) {
+    const voice = SpeechStream.voiceID(request.voice);
+    if (voice === undefined)
+        return yield* ProviderShared.invalidRequest(`${NAME} requires a voice id; pass it as \`voice\``);
+    const { sampleRate: _sampleRate, bitRate: _bitRate, encoding: _encoding, ...native } = request.providerOptions ?? {};
+    return MediaProtocol.json(mergeJsonRecords({
+        model_id: request.model.id,
+        transcript: request.text,
+        voice,
+        output_format: yield* outputFormat(request),
+        language: request.language,
+        generation_config: request.speed === undefined ? undefined : { speed: request.speed },
+        add_timestamps: request.timestamps === true ? true : undefined,
+    }, native, request.http?.body) ?? {});
+});
+// ---------------------------------------------------------------------------
+// 6. Stream parsing
+// ---------------------------------------------------------------------------
+const onEvent = Effect.fn("CartesiaSpeech.onEvent")(function* (state, frame) {
+    const event = yield* decodeEvent(frame);
+    if (event.type === "chunk" && event.data !== undefined)
+        return SpeechStream.delta(state, event.data);
+    if (event.type === "timestamps" && event.word_timestamps !== undefined) {
+        const words = event.word_timestamps;
+        return [state, SpeechStream.timestamps(words.words, words.start, words.end)];
+    }
+    if (event.type === "done")
+        return [{ ...state, done: true }, []];
+    if (event.type === "error")
+        return yield* new AIError({
+            reason: classifyProviderFailure({
+                message: `${NAME} stream failed${event.title === undefined ? "" : ` (${event.title})`}: ${event.message ?? "unknown error"}`,
+                status: event.status_code,
+                rawBody: frame,
+            }),
+        });
+    return [state, []];
+});
+const finish = Effect.fn("CartesiaSpeech.finish")(function* (state, context) {
+    if (usesSse(context.request) && !state.done)
+        return yield* MediaProtocol.incomplete(ADAPTER);
+    const format = yield* outputFormat(context.request);
+    return yield* SpeechStream.finish(ADAPTER, state, format.container === "raw"
+        ? SpeechStream.pcm(format.encoding, format.sample_rate)
+        : SpeechStream.container(format.container, format.sample_rate));
+});
+// ---------------------------------------------------------------------------
+// 7. Protocol and route
+// ---------------------------------------------------------------------------
+export const protocol = MediaProtocol.stream({
+    id: ADAPTER,
+    name: NAME,
+    unsupported: ["instructions"],
+    body: { from: fromRequest },
+    frames: (bytes, context) => (usesSse(context.request) ? Framing.sse.frame(bytes) : bytes),
+    initial: () => ({ chunks: [], done: false }),
+    step: SpeechStream.step(onEvent),
+    finish,
+});
+export const model = (input) => SpeechModel.fromRoute({
+    id: ADAPTER,
+    provider: PROVIDER,
+    protocol,
+    baseURL: DEFAULT_BASE_URL,
+    headers: { "Cartesia-Version": API_VERSION },
+    path: ({ request }) => (usesSse(request) ? SSE_PATH : BYTES_PATH),
+}, input);
+export const CartesiaSpeech = {
+    protocol,
+    model,
+};