# Vercel AI SDK

The [Vercel AI SDK](https://ai-sdk.dev/) provides a unified interface for integrating AI capabilities—such as text-to-speech—into web applications built with frameworks like Next.js and SvelteKit. It abstracts away provider-specific details, making it simple to work with AI models across frameworks like Next.js and SvelteKit.

This guide walks you through how to use the AI SDK to integrate Hume’s expressive TTS into your web application.

Prefer code over docs? See our [Next.js example](https://github.com/HumeAI/hume-api-examples/tree/main/tts/tts-next-js-vercel-ai-sdk) using Hume TTS with the Vercel AI SDK.

## Installation

To get started, install the required packages:

1. [ai](https://www.npmjs.com/package/ai): the core AI SDK package.
2. [@ai-sdk/hume](https://www.npmjs.com/package/@ai-sdk/hume): the Hume speech provider package.

```bash
bun add ai @ai-sdk/hume
```

## Authentication

The [HumeProvider](https://ai-sdk.dev/providers/ai-sdk-providers/hume#hume-provider) integrates Hume’s TTS API and requires a valid API key to authenticate requests. Follow these steps to obtain your credentials and configure your environment.

### Get your Hume API key

Sign in to the [Hume Platform](https://app.hume.ai/) and follow the [getting your API key guide](https://dev.hume.ai/docs/introduction/api-key) to get your API key.

### Configure environment variables

Define your Hume API key in an environment file. Most frameworks support multiple `.env` file naming conventions depending on the environment (e.g., `.env`, `.env.local`, `.env.development`, etc.). Use the one that best fits your setup.

```env
HUME_API_KEY=your-api-key-here
```

### Supply API key to HumeProvider

Pass your API key using the `apiKey` field when creating the `HumeProvider`. This ensures all requests made by the SDK to the Hume TTS API are properly authenticated.

```typescript
import { createHume } from '@ai-sdk/hume';

export const hume = createHume({
  apiKey: process.env.HUME_API_KEY ?? '',
});
```

## Usage

The AI SDK provides a unified [generateSpeech](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-speech#generatespeech) function for converting text to speech across providers. Hume integrates into this interface via the [HumeProvider](https://ai-sdk.dev/providers/ai-sdk-providers/hume#hume-provider), which exposes Hume’s expressive TTS model through the `speech()` factory method.

### Basic implementation

To generate speech, call `generateSpeech()` with at least two arguments:

- `model`: Use `hume.speech()` to specify Hume as the provider.
- `text`: The input string to be synthesized into speech.

```typescript
import { experimental_generateSpeech as generateSpeech } from 'ai';
import { hume } from '@ai-sdk/hume';

const result = await generateSpeech({
  model: hume.speech(),
  text: 'Hello, world!',
});
```

### Specify a voice

Use the `voice` argument to specify a voice from Hume’s [Voice Library](https://app.hume.ai/voices) or one of your [Custom Voices](https://app.hume.ai/voices?category=my-voices&page=0).

```typescript
import { experimental_generateSpeech as generateSpeech } from 'ai';
import { hume } from '@ai-sdk/hume';

const result = await generateSpeech({
  model: hume.speech(),
  text: 'Hello, world!',
  voice: '9e068547-5ba4-4c8e-8e03-69282a008f04', // Male English Actor
});
```

### Add instructions

Guide tone and delivery by passing natural language instructions to the `instructions` argument. See our [Acting instructions guide](https://dev.hume.ai/docs/text-to-speech-tts/acting-instructions) for examples and best practices.

```typescript
import { experimental_generateSpeech as generateSpeech } from 'ai';
import { hume } from '@ai-sdk/hume';

const result = await generateSpeech({
  model: hume.speech(),
  text: 'Hello, world!',
  voice: '9e068547-5ba4-4c8e-8e03-69282a008f04',
  instructions: 'The voice has a happy and enthusiastic tone.',
});
```

### Provide context

Hume’s speech-language model can reuse previously generated speech tokens to preserve emotion, cadence, and linguistic continuity. Provide context via `providerOptions` in one of two ways:

1. **Generation ID**: The ID corresponding to a previous generation.
2. **Context utterances**: One or more full TTS-input objects that the model synthesizes into speech tokens and then uses as context.

For more details on how context works, see our [Continuation guide](https://dev.hume.ai/docs/text-to-speech-tts/continuation).

```typescript
import { experimental_generateSpeech as generateSpeech } from 'ai';
import { hume } from '@ai-sdk/hume';

const providerOptions = {
  hume: {
    context: {
      generation_id: "795c949a-1510-4a80-9646-7d0863b023ab"
    }
  }
}

const result = await generateSpeech({
  model: hume.speech(),
  text: 'Hello, world!',
  voice: '9e068547-5ba4-4c8e-8e03-69282a008f04',
  instructions: 'The voice has a happy and enthusiastic tone.',
  providerOptions,
});
```

### Process audio

The response from `generateSpeech` is a [SpeechResult](https://github.com/vercel/ai/blob/main/packages/ai/core/generate-speech/generate-speech-result.ts) containing a [GeneratedAudioFile](https://github.com/vercel/ai/blob/main/packages/ai/core/generate-speech/generated-audio-file.ts) with the following properties:

- `base64`: The file as a base64-encoded string.
- `uint8Array`: The file as a [Uint8Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array).
- `mimeType`: The audio file’s [MIME type](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types) (e.g., "audio/mpeg").
- `format`: File format (e.g., "mp3", "wav")

The code snippet below converts the returned audio into a Blob URL you can feed directly to an audio player for playback.

```typescript
import { experimental_generateSpeech as generateSpeech } from 'ai';
import { hume } from '@ai-sdk/hume';

const result = await generateSpeech({
  model: hume.speech(),
  text: 'Hello, world!',
  voice: '9e068547-5ba4-4c8e-8e03-69282a008f04',
  instructions: 'The voice has a happy and enthusiastic tone.',
});

const { uint8Array, mimeType } = result.audio;
const blob = new Blob([uint8Array], { type: mimeType });
const url = URL.createObjectURL(blob);

const audio = new Audio(url);
audio.play();
```

## Constraints

- **Voice specification**: Pass the voice’s **ID** rather than its display `name`—the provider looks up voices by ID.

- **Implicit default voice**: If you omit `voice`, the SDK defaults to a voice from Hume’s [Voice Library](https://app.hume.ai/voices)— **Colton Rivers** (`d8ab67c6-953d-4bd8-9370-8fa53a0f1453`).

- **Audio formats**: Output can be **WAV**, **MP3**, or **PCM**. Defaults to **MP3** if not specified.

- **Fixed sample rate**: The Hume API outputs audio at a fixed sample rate of **48kHz**. Ensure compatibility with your audio processing pipeline.

- **One utterance per request**: The AI SDK sends a single [utterance](https://dev.hume.ai/docs/text-to-speech-tts/overview#glossary) per call. Split multi-utterance text inputs into separate requests.

- **Config surface**: Through the SDK you can adjust `text`, `voice`, `instructions`, `speed`, and `outputFormat`. Additional Hume-specific TTS options aren’t exposed yet.

- **Audio-only response**: The SDK calls the [/v0/tts/file](https://api.hume.ai/v0/tts/file) endpoint, which returns just the audio payload—metadata such as [generation_id](https://dev.hume.ai/reference/text-to-speech-tts/synthesize-json#response.body.generations.generation_id) isn’t included in the response.

- **Streaming not yet integrated**: Hume offers [real-time streaming TTS](https://dev.hume.ai/docs/text-to-speech-tts/overview#streaming-requests), but the AI SDK hasn’t wired up those endpoints yet, so audio is returned only after synthesis completes.