`models`

ElevenLabs model catalog. Lists every model the API key has access to, along with capability flags (TTS / voice conversion / fine-tuning) and the language matrix. Calls GET /v1/models.

(no submodules)

Purpose

Most ElevenLabs adapters take an optional modelId parameter — but which model is appropriate depends on the operation, the language, the account tier, and whether the model serves Pro voices or requires Alpha access. This catalog gives application code a typed view of the account's available models so it can pick the right one at runtime instead of hard-coding strings, and degrade gracefully if a previously chosen model is no longer accessible.

Features

One method, list(), returning readonly ElevenLabsModel[].
Each ElevenLabsModel carries the model id, display name, capability flags (canDoTextToSpeech, canDoVoiceConversion, canBeFinetuned), language matrix, and account-tier limits (maxCharactersFree, maxCharactersSubscribed).
Optional metadata (description, requiresAlphaAccess, servesProVoices, tokenCostFactor) is included only when present in the upstream response.
Boolean capability flags default to false when missing, and the language list defaults to [].
Errors are remapped onto the @suaveplan/voice domain: ProviderNotConfiguredError, ProviderRateLimitedError, and a generic VoiceError for everything else.

Usage: Basic Example

import { createElevenLabsAdapters } from "@suaveplan/third-party-elevenlabs";

const { models } = createElevenLabsAdapters({ apiKey: KEY });
const all = await models.list();
for (const m of all) console.log(m.modelId, m.name);

Usage: Advanced Example

import { createElevenLabsAdapters } from "@suaveplan/third-party-elevenlabs";

const { models } = createElevenLabsAdapters({ apiKey: KEY });

const all = await models.list();
const ttsModelsForEnglish = all.filter(
    (m) =>
        m.canDoTextToSpeech &&
        m.languages.some((l) => l.languageId === "en") &&
        !m.requiresAlphaAccess
);
const cheapest = ttsModelsForEnglish.reduce((best, m) =>
    (m.tokenCostFactor ?? 1) < (best.tokenCostFactor ?? 1) ? m : best
);
console.log("picked:", cheapest.modelId);

API Reference

interface ElevenLabsLanguage { languageId: string; name: string }
interface ElevenLabsModel { modelId, name, canDoTextToSpeech, canDoVoiceConversion, canBeFinetuned, languages, description?, maxCharactersFree?, maxCharactersSubscribed?, requiresAlphaAccess?, servesProVoices?, tokenCostFactor? }
class ElevenLabsModelCatalog
- providerName: "elevenlabs"
- list(): Promise<readonly ElevenLabsModel[]>

Throws: ProviderNotConfiguredError, ProviderRateLimitedError, and generic VoiceError-shaped failures.

Implementation Notes

The endpoint returns an array, not a paged envelope. There is no pageToken to follow.
Language entries with missing language_id or name are still emitted, but with empty strings — caller code should guard against this rather than crash.
The catalog is not cached. Wrap it in an async-cache if you call it frequently — model lists change rarely (days / weeks).
tokenCostFactor is ElevenLabs's relative pricing multiplier vs. the base model. A value of 1 means 1× character billing; 0.5 means half-cost (cheaper, often lower fidelity).

3.4 KiB Raw Blame History Unescape Escape

models