@effect-uai/elevenlabs 0.5.2 → 0.7.0

package/src/ElevenLabsMusicGenerator.ts

@@ -0,0 +1,353 @@
+import { Context, Duration, Effect, Layer, Redacted, Stream } from "effect"
+import { HttpClient, HttpClientRequest } from "effect/unstable/http"
+import * as AiError from "@effect-uai/core/AiError"
+import type { AudioChunk, AudioFormat } from "@effect-uai/core/Audio"
+import type {
+  CommonGenerateMusicRequest,
+  CommonStreamGenerateMusicRequest,
+  GenerateResult,
+  MusicResult,
+  MusicSessionInput,
+  MusicStreamEvent,
+} from "@effect-uai/core/Music"
+import { singleVariant } from "@effect-uai/core/Music"
+import { MusicGenerator, type MusicGeneratorService } from "@effect-uai/core/MusicGenerator"
+import { defaultFormat, formatToOutputSlug } from "./codec.js"
+import type { ElevenLabsMusicModel } from "./models.js"
+import {
+  decodeCompositionPlan,
+  type ElevenLabsCompositionPlan,
+  warnDroppedPromptModeHints,
+  wireCompositionPlan,
+} from "./musicCodec.js"
+import { type ElevenLabsRegion, resolveHost } from "./region.js"
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+/**
+ * ElevenLabs-typed music request. Narrows `model` to
+ * `ElevenLabsMusicModel` and adds provider-specific extras:
+ *
+ * - `compositionPlan` — switch from prompt mode to plan mode. Mutually
+ *   exclusive with `prompt` on the wire.
+ * - `forceInstrumental` — skip vocals. ElevenLabs has no `instrumental`
+ *   on the cross-provider Common request (the field was removed in
+ *   v0.7 because it has wildly different semantics per provider); the
+ *   typed surface restores it.
+ * - `signWithC2pa` — opt-in C2PA Content Credentials, MP3 output only.
+ * - `respectSectionsDurations` — composition-plan mode only. False
+ *   trades section-duration accuracy for quality + latency.
+ *
+ * Setting `compositionPlan` with a non-empty `prompt`, or with
+ * `duration`, fails `InvalidRequest` at the codec layer.
+ */
+export type ElevenLabsMusicGenerateRequest = Omit<CommonGenerateMusicRequest, "model"> & {
+  readonly model?: ElevenLabsMusicModel
+  readonly compositionPlan?: ElevenLabsCompositionPlan
+  readonly forceInstrumental?: boolean
+  readonly signWithC2pa?: boolean
+  readonly respectSectionsDurations?: boolean
+}
+
+export type CreateCompositionPlanRequest = {
+  readonly prompt: string
+  readonly duration?: Duration.Duration
+  readonly sourceCompositionPlan?: ElevenLabsCompositionPlan
+  readonly model?: ElevenLabsMusicModel
+}
+
+export type ElevenLabsMusicGeneratorService = {
+  readonly generate: (
+    request: ElevenLabsMusicGenerateRequest,
+  ) => Effect.Effect<GenerateResult, AiError.AiError>
+  readonly streamGeneration: (
+    request: ElevenLabsMusicGenerateRequest,
+  ) => Stream.Stream<AudioChunk, AiError.AiError>
+  readonly streamGenerationFrom: <E, R>(
+    input: Stream.Stream<MusicSessionInput, E, R>,
+    request: CommonStreamGenerateMusicRequest,
+  ) => Stream.Stream<MusicStreamEvent, AiError.AiError | E, R>
+  /**
+   * Free endpoint (rate-limited, no credit cost): turn a prompt into a
+   * structured `MusicPrompt` plan. Feed the result back into
+   * `generate` / `streamGeneration` via `compositionPlan`.
+   */
+  readonly createCompositionPlan: (
+    request: CreateCompositionPlanRequest,
+  ) => Effect.Effect<ElevenLabsCompositionPlan, AiError.AiError>
+}
+
+export class ElevenLabsMusicGenerator extends Context.Service<
+  ElevenLabsMusicGenerator,
+  ElevenLabsMusicGeneratorService
+>()("@betalyra/effect-uai/providers/elevenlabs/ElevenLabsMusicGenerator") {}
+
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}
+
+const DEFAULT_MODEL: ElevenLabsMusicModel = "music_v1"
+
+// ---------------------------------------------------------------------------
+// HTTP errors (music namespace; reuses the same status taxonomy)
+// ---------------------------------------------------------------------------
+
+const musicTransportFailure = (cause: unknown): AiError.AiError =>
+  new AiError.Unavailable({ provider: "elevenlabs-music", raw: cause })
+
+const musicHttpStatusError = (status: number, body: string): AiError.AiError => {
+  if (status === 429) return new AiError.RateLimited({ provider: "elevenlabs-music", raw: body })
+  if (status === 408 || status === 504)
+    return new AiError.Timeout({ provider: "elevenlabs-music", raw: body })
+  if (status === 401)
+    return new AiError.AuthFailed({ provider: "elevenlabs-music", subtype: "auth", raw: body })
+  if (status === 403)
+    return new AiError.AuthFailed({
+      provider: "elevenlabs-music",
+      subtype: "permission",
+      raw: body,
+    })
+  if (status === 402)
+    return new AiError.AuthFailed({
+      provider: "elevenlabs-music",
+      subtype: "billing",
+      raw: body,
+    })
+  if (status >= 500)
+    return new AiError.Unavailable({ provider: "elevenlabs-music", status, raw: body })
+  return new AiError.InvalidRequest({ provider: "elevenlabs-music", raw: body })
+}
+
+// ---------------------------------------------------------------------------
+// Wire body
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the JSON body for `/v1/music` (sync + stream share the body).
+ *
+ * Mutual exclusion: `compositionPlan` and prompt-mode fields cannot
+ * coexist. When `compositionPlan` is set, `prompt` must be empty and
+ * `duration` must be unset (section durations live on the plan).
+ */
+const buildBody = (request: ElevenLabsMusicGenerateRequest) =>
+  Effect.gen(function* () {
+    const model = request.model ?? DEFAULT_MODEL
+    if (request.compositionPlan !== undefined) {
+      if (request.prompt.length > 0) {
+        return yield* Effect.fail(
+          new AiError.InvalidRequest({
+            provider: "elevenlabs-music",
+            param: "prompt",
+            raw: "`prompt` and `compositionPlan` are mutually exclusive. Pass one or the other (compositionPlan carries its own per-section lyrics and styles).",
+          }),
+        )
+      }
+      if (request.duration !== undefined) {
+        return yield* Effect.fail(
+          new AiError.InvalidRequest({
+            provider: "elevenlabs-music",
+            param: "duration",
+            raw: "`duration` is ignored when `compositionPlan` is set; section durations live on the plan. Remove `duration`.",
+          }),
+        )
+      }
+      return {
+        composition_plan: wireCompositionPlan(request.compositionPlan),
+        model_id: model,
+        ...(request.seed !== undefined && { seed: request.seed }),
+        ...(request.forceInstrumental !== undefined && {
+          force_instrumental: request.forceInstrumental,
+        }),
+        ...(request.respectSectionsDurations !== undefined && {
+          respect_sections_durations: request.respectSectionsDurations,
+        }),
+        ...(request.signWithC2pa !== undefined && { sign_with_c2pa: request.signWithC2pa }),
+      }
+    }
+    yield* warnDroppedPromptModeHints(request as CommonGenerateMusicRequest)
+    return {
+      prompt: request.prompt,
+      model_id: model,
+      ...(request.duration !== undefined && {
+        music_length_ms: Duration.toMillis(request.duration),
+      }),
+      ...(request.seed !== undefined && { seed: request.seed }),
+      ...(request.forceInstrumental !== undefined && {
+        force_instrumental: request.forceInstrumental,
+      }),
+      ...(request.signWithC2pa !== undefined && { sign_with_c2pa: request.signWithC2pa }),
+    }
+  })
+
+const buildMusicHttpRequest = (
+  cfg: Config,
+  request: ElevenLabsMusicGenerateRequest,
+  path: "" | "/stream",
+) =>
+  Effect.gen(function* () {
+    const format: AudioFormat = request.outputFormat ?? defaultFormat
+    const slug = yield* formatToOutputSlug(format)
+    const body = yield* buildBody(request)
+    const url = `${resolveHost(cfg)}/music${path}?output_format=${slug}`
+    const httpRequest = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(body),
+    )
+    return { httpRequest, format }
+  })
+
+// ---------------------------------------------------------------------------
+// Service implementation
+// ---------------------------------------------------------------------------
+
+const generateImpl =
+  (cfg: Config) =>
+  (
+    request: ElevenLabsMusicGenerateRequest,
+  ): Effect.Effect<GenerateResult, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const { httpRequest, format } = yield* buildMusicHttpRequest(cfg, request, "")
+      const response = yield* client
+        .execute(httpRequest)
+        .pipe(Effect.mapError(musicTransportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return yield* Effect.fail(musicHttpStatusError(response.status, text))
+      }
+      const buffer = yield* response.arrayBuffer.pipe(Effect.mapError(musicTransportFailure))
+      const bytes = new Uint8Array(buffer)
+      const songId = response.headers["song_id"] ?? response.headers["x-song-id"]
+      const result: MusicResult = {
+        audio: { format, bytes },
+        provider: "elevenlabs-music",
+        ...(typeof songId === "string" && { songId }),
+        ...(request.signWithC2pa === true && { watermark: "c2pa" as const }),
+      }
+      return singleVariant(result)
+    })
+
+const streamGenerationImpl =
+  (cfg: Config) =>
+  (
+    request: ElevenLabsMusicGenerateRequest,
+  ): Stream.Stream<AudioChunk, AiError.AiError, HttpClient.HttpClient> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient
+        const { httpRequest } = yield* buildMusicHttpRequest(cfg, request, "/stream")
+        const response = yield* client
+          .execute(httpRequest)
+          .pipe(Effect.mapError(musicTransportFailure))
+        if (response.status >= 400) {
+          const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+          return Stream.fail(musicHttpStatusError(response.status, text))
+        }
+        return response.stream.pipe(
+          Stream.mapError(musicTransportFailure),
+          Stream.map((bytes): AudioChunk => ({ bytes })),
+        )
+      }),
+    )
+
+/**
+ * ElevenLabs music has no bidirectional session at the wire level.
+ * Layer does not register `MusicInteractiveSession`, so callers using
+ * `MusicGenerator.streamGenerationFrom` get a compile-time error
+ * before this runtime fallback fires.
+ */
+const streamGenerationFromUnsupported = <E, R>(
+  _input: Stream.Stream<MusicSessionInput, E, R>,
+  _request: CommonStreamGenerateMusicRequest,
+): Stream.Stream<MusicStreamEvent, AiError.AiError | E, R> =>
+  Stream.fail(
+    new AiError.Unsupported({
+      provider: "elevenlabs-music",
+      capability: "streamGenerationFrom",
+      reason:
+        "ElevenLabs music has no bidirectional session. Use `streamGeneration` for chunked output, or `createCompositionPlan` + `generate` for structured plans.",
+    }),
+  )
+
+const createCompositionPlanImpl =
+  (cfg: Config) =>
+  (
+    request: CreateCompositionPlanRequest,
+  ): Effect.Effect<ElevenLabsCompositionPlan, AiError.AiError, HttpClient.HttpClient> =>
+    Effect.gen(function* () {
+      const client = yield* HttpClient.HttpClient
+      const body = {
+        prompt: request.prompt,
+        model_id: request.model ?? DEFAULT_MODEL,
+        ...(request.duration !== undefined && {
+          music_length_ms: Duration.toMillis(request.duration),
+        }),
+        ...(request.sourceCompositionPlan !== undefined && {
+          source_composition_plan: wireCompositionPlan(request.sourceCompositionPlan),
+        }),
+      }
+      const httpRequest = HttpClientRequest.post(`${resolveHost(cfg)}/music/plan`).pipe(
+        HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+        HttpClientRequest.bodyJsonUnsafe(body),
+      )
+      const response = yield* client
+        .execute(httpRequest)
+        .pipe(Effect.mapError(musicTransportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return yield* Effect.fail(musicHttpStatusError(response.status, text))
+      }
+      const json = yield* response.json.pipe(Effect.mapError(musicTransportFailure))
+      return decodeCompositionPlan(json)
+    })
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+export const make = (
+  cfg: Config,
+): Effect.Effect<ElevenLabsMusicGeneratorService, never, HttpClient.HttpClient> =>
+  Effect.map(HttpClient.HttpClient.asEffect(), (client) => ({
+    generate: (request) =>
+      generateImpl(cfg)(request).pipe(Effect.provideService(HttpClient.HttpClient, client)),
+    streamGeneration: (request) =>
+      streamGenerationImpl(cfg)(request).pipe(Stream.provideService(HttpClient.HttpClient, client)),
+    streamGenerationFrom: streamGenerationFromUnsupported,
+    createCompositionPlan: (request) =>
+      createCompositionPlanImpl(cfg)(request).pipe(
+        Effect.provideService(HttpClient.HttpClient, client),
+      ),
+  }))
+
+/**
+ * Layer that registers the provider-specific `ElevenLabsMusicGenerator`
+ * tag and the generic `MusicGenerator` tag.
+ *
+ * Does NOT register `MusicInteractiveSession`. ElevenLabs music has no
+ * bidirectional wire endpoint; `streamGenerationFrom` against this
+ * Layer alone fails to typecheck.
+ */
+export const layer = (
+  cfg: Config,
+): Layer.Layer<ElevenLabsMusicGenerator | MusicGenerator, never, HttpClient.HttpClient> =>
+  Layer.merge(
+    Layer.effect(ElevenLabsMusicGenerator, make(cfg)),
+    Layer.effect(
+      MusicGenerator,
+      Effect.map(
+        make(cfg),
+        (s): MusicGeneratorService => ({
+          generate: (req: CommonGenerateMusicRequest) =>
+            s.generate({ ...req, model: req.model as ElevenLabsMusicModel }),
+          streamGeneration: (req: CommonStreamGenerateMusicRequest) =>
+            s.streamGeneration({ ...req, model: req.model as ElevenLabsMusicModel }),
+          streamGenerationFrom: s.streamGenerationFrom,
+        }),
+      ),
+    ),
+  )

package/src/ElevenLabsSynthesizer.ts

@@ -5,7 +5,9 @@ import type * as AiError from "@effect-uai/core/AiError"
 import type { AudioBlob, AudioChunk } from "@effect-uai/core/Audio"
 import {
   type CommonStreamSynthesizeRequest,
+  type CommonSynthesizeDialogueRequest,
   type CommonSynthesizeRequest,
+  MultiSpeakerTts,
   SpeechSynthesizer,
   type SpeechSynthesizerService,
   TtsIncrementalText,
@@ -14,12 +16,16 @@ import {
   defaultFormat,
   formatToOutputSlug,
   httpStatusError,
+  type PronunciationDictionaryLocator,
+  rejectInlinePronunciations,
   transportFailure,
   type VoiceSettings,
+  wirePronunciationLocators,
   wireVoiceSettings,
 } from "./codec.js"
 import type { ElevenLabsTtsModel, ElevenLabsVoiceId } from "./models.js"
 import { streamSynthesis as realtimeStream } from "./realtimeTts.js"
+import { type ElevenLabsRegion, resolveHost } from "./region.js"
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -30,6 +36,11 @@ import { streamSynthesis as realtimeStream } from "./realtimeTts.js"
  * provider's prosody/timbre controls; `seed` makes generation
  * deterministic; `previousText` / `nextText` thread context across
  * sequential calls for natural prosody.
+ *
+ * `pronunciationDictionaryLocators` references pre-provisioned
+ * pronunciation dictionaries by ID. Inline `pronunciations` (IPA) on
+ * the Common request are not supported by ElevenLabs and fail
+ * `Unsupported`; use a dictionary for phonetic control.
  */
 export type ElevenLabsSynthesizeRequest = Omit<CommonSynthesizeRequest, "model" | "voiceId"> & {
   readonly model: ElevenLabsTtsModel
@@ -38,6 +49,7 @@ export type ElevenLabsSynthesizeRequest = Omit<CommonSynthesizeRequest, "model"
   readonly seed?: number
   readonly previousText?: string
   readonly nextText?: string
+  readonly pronunciationDictionaryLocators?: ReadonlyArray<PronunciationDictionaryLocator>
 }
 
 export type ElevenLabsSynthesizerService = {
@@ -46,6 +58,8 @@ export type ElevenLabsSynthesizerService = {
     r: ElevenLabsSynthesizeRequest,
   ) => Stream.Stream<AudioChunk, AiError.AiError>
   readonly streamSynthesisFrom: SpeechSynthesizerService["streamSynthesisFrom"]
+  readonly synthesizeDialogue: SpeechSynthesizerService["synthesizeDialogue"]
+  readonly streamSynthesizeDialogue: SpeechSynthesizerService["streamSynthesizeDialogue"]
 }
 
 export class ElevenLabsSynthesizer extends Context.Service<
@@ -53,7 +67,11 @@ export class ElevenLabsSynthesizer extends Context.Service<
   ElevenLabsSynthesizerService
 >()("@betalyra/effect-uai/providers/elevenlabs/ElevenLabsSynthesizer") {}
 
-export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}
 
 // ---------------------------------------------------------------------------
 // Codec — request → JSON body
@@ -66,20 +84,82 @@ const buildBody = (r: ElevenLabsSynthesizeRequest) => ({
   ...(r.seed !== undefined && { seed: r.seed }),
   ...(r.previousText !== undefined && { previous_text: r.previousText }),
   ...(r.nextText !== undefined && { next_text: r.nextText }),
+  ...wirePronunciationLocators(r.pronunciationDictionaryLocators),
   ...(r.voiceSettings !== undefined && { voice_settings: wireVoiceSettings(r.voiceSettings) }),
 })
 
 // ---------------------------------------------------------------------------
-// HTTP plumbing (sync + chunked-HTTP streaming)
+// Dialogue — POST /v1/text-to-dialogue (+ /stream variant)
 // ---------------------------------------------------------------------------
 
-const baseUrl = (cfg: Config) => cfg.baseUrl ?? "https://api.elevenlabs.io/v1"
+const DEFAULT_DIALOGUE_MODEL = "eleven_v3"
+
+const buildDialogueBody = (r: CommonSynthesizeDialogueRequest) => ({
+  inputs: r.turns.map((t) => ({
+    voice_id: t.voiceId,
+    text: t.text,
+  })),
+  model_id: r.model ?? DEFAULT_DIALOGUE_MODEL,
+  ...(r.languageCode !== undefined && { language_code: r.languageCode }),
+})
+
+const buildDialogueHttpRequest = (
+  cfg: Config,
+  r: CommonSynthesizeDialogueRequest,
+  path: "" | "/stream",
+) =>
+  Effect.gen(function* () {
+    const format = r.outputFormat ?? defaultFormat
+    const slug = yield* formatToOutputSlug(format)
+    const url = `${resolveHost(cfg)}/text-to-dialogue${path}?output_format=${slug}`
+    const httpRequest = HttpClientRequest.post(url).pipe(
+      HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
+      HttpClientRequest.bodyJsonUnsafe(buildDialogueBody(r)),
+    )
+    return { httpRequest, format }
+  })
+
+const synthesizeDialogueImpl = (cfg: Config) => (request: CommonSynthesizeDialogueRequest) =>
+  Effect.gen(function* () {
+    yield* rejectInlinePronunciations(request.pronunciations)
+    const client = yield* HttpClient.HttpClient
+    const { httpRequest, format } = yield* buildDialogueHttpRequest(cfg, request, "")
+    const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+    if (response.status >= 400) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+      return yield* Effect.fail(httpStatusError(response.status, text))
+    }
+    const bytes = yield* response.arrayBuffer.pipe(Effect.mapError(transportFailure))
+    return { format, bytes: new Uint8Array(bytes) } satisfies AudioBlob
+  })
+
+const streamSynthesizeDialogueImpl = (cfg: Config) => (request: CommonSynthesizeDialogueRequest) =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      yield* rejectInlinePronunciations(request.pronunciations)
+      const client = yield* HttpClient.HttpClient
+      const { httpRequest } = yield* buildDialogueHttpRequest(cfg, request, "/stream")
+      const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
+      if (response.status >= 400) {
+        const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""))
+        return Stream.fail(httpStatusError(response.status, text))
+      }
+      return response.stream.pipe(
+        Stream.mapError(transportFailure),
+        Stream.map((bytes): AudioChunk => ({ bytes })),
+      )
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// HTTP plumbing (sync + chunked-HTTP streaming)
+// ---------------------------------------------------------------------------
 
 const buildHttpRequest = (cfg: Config, r: ElevenLabsSynthesizeRequest, path: "" | "/stream") =>
   Effect.gen(function* () {
     const format = r.outputFormat ?? defaultFormat
     const slug = yield* formatToOutputSlug(format)
-    const url = `${baseUrl(cfg)}/text-to-speech/${r.voiceId}${path}?output_format=${slug}`
+    const url = `${resolveHost(cfg)}/text-to-speech/${r.voiceId}${path}?output_format=${slug}`
     const httpRequest = HttpClientRequest.post(url).pipe(
       HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
       HttpClientRequest.bodyJsonUnsafe(buildBody(r)),
@@ -89,6 +169,7 @@ const buildHttpRequest = (cfg: Config, r: ElevenLabsSynthesizeRequest, path: ""
 
 const synthesizeImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =>
   Effect.gen(function* () {
+    yield* rejectInlinePronunciations(request.pronunciations)
     const client = yield* HttpClient.HttpClient
     const { httpRequest, format } = yield* buildHttpRequest(cfg, request, "")
     const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
@@ -103,6 +184,7 @@ const synthesizeImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =
 const streamSynthesisImpl = (cfg: Config) => (request: ElevenLabsSynthesizeRequest) =>
   Stream.unwrap(
     Effect.gen(function* () {
+      yield* rejectInlinePronunciations(request.pronunciations)
       const client = yield* HttpClient.HttpClient
       const { httpRequest } = yield* buildHttpRequest(cfg, request, "/stream")
       const response = yield* client.execute(httpRequest).pipe(Effect.mapError(transportFailure))
@@ -134,15 +216,25 @@ export const make = (cfg: Config) =>
         realtimeStream(cfg)(textIn, request as ElevenLabsSynthesizeRequest).pipe(
           Stream.provideService(Socket.WebSocketConstructor, ctor),
         ),
+      synthesizeDialogue: (request) =>
+        synthesizeDialogueImpl(cfg)(request).pipe(
+          Effect.provideService(HttpClient.HttpClient, client),
+        ),
+      streamSynthesizeDialogue: (request) =>
+        streamSynthesizeDialogueImpl(cfg)(request).pipe(
+          Stream.provideService(HttpClient.HttpClient, client),
+        ),
     } satisfies ElevenLabsSynthesizerService
   })
 
 /**
  * Layer registers `ElevenLabsSynthesizer`, the generic
- * `SpeechSynthesizer`, **and `TtsIncrementalText`** — incremental
- * text-in is wired to the realtime `/stream-input` WebSocket. Provide
- * `Socket.layerWebSocketConstructorGlobal` and an `HttpClient` Layer at
- * the call site.
+ * `SpeechSynthesizer`, the `TtsIncrementalText` marker (incremental
+ * text-in via `/stream-input` WebSocket), **and `MultiSpeakerTts`** —
+ * multi-speaker dialogue is wired to `POST /v1/text-to-dialogue`
+ * (sync) and `/v1/text-to-dialogue/stream` (chunked). Provide
+ * `Socket.layerWebSocketConstructorGlobal` and an `HttpClient` Layer
+ * at the call site.
  */
 export const layer = (cfg: Config) =>
   Layer.mergeAll(
@@ -158,8 +250,11 @@ export const layer = (cfg: Config) =>
             s.streamSynthesis(req as ElevenLabsSynthesizeRequest),
           streamSynthesisFrom: (textIn, req: CommonStreamSynthesizeRequest) =>
             s.streamSynthesisFrom(textIn, req),
+          synthesizeDialogue: s.synthesizeDialogue,
+          streamSynthesizeDialogue: s.streamSynthesizeDialogue,
         }),
       ),
     ),
     Layer.succeed(TtsIncrementalText, undefined),
+    Layer.succeed(MultiSpeakerTts, undefined),
   )

package/src/ElevenLabsTranscriber.ts

@@ -2,6 +2,7 @@ import { Context, Effect, Layer, Redacted, Schema, Stream } from "effect"
 import { HttpClient, HttpClientRequest } from "effect/unstable/http"
 import * as Socket from "effect/unstable/socket/Socket"
 import * as AiError from "@effect-uai/core/AiError"
+import * as Capabilities from "@effect-uai/core/Capabilities"
 import type { TranscriptResult, WordTimestamp } from "@effect-uai/core/Transcript"
 import {
   type CommonTranscribeRequest,
@@ -12,6 +13,7 @@ import {
 import { audioToBlob, defaultFileName, httpStatusError, transportFailure } from "./codec.js"
 import type { ElevenLabsSttModel } from "./models.js"
 import { streamTranscription } from "./realtimeStt.js"
+import { type ElevenLabsRegion, resolveHost } from "./region.js"
 
 // ---------------------------------------------------------------------------
 // Public types
@@ -43,7 +45,11 @@ export class ElevenLabsTranscriber extends Context.Service<
   ElevenLabsTranscriberService
 >()("@betalyra/effect-uai/providers/elevenlabs/ElevenLabsTranscriber") {}
 
-export type Config = { readonly apiKey: Redacted.Redacted; readonly baseUrl?: string }
+export type Config = {
+  readonly apiKey: Redacted.Redacted
+  readonly baseUrl?: string
+  readonly region?: ElevenLabsRegion
+}
 
 // ---------------------------------------------------------------------------
 // Response schema
@@ -96,6 +102,16 @@ const buildForm = (request: ElevenLabsTranscribeRequest) =>
     if (request.numSpeakers !== undefined) form.set("num_speakers", String(request.numSpeakers))
     if (request.audioEvents !== undefined)
       form.set("tag_audio_events", request.audioEvents ? "true" : "false")
+    // Vocab biasing → Scribe `keyterms` (≤1000 terms, ≤50 chars). Each
+    // term is a repeated form field (`keyterms=a&keyterms=b`), matching
+    // the ElevenLabs SDK. Scribe has no free-form prompt field.
+    for (const term of request.biasingTerms ?? []) form.append("keyterms", term)
+    yield* Capabilities.warnDroppedWhen(request.prompt, {
+      provider: "elevenlabs",
+      capability: "prompt",
+      field: "prompt",
+      reason: "ElevenLabs Scribe has no free-form prompt field; bias via `biasingTerms`.",
+    })
     return form
   })
 
@@ -103,13 +119,11 @@ const buildForm = (request: ElevenLabsTranscribeRequest) =>
 // HTTP plumbing
 // ---------------------------------------------------------------------------
 
-const baseUrl = (cfg: Config) => cfg.baseUrl ?? "https://api.elevenlabs.io/v1"
-
 const transcribeImpl = (cfg: Config) => (request: ElevenLabsTranscribeRequest) =>
   Effect.gen(function* () {
     const client = yield* HttpClient.HttpClient
     const form = yield* buildForm(request)
-    const httpRequest = HttpClientRequest.post(`${baseUrl(cfg)}/speech-to-text`).pipe(
+    const httpRequest = HttpClientRequest.post(`${resolveHost(cfg)}/speech-to-text`).pipe(
       HttpClientRequest.setHeader("xi-api-key", Redacted.value(cfg.apiKey)),
       HttpClientRequest.bodyFormData(form),
     )

package/src/codec.ts

@@ -1,6 +1,7 @@
 import { Array as Arr, Effect, Encoding, Match, Option, Result } from "effect"
 import * as AiError from "@effect-uai/core/AiError"
 import type { AudioFormat, AudioSource } from "@effect-uai/core/Audio"
+import type { CustomPronunciation } from "@effect-uai/core/SpeechSynthesizer"
 
 // ---------------------------------------------------------------------------
 // Shared TTS voice-settings shape (sync + streaming use the same fields)
@@ -25,6 +26,52 @@ export const wireVoiceSettings = (v: VoiceSettings | undefined) =>
         ...(v.speed !== undefined && { speed: v.speed }),
       }
 
+// ---------------------------------------------------------------------------
+// Pronunciation: dictionary locators (supported) vs inline IPA (rejected)
+// ---------------------------------------------------------------------------
+
+/**
+ * Reference to a pre-provisioned ElevenLabs pronunciation dictionary.
+ * The caller provisions and versions the dictionary out-of-band
+ * (dashboard or the pronunciation-dictionary API); we only reference it.
+ */
+export type PronunciationDictionaryLocator = {
+  readonly dictionaryId: string
+  readonly versionId: string
+}
+
+export const wirePronunciationLocators = (
+  locators: ReadonlyArray<PronunciationDictionaryLocator> | undefined,
+) =>
+  locators === undefined || locators.length === 0
+    ? undefined
+    : {
+        pronunciation_dictionary_locators: locators.map((l) => ({
+          pronunciation_dictionary_id: l.dictionaryId,
+          version_id: l.versionId,
+        })),
+      }
+
+/**
+ * ElevenLabs has no stateless inline IPA path (legacy `<phoneme>` SSML
+ * is dropped; modern phonetics live in pre-uploaded dictionaries).
+ * Inline `pronunciations` are load-bearing (bucket 1), so reject rather
+ * than silently mispronounce. Use `pronunciationDictionaryLocators`.
+ */
+export const rejectInlinePronunciations = (
+  pronunciations: ReadonlyArray<CustomPronunciation> | undefined,
+): Effect.Effect<void, AiError.AiError> =>
+  pronunciations !== undefined && pronunciations.length > 0
+    ? Effect.fail(
+        new AiError.Unsupported({
+          provider: "elevenlabs",
+          capability: "pronunciations",
+          reason:
+            "ElevenLabs has no stateless inline IPA path. Provision a pronunciation dictionary and pass `pronunciationDictionaryLocators`, or use a provider with inline phonemes (Inworld, Google).",
+        }),
+      )
+    : Effect.void
+
 // ---------------------------------------------------------------------------
 // AudioFormat → ElevenLabs `output_format` query value
 // ---------------------------------------------------------------------------