API 가이드 · VisionAI Docs

로컬 API 기본 주소는 http://127.0.0.1:8010입니다. 재생 화면에서 Connect를 누르면 상단 SID에 세션 ID가 표시됩니다. 아래 예제의 SESSION_ID를 그 값으로 바꾸세요.

응답과 세션

일반 업무 API는 JSON의 code가 0이면 성공입니다. 오류를 HTTP 상태만으로 판단하지 말고 code와 msg도 확인합니다. /offer는 SDP answer와 sessionid를 반환하며 일반 업무 API 형식과 다릅니다.

{ "code": 0, "msg": "ok" }

텍스트 읽기

curl -X POST http://127.0.0.1:8010/human \
  -H 'Content-Type: application/json' \
  -d '{
    "sessionid": "SESSION_ID",
    "text": "안녕하세요. 실시간 아바타입니다.",
    "type": "echo",
    "interrupt": false,
    "tts": { "ref_file": "ko-KR-InJoonNeural" }
  }'

echo는 입력 문장을 그대로 읽습니다. chat은 별도 LLM 응답 함수를 사용합니다. interrupt: true를 지정하면 기존 발화를 비우고 새 문장을 공급합니다. Edge TTS의 메시지별 음성 옵션 키는 **tts.ref_file**입니다.

브라우저 앱에서는 VisionAI 서버에 연결해 받은 세션 ID로 같은 요청을 보냅니다. 아래 예제는 VisionAI과 같은 출처에서 실행하는 경우입니다.

async function speak(sessionid, text) {
  const response = await fetch('/human', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ sessionid, text, type: 'echo' }),
  });
  const result = await response.json();
  if (!response.ok || result.code !== 0) {
    throw new Error(result.msg || '텍스트 전송 실패');
  }
  return result;
}

다른 포트나 도메인의 앱에서는 API 주소를 명시하고 CORS, 인증과 미디어 접속 정책을 함께 구성합니다. 이 문서 사이트의 4321 포트에 /human을 보내면 VisionAI에 전달되지 않습니다.

음성 파일 입력

# LiveTalking 디렉터리에서 실행
curl -X POST http://127.0.0.1:8010/humanaudio \
  -F 'sessionid=SESSION_ID' \
  -F 'file=@output/mac-test/korean-test.wav'

multipart/form-data로 file과 sessionid를 보냅니다. 파일 안의 음성으로 아바타가 말하므로 별도 TTS가 필요하지 않습니다. 이 인터페이스는 파일 제출 방식입니다.

중단과 발화 상태

경로	메서드	JSON 본문	역할
`/interrupt_talk`	POST	`{"sessionid":"SESSION_ID"}`	발화·대기 음성 큐 비우기
`/is_speaking`	POST	`{"sessionid":"SESSION_ID"}`	`data`의 발화 상태 확인
`/disconnect`	POST	`{"sessionid":"SESSION_ID"}`	연결·세션 해제, 로컬 추가 API
`/api/admin/sessions`	GET	없음	활성 세션과 설정 조회

/disconnect는 현재 로컬 수정에 추가한 경로입니다. upstream 원본과 별도입니다. 신규 버전에서는 실제 라우트를 확인하세요.

영상 녹화

녹화는 영상이 연결되고 재생된 이후에 시작합니다. 재생 페이지의 녹화 UI 또는 아래 API를 사용합니다.

curl -X POST http://127.0.0.1:8010/record \
  -H 'Content-Type: application/json' \
  -d '{"sessionid":"SESSION_ID","type":"start_record"}'

# 텍스트 또는 음성을 재생한 뒤 녹화 종료
curl -X POST http://127.0.0.1:8010/record \
  -H 'Content-Type: application/json' \
  -d '{"sessionid":"SESSION_ID","type":"end_record"}'

종료 후 data/record/SESSION_ID.mp4에 저장되며 GET /record/SESSION_ID로 다운로드할 수 있습니다. 서버에 FFmpeg가 필요합니다.

아바타 생성 API

현재 Mac의 파일 경로를 JSON으로 제출하는 예제입니다. 경로는 서버에서 접근 가능한 파일을 가리켜야 합니다.

curl -X POST http://127.0.0.1:8010/api/avatar/task \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "wav2lip",
    "avatar_id": "my_avatar_002",
    "video_path": "/Users/dimplejuno/Developments/GithubDev/LiveTalking/output/mac-test/person-camera-avatar-source-25fps.mp4",
    "img_size": 256,
    "face_det_batch_size": 1,
    "pads": "0 10 0 0"
  }'

응답의 data.task_id를 사용해 상태를 조회합니다.

curl http://127.0.0.1:8010/api/avatar/task/TASK_ID
curl http://127.0.0.1:8010/api/avatar/tasks

상태는 pending → running → completed 또는 failed이며 progress, error_msg를 확인할 수 있습니다. 업로드할 때는 multipart의 video_file, model, avatar_id를 사용합니다. 다른 이름의 ID로 생성하면 기존 아바타 덮어쓰기를 피할 수 있습니다.

WebRTC 연동의 기준

직접 재생 UI를 구현하려면 현재 web/index-en.html의 offer 생성, ICE 수집, 트랙 연결과 Disconnect 처리를 참고하세요. /offer 요청은 sdp, type: "offer", 선택값 avatar, refaudio, reftext를 받습니다. 서버 응답을 remote description으로 적용하고 sessionid를 저장합니다.

현재 /whep 경로도 있으나, 문서에 기재된 모든 추가 query 옵션이 세션 생성 코드에 적용되는 것은 아닙니다. 현재 build_avatar_session()은 인물, 참조 음성·문장과 사용자 액션을 반영하며 TTS 엔진 변경은 서버 설정을 기준으로 합니다.

참고: 공식 API 문서, 아바타 API 문서. 현재 동작의 기준은 로컬 server/routes.py, server/avatar_routes.py, app.py입니다.