From dee193502fb1b85b1dc911a034c61f9913372dd8 Mon Sep 17 00:00:00 2001 From: jelveh Date: Sun, 3 May 2026 22:12:49 -0700 Subject: [PATCH] Add `txt2speech.listEngines` and `listVoices` docs --- src/docs/src/AI.md | 4 + src/docs/src/AI/txt2speech.listEngines.md | 90 ++++++++++++++++ src/docs/src/AI/txt2speech.listVoices.md | 101 ++++++++++++++++++ src/docs/src/examples.js | 12 +++ .../examples/ai-txt2speech-list-engines.html | 14 +++ .../examples/ai-txt2speech-list-voices.html | 14 +++ src/docs/src/sidebar.js | 16 +++ 7 files changed, 251 insertions(+) create mode 100644 src/docs/src/AI/txt2speech.listEngines.md create mode 100644 src/docs/src/AI/txt2speech.listVoices.md create mode 100644 src/docs/src/playground/examples/ai-txt2speech-list-engines.html create mode 100644 src/docs/src/playground/examples/ai-txt2speech-list-voices.html diff --git a/src/docs/src/AI.md b/src/docs/src/AI.md index e89b53050..a82cedb9a 100644 --- a/src/docs/src/AI.md +++ b/src/docs/src/AI.md @@ -196,6 +196,8 @@ These AI features are supported out of the box when using Puter.js: - **[`puter.ai.txt2img()`](/AI/txt2img/)** - Generate images from text descriptions - **[`puter.ai.img2txt()`](/AI/img2txt/)** - Extract text from images (OCR) - **[`puter.ai.txt2speech()`](/AI/txt2speech/)** - Convert text to speech +- **[`puter.ai.txt2speech.listEngines()`](/AI/txt2speech.listEngines/)** - List available TTS engines/models +- **[`puter.ai.txt2speech.listVoices()`](/AI/txt2speech.listVoices/)** - List available TTS voices - **[`puter.ai.speech2speech()`](/AI/speech2speech/)** - Convert speech in one voice to another voice - **[`puter.ai.txt2vid()`](/AI/txt2vid/)** - Generate short videos with OpenAI Sora models - **[`puter.ai.speech2txt()`](/AI/speech2txt/)** - Transcribe or translate audio recordings into text @@ -227,6 +229,8 @@ You can see various Puter.js AI features in action from the following examples: - [Text to Speech with engines](/playground/ai-txt2speech-engines/) - [Text to Speech with OpenAI voices](/playground/ai-txt2speech-openai/) - [Text to Speech with Gemini voices](/playground/ai-txt2speech-gemini/) + - [List TTS Engines](/playground/ai-txt2speech-list-engines/) + - [List TTS Voices](/playground/ai-txt2speech-list-voices/) - [Transcribe audio with `speech2txt`](/AI/speech2txt/) - Text to Video - [Generate a sample Sora clip](/AI/txt2vid/) diff --git a/src/docs/src/AI/txt2speech.listEngines.md b/src/docs/src/AI/txt2speech.listEngines.md new file mode 100644 index 000000000..74b521f8e --- /dev/null +++ b/src/docs/src/AI/txt2speech.listEngines.md @@ -0,0 +1,90 @@ +--- +title: puter.ai.txt2speech.listEngines() +description: List available TTS engines/models with pricing information. +platforms: [websites, apps, nodejs, workers] +--- + +Returns the TTS engines (models) available from a given provider, including pricing metadata where available. + +## Syntax + +```js +puter.ai.txt2speech.listEngines() +puter.ai.txt2speech.listEngines(provider) +puter.ai.txt2speech.listEngines(options) +``` + +## Parameters + +#### `provider` (String) (optional) + +A provider name to query. When passed as a string, this is shorthand for `{ provider }`. Defaults to `'aws-polly'`. + +Accepted values: `'aws-polly'`, `'openai'`, `'elevenlabs'`, `'gemini'`, `'xai'` + +Common aliases are also accepted (e.g. `'eleven'`, `'google'`, `'grok'`). + +#### `options` (Object) (optional) + +| Option | Type | Description | +|--------|------|-------------| +| `provider` | `String` | TTS provider to query. Defaults to `'aws-polly'` | + +## Return value + +A `Promise` that resolves to an array of engine objects. Each object contains: + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `String` | Engine/model identifier | +| `name` | `String` | Human-readable engine name | +| `provider` | `String` | Provider this engine belongs to | +| `pricing_per_million_chars` | `Number` | Cost per million characters (may be absent) | + +Example response: + +```json +[ + { + "id": "gpt-4o-mini-tts", + "name": "GPT-4o Mini TTS", + "provider": "openai", + "pricing_per_million_chars": 12 + }, + { + "id": "tts-1", + "name": "TTS-1", + "provider": "openai" + } +] +``` + +## Examples + +List engines for a specific provider + +```html;ai-txt2speech-list-engines + + + + + + +``` + +List engines using options object + +```js +const engines = await puter.ai.txt2speech.listEngines({ provider: 'elevenlabs' }); +for (const engine of engines) { + console.log(engine.id, engine.name); +} +``` diff --git a/src/docs/src/AI/txt2speech.listVoices.md b/src/docs/src/AI/txt2speech.listVoices.md new file mode 100644 index 000000000..78851f3e3 --- /dev/null +++ b/src/docs/src/AI/txt2speech.listVoices.md @@ -0,0 +1,101 @@ +--- +title: puter.ai.txt2speech.listVoices() +description: List available TTS voices, optionally filtered by provider. +platforms: [websites, apps, nodejs, workers] +--- + +Returns the voices available from a TTS provider. Each voice entry includes metadata such as language, category, and supported models. + +## Syntax + +```js +puter.ai.txt2speech.listVoices() +puter.ai.txt2speech.listVoices(options) +``` + +## Parameters + +#### `options` (Object) (optional) + +| Option | Type | Description | +|--------|------|-------------| +| `provider` | `String` | TTS provider to query. Defaults to `'aws-polly'`. Accepted: `'aws-polly'`, `'openai'`, `'elevenlabs'`, `'gemini'`, `'xai'` | +| `engine` | `String` | Engine/model filter (provider-specific, ignored by some providers) | + +When `options` is a plain string it is treated as an `engine` filter for the default (AWS Polly) provider. + +## Return value + +A `Promise` that resolves to an array of voice objects. Each object contains: + +| Field | Type | Description | +|-------|------|-------------| +| `id` | `String` | Voice identifier to pass to `txt2speech()` | +| `name` | `String` | Human-readable voice name | +| `provider` | `String` | Provider this voice belongs to | +| `language` | `Object` | `{ name, code }` language info (may be absent) | +| `description` | `String` | Short description of the voice (may be absent) | +| `category` | `String` | Voice category, e.g. `'premade'` (may be absent) | +| `labels` | `Object` | Provider-specific labels (may be absent) | +| `supported_models` | `Array` | Model IDs this voice works with (may be absent) | +| `supported_engines` | `Array` | Engine types this voice supports (may be absent) | + +Example response: + +```json +[ + { + "id": "alloy", + "name": "Alloy", + "provider": "openai", + "description": "A balanced, neutral voice" + }, + { + "id": "Joanna", + "name": "Joanna", + "provider": "aws-polly", + "language": { "name": "English (US)", "code": "en-US" }, + "supported_engines": ["standard", "neural"] + } +] +``` + +## Examples + +List voices for a provider + +```html;ai-txt2speech-list-voices + + + + + + +``` + +List all default (AWS Polly) voices + +```js +const voices = await puter.ai.txt2speech.listVoices(); +for (const voice of voices) { + const lang = voice.language ? ` (${voice.language.code})` : ''; + console.log(`${voice.id} - ${voice.name}${lang}`); +} +``` + +List Gemini voices + +```js +const voices = await puter.ai.txt2speech.listVoices({ provider: 'gemini' }); +for (const voice of voices) { + console.log(voice.id, voice.name); +} +``` diff --git a/src/docs/src/examples.js b/src/docs/src/examples.js index 7a66bad8a..7f434bb69 100644 --- a/src/docs/src/examples.js +++ b/src/docs/src/examples.js @@ -205,6 +205,18 @@ const examples = [ slug: 'ai-txt2speech-xai', source: '/playground/examples/ai-txt2speech-xai.html', }, + { + title: 'List TTS Engines', + description: 'Query available TTS engines/models from each provider using puter.ai.txt2speech.listEngines().', + slug: 'ai-txt2speech-list-engines', + source: '/playground/examples/ai-txt2speech-list-engines.html', + }, + { + title: 'List TTS Voices', + description: 'Browse available TTS voices from each provider using puter.ai.txt2speech.listVoices().', + slug: 'ai-txt2speech-list-voices', + source: '/playground/examples/ai-txt2speech-list-voices.html', + }, { title: 'Voice Changer', description: 'Swap a sample clip into a new voice using Puter.js AI speech-to-speech helpers.', diff --git a/src/docs/src/playground/examples/ai-txt2speech-list-engines.html b/src/docs/src/playground/examples/ai-txt2speech-list-engines.html new file mode 100644 index 000000000..4b5717ed3 --- /dev/null +++ b/src/docs/src/playground/examples/ai-txt2speech-list-engines.html @@ -0,0 +1,14 @@ + + + + + + \ No newline at end of file diff --git a/src/docs/src/playground/examples/ai-txt2speech-list-voices.html b/src/docs/src/playground/examples/ai-txt2speech-list-voices.html new file mode 100644 index 000000000..3a305a9dc --- /dev/null +++ b/src/docs/src/playground/examples/ai-txt2speech-list-voices.html @@ -0,0 +1,14 @@ + + + + + + \ No newline at end of file diff --git a/src/docs/src/sidebar.js b/src/docs/src/sidebar.js index 0d6379807..c40e132f8 100755 --- a/src/docs/src/sidebar.js +++ b/src/docs/src/sidebar.js @@ -82,6 +82,22 @@ let sidebar = [ source: '/AI/txt2speech.md', path: '/AI/txt2speech', }, + { + title: 'txt2speech.listEngines()', + page_title: 'puter.ai.txt2speech.listEngines()', + title_tag: 'puter.ai.txt2speech.listEngines()', + icon: '/assets/img/function.svg', + source: '/AI/txt2speech.listEngines.md', + path: '/AI/txt2speech.listEngines', + }, + { + title: 'txt2speech.listVoices()', + page_title: 'puter.ai.txt2speech.listVoices()', + title_tag: 'puter.ai.txt2speech.listVoices()', + icon: '/assets/img/function.svg', + source: '/AI/txt2speech.listVoices.md', + path: '/AI/txt2speech.listVoices', + }, { title: 'txt2vid()', page_title: 'puter.ai.txt2vid()',