elevenlabs

What it does

Provider. elevenlabs owns everything ElevenLabs-specific. It registers three handlers with registry in onInit: ("voiceover", "elevenlabs"), ("sfx", "elevenlabs") and ("music", "elevenlabs"). It talks to the API with a thin fetch client, no SDK. Each handler has estimate and execute. The runner and the task facades reach them through the registry. You never call a handler directly.

Its own public API is one method, app.elevenlabs.info().

Setup

One env var. Exported in the shell or in .env.local.

info() and every estimate() work without the key. When the variable is unset, execute throws before any network call:

[ai] ELEVENLABS_API_KEY is not set.
  Export it or set config.apiKeyEnv to the variable that holds your key.

The key is read through ctx.env at request time. It is never stored and never logged.

Tasks it serves

voiceover

text, voice (an ElevenLabs voice id), optional language, model, format and params. format is mp3 (default), wav or ogg. params is spread into the JSON body last, so its keys win.

  - id: greeting
    task: voiceover
    provider: elevenlabs
    input:
      text: "Hello, world!"
      voice: "21m00Tcm4TlvDq8ikWAM"
      format: mp3

sfx

The output is always mp3. Every rule is checked before any HTTP call. A refused request is a terminal 400: the runner marks the item failed and never retries it.

  - id: sword-hit
    task: sfx
    input:
      prompt: "sword hit, metallic"
      model: eleven_text_to_sound_v2
      durationMs: 800

music

Paid ElevenLabs plans only. On a free plan the call fails with a 4xx. The endpoint answers when the whole track is ready, so it has its own timeout, musicTimeoutMs.

  - id: s01.score
    task: music
    provider: elevenlabs
    input: { model: music_v2_5, prompt: "tense synth pulse", lengthMs: 30000 }
  - id: s01.theme
    task: music
    provider: elevenlabs
    input:
      model: music_v2_5
      prompt: "main theme"
      lengthMs: 43000
      seed: 7
      chunks:
        - { text: "[Intro]", durationMs: 13000, styles: [synthwave, dark, slow build] }
        - { text: "[Drop]", durationMs: 30000, styles: [driving bass], avoid: [vocals] }

Models and prices

The plugin ships a price table. priceOverrides merges over it, and an override wins. The effective table is computed once at first use and cached. The bundled numbers are estimates: set your plan's real price.

Voice models, USD per character:

A voice model missing from the table estimates at $0.

Sound effects, keyed sfx:<model>#second and sfx:<model>#auto:

Music, keyed music:<model>, per started minute:

A missing sfx or music price is a terminal error, not $0. A paid job never runs at an unknown price:

[ai] No price for ElevenLabs sfx model "eleven_text_to_sound_v2".
  Add it to elevenlabs.priceOverrides.

Cost math: voiceover is text.length × price. sfx is ceil(durationMs / 1000) × #second, or #auto without a duration. music is every started minute × music:<model>. estimate and execute use the same formula, so costUsd equals the estimate.

import { createApp } from "@moku-labs/ai";

const app = createApp({
  pluginConfigs: {
    elevenlabs: {
      defaultModel: "eleven_turbo_v2_5",
      priceOverrides: {
        eleven_turbo_v2_5: 0.00012,
        "sfx:eleven_text_to_sound_v2#second": 0.0025
      }
    }
  }
});

console.log(app.elevenlabs.info().models); // includes "eleven_turbo_v2_5"

Config

pluginConfigs.elevenlabs.

API

Mounted at app.elevenlabs.

import { app } from "./app";

const { configured, models } = app.elevenlabs.info();
if (!configured) throw new Error("Export ELEVENLABS_API_KEY first.");
console.log(models); // ["eleven_multilingual_v2", "eleven_turbo_v2_5", ...]

Types ship under the Elevenlabs namespace: Elevenlabs.Config, Elevenlabs.ElevenlabsApi.

Errors

The client maps every failure to one of three classes. The runner reads them by shape (status, kind, retryAfterMs), never by class.

A content-policy detail.status in the body wins over the numeric status. An abort through opts.signal is rethrown unchanged. Messages carry status codes and error classes only, never request text or response bodies.

The classes are values under ElevenlabsErrors:

import { ElevenlabsErrors } from "@moku-labs/ai";
import { app } from "./app";

try {
  await app.voiceover.generate({ text: "Hi", voice: "21m00Tcm4TlvDq8ikWAM" });
} catch (error) {
  if (error instanceof ElevenlabsErrors.RetryableProviderError) {
    console.warn("transient", error.status ?? error.kind, error.retryAfterMs);
  } else if (error instanceof ElevenlabsErrors.FlaggedProviderError) {
    console.error("content policy, do not re-queue");
  } else {
    throw error;
  }
}

Events

Emits

None.

Listens to

None. Diagnostics go through ctx.log: elevenlabs:<task>:done on success, and elevenlabs:<task>:failed with the error class and status before a rethrow. No message text.

Depends on

• registry: the three register calls.

Related

• voiceover, sfx, music: the tasks.
• openai: the other voiceover provider.
• runner: how the error classes become retries.