Vercel AI SDK | Hume API

Vercel AI SDK

The Vercel AI SDK 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 using Hume TTS with the Vercel AI SDK.

Installation

To get started, install the required packages:

  1. ai: the core AI SDK package.
  2. @ai-sdk/hume: the Hume speech provider package.
bun add ai @ai-sdk/hume

Authentication

The HumeProvider 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 and follow the getting your API key guide 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.

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.

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

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

Usage

The AI SDK provides a unified generateSpeech function for converting text to speech across providers. Hume integrates into this interface via the HumeProvider, which exposes Hume’s expressive TTS model through the speech() factory method.

Basic implementation

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

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 or one of your Custom Voices.

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 for examples and best practices.

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.

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 containing a GeneratedAudioFile with the following properties:

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

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