Skip to content
Ultravox API

Quickstart

Creating your first voice-powered AI agent with Ultravox is easy. This guide will walk you through the process of creating a simple voice-enabled AI agent.

There are three main steps to building a voice-enabled AI agent with the Ultravox API:

  1. Create a Call → Construct a systemPrompt and choose a voice for your AI agent. This returns a joinUrl that you use to join the call.

  2. Join the Call → Using the joinUrl from the previous step, join the call which starts a speech-to-speech conversation with your AI agent.

  3. End the Call → When the conversation is complete, end the call to stop the conversation.

Create a Call

The first step is to create a call. This is done by doing a POST to the /calls endpoint. This call should be made from a server to prevent accidentally leaking your API key on the client. Here is what that looks like:

Terminal window
curl --location 'https://api.ultravox.ai/api/calls' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: ••••••' \
--data '{
    "systemPrompt": "You are an expert on speech-to-speech communication.",
    "temperature": 0.8,
}'

This returns the following response:

{
    "callId": "9b74f1aa-0802-4198-a5f3-cfa89871aebb",
    "created": "2024-08-12T18:47:22.365692Z",
    "ended": null,
    "model": "fixie-ai/ultravox",
    "systemPrompt": "You are an expert on speech-to-speech communication.",
    "temperature": 0.8,
    "voice": null,
    "languageHint": null,
    "joinUrl": "wss://voice...app/calls/9b74f1aa-0802-4198-a5f3-cfa89871aebb"
}

We will ignore voice and languageHint for now.

The joinUrl will be used in the next step.

Join the Call

Now that we have a joinUrl, we can use the ultravox-client in our application to join the call. The ultravox-client is available for multiple languages. More info on the SDK page.

We need to reference the ultravox-client in our front-end, create an UltravoxSession, and then call the joinCall method:

<script type="module">
  import { UltravoxSession } from 'https://unpkg.com/ultravox-client/dist/esm/session.js?module';
  let UVSession = new UltravoxSession();
  const joinUrl = "wss://voice...app/calls/9b74f1aa-0802-4198-a5f3-cfa89871aebb" // From the POST to /calls
  UVSession.joinCall(joinUrl);
</script>

End the Call

When the call is over, simply use the endCall() method on the UltravoxSession object:

UVSession.leaveCall();

Examples

There are some examples you can fork and run.