Text-to-speech output
Create spoken audio from application-generated text.
AI Tools · Function
experimental_generateSpeech
Generates speech audio from text with a selected speech model. Configure voice, format, language, provider-specific options, retries, and cancellation as needed.
How it works
Call experimental_generateSpeech with a speech model and input text. The returned audio object contains the generated sound, while optional settings can control voice, format, instructions, speed, language, provider-specific options, retries, and cancellation.
Syntax
experimental_generateSpeech({ model, text, voice?, outputFormat?, instructions?, speed?, language?, providerOptions?, maxRetries?, abortSignal? })Parameters
| Name | Type | Description |
|---|---|---|
model | SpeechModelV2 | The speech model to use. |
text | string | The text to generate the speech from. |
voice | string (optional) | The voice to use for the speech. |
outputFormat | string (optional) | The output format to use for the speech, such as mp3 or wav. |
instructions | string (optional) | Instructions for speech generation. |
speed | number (optional) | The speed of speech generation. |
language | string (optional) | ISO 639-1 language code or auto for automatic detection; provider support varies. |
providerOptions | Record<string, Record<string, JSONValue>> (optional) | Additional provider-specific options. |
maxRetries | number (optional) | Maximum number of retries; default is 2. |
abortSignal | AbortSignal (optional) | Signal used to cancel the call. |
Returns
An object containing audio of type GeneratedAudioFile.
Key points
- Converts supplied text into audio using the selected speech model.
- Pass a speech model created by a provider's speech-model factory.
- Provide the source text as a string.
- Optionally select a voice with the voice parameter.
- Use providerOptions for settings exposed only by the chosen provider.
- Supply an AbortSignal when the request must be cancellable.
Common mistakes
- The function is experimental, so its API may change.
- Choose an output format supported by the selected speech provider.
- Language handling is provider-dependent; verify support before relying on a language setting.
Example: Generate speech audio
import { experimental_generateSpeech as generateSpeech } from 'ai';
import { openai } from '@ai-sdk/openai';
const { audio } = await generateSpeech({
model: openai.speech('tts-1'),
text: 'Hello from the AI SDK!',
});
await audio.write('./speech.mp3');Generates speech audio from text with an OpenAI speech model and writes the resulting audio to a file.
When to use it
Audio narration
Add narration or voice playback to an application.
Customized speech generation
Select provider-specific voices and settings.
Related
generateSpeechSpeechModelV2GeneratedAudioFileproviderOptionsAbortSignal