Cloud TTS

Generate speech using ListenHub OpenAPI. Audio is streamed as MP3 from the cloud.

Prerequisites

• A ListenHub API key. Pass it via --api-key or set the COLI_LISTENHUB_API_KEY environment variable.
• Optionally, a custom base URL via --base-url or the COLI_TTS_BASE_URL environment variable.

CLI

# List available speakers
coli cloud-tts --list-speakers

# List speakers filtered by language, in JSON
coli cloud-tts --list-speakers --language en --json

# Generate speech with default voice for a language
coli cloud-tts --language en "Hello world"

# Generate speech with a specific speaker
coli cloud-tts --voice cozy-man-english "Hello world"

# Save to file
coli cloud-tts --voice cozy-man-english -o output.mp3 "Hello world"

# Specify model
coli cloud-tts --voice cozy-man-english --model flowtts "Hello world"

Options

--api-key <key>       ListenHub API key (or set COLI_LISTENHUB_API_KEY)
--voice <id>          Speaker ID to use
--language <lang>     Speaker language (en, zh, ja). Uses default voice if --voice is omitted
--model <name>        Model to use (default: flowtts)
--base-url <url>      Base URL for TTS API (or set COLI_TTS_BASE_URL)
-o, --output <file>   Save audio to file
--list-speakers       List available speakers
-j, --json            Output in JSON format (use with --list-speakers)

API

listSpeakers(options)

List available speakers from ListenHub.

import {listSpeakers} from '@marswave/coli';

const speakers = await listSpeakers({
	apiKey: 'lh_sk_...',
	language: 'en',
});

for (const speaker of speakers) {
	console.log(`${speaker.name} (${speaker.speakerId})`);
}

Options

Property	Type	Description
apiKey	string	ListenHub API key
language	'en' | 'zh' | 'ja'	Filter speakers by language. Omit to list all.
baseUrl	string	Custom base URL for TTS API (optional)

runCloudTts(text, options)

Generate speech from text. When output is provided, saves MP3 to file. Otherwise plays the audio directly.

import {runCloudTts} from '@marswave/coli';

// Save to file
await runCloudTts('Hello world', {
	apiKey: 'lh_sk_...',
	voice: 'cozy-man-english',
	output: 'output.mp3',
});

Options

Property	Type	Description
apiKey	string	ListenHub API key
voice	string	Speaker ID (from listSpeakers)
model	string	Model to use (optional, defaults to flowtts)
output	string	Save to file instead of playing directly
baseUrl	string	Custom base URL for TTS API (optional)