ModelsLab

ModelsLab provides text-to-speech (TTS) only. The Mastra integration submits an asynchronous synthesis job, waits for the audio URL, downloads the completed audio, and returns it as a Node.js readable stream.

Installation

npm

npm install @mastra/voice-modelslab@latest

pnpm

pnpm add @mastra/voice-modelslab@latest

Yarn

yarn add @mastra/voice-modelslab@latest

Bun

bun add @mastra/voice-modelslab@latest

API key

Set MODELSLAB_API_KEY or pass the key through speechModel.apiKey. The constructor throws MODELSLAB_API_KEY is not set when neither value is available.

Usage example

import { ModelsLabVoice } from '@mastra/voice-modelslab'

const voice = new ModelsLabVoice({
  speechModel: {
    apiKey: process.env.MODELSLAB_API_KEY,
  },
  speaker: '5',
})

const audioStream = await voice.speak('Hello, world!', {
  speaker: 'nova',
  language: 'english',
  speed: 1,
})

const speakers = await voice.getSpeakers()

Constructor parameters

speechModel?:

ModelsLabVoiceConfig

Configuration for text-to-speech.

ModelsLabVoiceConfig

name?:

'default'

ModelsLab speech model name.

apiKey?:

string

ModelsLab API key. Falls back to the MODELSLAB_API_KEY environment variable.

speaker?:

ModelsLabVoiceId | string

= '1'

Default voice ID or OpenAI-style speaker alias.

Voices

ModelsLab exposes six built-in English voices:

ID	Name	Gender	Language
1	Neutral	neutral	en
2	Male	male	en
3	Warm	male	en
4	Deep Male	male	en
5	Female	female	en
6	Clear Female	female	en

OpenAI-style aliases map to these voices:

Alias	Voice ID
alloy	1
echo	2
fable	3
onyx	4
nova	5
shimmer	6

Methods

speak()

Converts text to speech. If ModelsLab returns a processing ID, the integration polls every five seconds for up to five minutes. It downloads the completed audio before returning the readable stream, so this method doesn't provide progressive audio streaming.

input:

string | NodeJS.ReadableStream

Text to convert to speech. A readable stream is fully buffered and converted to text first.

options?:

object

Options for the synthesis request.

object

speaker?:

ModelsLabVoiceId | string

Voice ID or OpenAI-style alias. Non-numeric values that are not aliases fall back to voice ID 1.

language?:

string

Language sent to the ModelsLab API.

speed?:

number

Speech speed sent to the ModelsLab API.

Returns: Promise<NodeJS.ReadableStream>

getSpeakers()

Returns the built-in ModelsLab voice metadata.

voiceId:

string

Voice identifier from 1 through 6.

name:

string

Display name of the voice.

language:

string

Language code for the voice.

gender:

string

Gender metadata for the voice.

Returns: Promise<Array<{ voiceId: string; name: string; language: string; gender: string }>>

listen()

ModelsLab doesn't support speech-to-text. Calling this method throws an error that points to @mastra/voice-deepgram as a listening provider.

Important notes

• ModelsLab text-to-speech requests send the API key in the request body.
• Processing jobs are polled every five seconds and time out after 300 seconds.
• The completed audio is fully downloaded before the stream is returned. The stream isn't progressive.
• The integration doesn't force an output format. It downloads the audio from the URL returned by ModelsLab.
• speed doesn't have runtime range validation in this package.
• Non-numeric speaker values that don't match an alias fall back to voice ID 1.
• Speech-to-text isn't supported.