실시간 음성 런타임 API 작성

​

런타임별 값

​

제공사별 기능 호환성

​

Grok Voice

{
  "type": "grok_voice",
  "model": "grok-voice-think-fast-2.0",
  "voice": { "type": "builtin", "name": "eve" }
}

​

Gemini Live

{
  "type": "gemini_live",
  "model": "gemini-2.5-flash-native-audio-preview-12-2025",
  "voice": { "type": "builtin", "name": "Puck" }
}

​

런타임 선택

{
  "runtime": {
    "type": "gpt_live",
    "model": "gpt-live-1",
    "voice": {
      "type": "builtin",
      "name": "marin"
    }
  }
}

{
  "runtime": {
    "type": "gpt_live",
    "model": "gpt-live-1",
    "voice": {
      "type": "custom",
      "id": "voice_..."
    }
  }
}

• 자리: 모든 네이티브 음성은 runtime.voice에 두세요. 기존 파이프라인용 data.voice나 TTS 설정 아래에 넣지 마세요.
• GPT-Live: OpenAI 빌트인 음성이나 승인된 커스텀 음성 참조를 써요. 커스텀 음성은 기본으로 꺼져 있고 워크스페이스별 승인과 프로비저닝이 필요해요. voice_... 값은 파이프라인 음성 카탈로그에서 조회했거나 소유했다는 이유만으로 허용되지 않아요. 커스텀 참조만으로 품질 검증까지 끝났다고 볼 수 없어요.
• Grok Voice, Gemini Live: 제공사가 정한 빌트인 이름만 받고, custom 음성과 OpenAI 커스텀 참조는 거부해요.
• 기존 파이프라인 음성: 설정을 그대로 유지하고 자동으로 마이그레이션하지 않아요.

​

LLM과의 관계

curl "https://client-api.tryvox.co/v3/models/llms" \
  -H "Authorization: Bearer $VOX_API_KEY"

​

수정 충돌 방지와 데이터 병합

​

네이티브 실시간 에이전트 만들기

curl -X POST "https://client-api.tryvox.co/v3/agents" \
  -H "Authorization: Bearer $VOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "업무 상담 에이전트",
    "type": "single_prompt",
    "data": {
      "prompt": {
        "prompt": "고객의 업무 문의를 짧고 정확하게 안내하세요."
      },
      "llm": {
        "model": "<GET /v3/models/llms에서 선택한 모델>"
      },
      "runtime": {
        "type": "gpt_live",
        "model": "gpt-live-1",
        "voice": {
          "type": "builtin",
          "name": "marin"
        }
      }
    }
  }'

​

런타임 전환

{
  "data": {
    "llm": {
      "model": "<기존 또는 새로 선택한 text LLM>"
    },
    "runtime": {
      "type": "pipeline"
    },
    "stt": {
      "languages": ["ko"],
      "speed": "high"
    },
    "voice": {
      "id": "<GET /v3/models/voices에서 선택한 voice id>",
      "provider": "<voice catalog provider>"
    }
  }
}

​

스키마 확인하기

​

작성 체크리스트

• 런타임 생략: 새로 만들 때 data.runtime을 생략하거나 type: "pipeline"으로 보내면 기존 파이프라인 계약을 써요. 수정할 때 runtime을 생략하면 현재 런타임을 유지해요.
• 런타임 객체: 네이티브 실시간은 type, model, voice를 runtime 안에 두세요.
• GPT-Live 빌트인 음성: 예시는 runtime.voice: {"type":"builtin","name":"marin"}이에요. 이 값은 예시이고 런타임이 음성을 자동으로 고르지 않아요.
• Grok Voice, Gemini Live의 모델과 음성: 각각 grok-voice-think-fast-2.0과 gemini-2.5-flash-native-audio-preview-12-2025 모델, 그 제공사 전용 빌트인 음성을 꼭 적으세요. 음성 허용값은 지금 스키마에서 확인하세요.
• Grok Voice, Gemini Live의 음성 형식: builtin 음성만 받아요. GPT-Live의 custom 형식은 이 두 런타임에서 거부돼요.
• GPT-Live 커스텀 음성: 파이프라인 카탈로그와 별개인 새 GPT-Live 전용 참조예요. 기존 파이프라인 음성은 그대로 두고 마이그레이션하지 않아요. 승인과 품질 검증 전에는 실행할 수 있는 설정이라고 약속하지 않아요.
• data.llm.model: 새 네이티브 실시간 에이전트를 만들 때 고를 수 있는 값을 꼭 넣으세요.
• chatLlm: 만들지 마세요. data.llm을 네이티브 런타임 모델로 암묵 변환하지도 않아요.
• 파이프라인 필드: 네이티브 실시간 요청에 stt, data.voice, parallelSTT, sttPreference, voicePreference, 지금 스키마에서 호환되지 않는 legacy speech preference를 넣지 마세요. data.speech 전체를 한꺼번에 지우지도 마세요.
• 끼어들기 허용: 세 런타임 모두 유효한 data.speech.isAllowInterruption 값이 true여야 해요. 만들 때 생략하면 기본값 true를 쓰지만, 수정할 때 생략하면 현재 값을 유지해요. 서버가 값을 강제로 바꾸지 않아요.
• 파이프라인 복귀: 파이프라인으로 되돌릴 때는 stt와 voice를 적으세요.
• 플로우 노드 LLM: 기존 플로우를 수정할 때 flow.nodes[].data.llm 오버라이드를 보존하세요. GPT-Live 기능이 아니에요.
• 조회 응답: 읽은 응답의 stt, voice가 null이거나 없을 수 있으니 그 경우를 처리하세요.

​

관련 문서

• 소개: v3 API의 인증, 컨벤션, 에이전트 data 수정 규칙
• 에이전트 버전 관리: 버전을 배포하고 프로덕션으로 지정하기
• 음성 인식 & 발화: 파이프라인 에이전트의 언어와 목소리 정하기
• API로 플로우 작성 및 검증: flow 필드로 플로우 에이전트를 작성하고 검증하기