Ultravox

Ultravox Realtime은 Fixie AI가 만든 실시간 음성 AI 플랫폼이에요. best-in-class 오픈웨이트 모델을 기반으로 완전 호스팅된 환경에서 저지연(low-latency) 음성 에이전트 앱을 만들 수 있어요. 전통적인 음성 AI처럼 ASR(음성 인식) 파이프라인을 거치지 않고 음성을 직접 이해해서 더 빠르고 문맥을 잘 파악하는 게 특징이에요. 26개 언어를 지원하고, REST API와 다양한 SDK, 텔레포니 연동까지 갖춘 API-first 플랫폼이라 전화 통화부터 웹·네이티브 앱까지 어디서나 음성 AI를 붙일 수 있어요. 분당 $0.05라는 가격으로 엔터프라이즈급 성능을 제공하고, 유료 플랜에서는 동시 통화 수 제한(concurrency cap)이 없어요.

출처: 문서

본문

Ultravox는 음성 AI 에이전트를 "통화(call)"라는 단위로 다뤄요. 매 상호작용은 다음과 같은 단순한 패턴을 따라요.

통화 생성(Call Creation) → REST API로 에이전트를 설정하고 통화를 만들어요.
통화 참여(Join Call) → SDK, 텔레포니, 또는 WebSocket으로 사용자를 연결해요.

이 과정에서 통화 생성 API는 joinUrl을 돌려주고, 클라이언트 SDK / 텔레포니 브리지 / WebSocket 중 원하는 방법으로 통화를 이어가요.

핵심 개념

ASR 없는 직접 음성 이해: 기존 시스템들이 음성→텍스트(ASR) 단계를 거치는데, Ultravox는 음성을 직접 이해해요. 그래서 응답이 빠르고 맥락 인지력이 좋아요.
모델: 기본적으로 ultravox-v0.7 모델을 사용해요. model 필드로 바꿀 수 있고, 사용 가능한 모델 목록은 GET /api/models로 조회해요.
Tools (함수 호출): 에이전트에 데이터베이스 접근, API 호출 같은 기능을 연결할 수 있어요. 내장 툴과 커스텀 툴을 모두 지원해요.
Knowledge (RAG): 커스텀 지식 코퍼스(corpus)를 만들어 에이전트에 제품 문서·지식 베이스를 주입할 수 있어요.
Call Stages: 다단계 대화 흐름(브랜칭)을 만들 수 있어요.
Conversation History: 오디오 녹음과 전체 텍스트 기록을 조회할 수 있어요.
Voice Cloning: 에이전트 전용 음성 복제를 지원해요.
텔레포니 연동: Twilio, SIP 등 bring-your-own-telephony 방식으로 전화망과 연동돼요.
Webhooks: 주요 이벤트에 대한 실시간 알림을 받을 수 있어요.

내가 가진 전화번호/브라우저로 시작하기

브라우저에서 먼저 테스트해보고 싶다면 Ultravox Console(https://app.ultravox.ai)에서 코드 없이 에이전트를 만들 수 있어요. Agents 화면에서 New Agent → 이름과 시스템 프롬프트 입력 → 음성 선택 → Test Agent 버튼으로 통화를 시작하면 돼요. 예시 프롬프트는 다음과 같아요.

Your name is Steve. You are a world-class conversationalist.
Ask the person their name and then chat with them.

REST API

Ultravox API는 https://api.ultravox.ai/api/ 베이스 URL을 사용해요. API 키는 41자(8자 + 마침표 + 32자)로 이루어져 있고, 요청 시 X-API-Key 헤더에 담아 보내요. API 키는 절대 클라이언트 코드에 노출하면 안 돼요 (로컬 데모에서만 X-Unsafe-API-Key 헤더 사용 가능).

통화 목록을 가져오는 예시:

curl --request GET \
--url https://api.ultravox.ai/api/calls \
--header 'X-API-Key: ***'

fetch('https://api.ultravox.ai/api/calls', {
  method: 'GET',
  headers: {
    'X-API-Key': 'aBCDef.123456'
  }
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

무료 계정 가입 시 통화에 쓸 수 있는 30분이 기본 제공돼요.

SDK 설치

클라이언트 SDK는 WebRTC 기반으로 저지연 고품질 오디오를 제공하며, 여섯 가지 구현체가 있어요.

# JavaScript
npm install ultravox-client

# Flutter
flutter add ultravox_client

# React Native
npm install ultravox-react-native

# Python
pip install ultravox-client

Kotlin (Android): Maven Central에서 찾을 수 있어요.
Swift (iOS): Swift Package Index에서 찾을 수 있어요.

각 SDK의 전체 구현은 SDK Reference에서 확인할 수 있어요.

직접 통화 만들기 예시

에이전트 없이 REST API로 직접 통화를 생성하는 방법이에요. systemPrompt, voice, model, firstSpeakerSettings, selectedTools 등을 지정할 수 있어요.

const startDirectCall = async () => {
  const response = await fetch('https://api.ultravox.ai/api/calls', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key': 'your-api-key'
    },
    body: JSON.stringify({
      systemPrompt: "You are a helpful customer service agent. Be friendly and professional.",
      voice: "Jessica",
      temperature: 0.3,
      model: "ultravox-v0.7",
      joinTimeout: "30s",
      maxDuration: "3600s",
      recordingEnabled: false,

      firstSpeakerSettings: {
        agent: {
          text: "Hello! How can I help you today?"
        }
      },

      selectedTools: [
        { toolName: 'knowledgebaseLookup' },
        { toolName: 'transferToHuman' }
      ],

      metadata: {
        purpose: "customer_support",
        test: "true"
      }
    })
  });

  return await response.json();
};

새 프로젝트에서는 에이전트(agent)를 먼저 만들어 재사용하는 방식이 권장돼요. 기존 에이전트로 통화를 시작하려면 POST https://api.ultravox.ai/api/agents/{agentId}/calls를 호출하고 templateContext 등으로 템플릿 변수를 넘기면 돼요. priorCallId 쿼리 파라미터를 쓰면 이전 통화의 속성과 메시지 기록을 그대로 이어받을 수도 있어요.

API 제한 사항

계정 단위 초당 500회, API 키 단위 초당 200회의 API 요청 제한이 있어요.
통화 생성은 플랜별로 제한돼요: Free/PAYGO 초당 5회·분당 30회, Pro 초당 10회·분당 120회, Scale 초당 30회·분당 360회.
동시 통화 수: Free/PAYGO 최대 5콜, Pro와 Scale은 하드 캡 없음 (Scale은 최대 100까지 우선 접근).
제한을 초과하면 429 상태 코드가 반환돼요.

더 알아보기 (Learn more)

공식 문서