Vapi

Vapi is a developer platform for building AI voice assistants that run over phone and web. It handles the full voice stack, including telephony, real-time audio streaming, and speech synthesis. You can configure assistant behavior directly in the Vapi dashboard.

Vapi includes built-in support for Hume’s text-to-speech (TTS) service. When creating an assistant, you can select a Hume voice from the Voice Library or provide a custom voice ID. Vapi manages all backend communication with Hume and handles audio formatting automatically.

Requirements

To use Hume voices in Vapi, you need:

1. A Vapi account with access to the Assistant Dashboard
2. A Hume voice, which can be either:
   • A Voice Library voice, selectable by name in the Vapi dashboard. No Hume account is required.
   • A custom voice you created on the Hume platform, which requires an API key associated with your Hume account and voice ID.

Configuration

Selecting a Hume voice

In the Voice section of the Vapi dashboard, set the voice provider to Hume.

You can then choose a voice in one of two ways:

1. Voice Library voices: Select a voice by name from the list of available options. A Hume account is not required to use these voices.
2. Custom voices: Enter the voice ID for a custom voice you’ve created in your Hume account using the Hume platform.

Vapi uses this selection to request audio from Hume during each assistant response. No additional configuration is required beyond selecting the voice.

Using a custom Hume voice via the Vapi API

Vapi currently defaults Hume voices in the UI to Voice Library options. If you need a custom Hume voice ID, follow the steps below to update or create an assistant via the Vapi API.

Step 1: Add your Hume API key in Vapi

1. Go to dashboard.vapi.ai and click More under Build.
2. Click Integrations, select Hume, enter your Hume API key, and save.
3. You can find your Hume API keys at platform.hume.ai under API keys. If you have an Organization API key, use that instead of a Personal key.

Step 2A: Update an existing assistant

Replace the REPLACE_ME values before running these commands in your terminal.

$
export VAPI_TOKEN="REPLACE_ME_VAPI_API_KEY"
$
export VAPI_ASSISTANT_ID="REPLACE_ME_ASSISTANT_ID"
$
export HUME_VOICE_ID="REPLACE_ME_CUSTOM_HUME_VOICE_ID"
$
$
curl -X PATCH "https://api.vapi.ai/assistant/${VAPI_ASSISTANT_ID}" \
>
  -H "Authorization: Bearer ${VAPI_TOKEN}" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "voice": {
>
      "provider": "hume",
>
      "model": "octave",
>
      "voiceId": "'"${HUME_VOICE_ID}"'",
>
      "isCustomHumeVoice": true
>
    }
>
  }'

Step 2B: Create a new assistant

Replace the REPLACE_ME values before running these commands in your terminal.

$
export VAPI_TOKEN="REPLACE_ME_VAPI_API_KEY"
$
export HUME_VOICE_ID="REPLACE_ME_CUSTOM_HUME_VOICE_ID"
$
$
curl -X POST "https://api.vapi.ai/assistant" \
>
  -H "Authorization: Bearer ${VAPI_TOKEN}" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "name": "Hume Voice Agent (Custom)",
>
    "model": {
>
      "provider": "openai",
>
      "model": "gpt-4o-mini"
>
    },
>
    "voice": {
>
      "provider": "hume",
>
      "model": "octave",
>
      "voiceId": "'"${HUME_VOICE_ID}"'",
>
      "isCustomHumeVoice": true
>
    },
>
    "firstMessage": "Hi! How can I help today?",
>
    "firstMessageMode": "assistant-speaks-first-with-model-generated-message"
>
  }'

Speech timing

Vapi allows you to control when the assistant starts and stops speaking in response to the user. These settings can be adjusted in the Speech configuration section of the assistant dashboard.

The two primary options are:

1. Start speaking plan: Defines how long the assistant waits after the user stops speaking before beginning its response.
2. Stop speaking plan: Controls when the assistant should stop speaking if the user begins talking again.

These settings let you tune the assistant’s responsiveness and interruptibility based on your use case. Refer to Vapi’s speech configuration documentation for detailed configuration options.

Testing and validation

You can validate your assistant’s voice configuration using the built-in testing tools in the Vapi dashboard.

To confirm that a Hume voice is working as expected:

• Use the Test Assistant feature to preview how it sounds with the selected voice.
• Run test calls using either the phone or web client integrations.
• Listen for correct voice playback and natural timing.
• Check the assistant logs for any issues related to voice selection or audio generation.

Troubleshooting tips

If your assistant is not responding with a Hume voice as expected, check the following:

• No audio playback: Make sure a voice is selected and that the assistant has a valid response. If you’re using a custom voice, confirm the voice ID is correct.
• First message is silent: Vapi may not trigger voice playback for the assistant’s initial message unless both firstMessage and firstMessageMode are configured. Check your assistant settings to ensure these are set.
• Voice fallback triggers unexpectedly: If a fallback voice is used, review the assistant logs for any timeouts or synthesis errors. This may indicate an issue retrieving or playing audio from Hume.
• Custom voice not working: If you entered a custom voice ID, verify that the voice is available in your Hume account and was created successfully. Test with a Voice Library voice to isolate the issue.

Resources