# `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`.

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs -->

## 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

```ts
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

```ts
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).