메시징

sendMessage(text)

아바타에게 텍스트 메시지를 전송합니다. 아바타가 LLM 응답을 생성하여 음성으로 답합니다.

SDK.sendMessage('안녕하세요');

파라미터	타입	설명
text	string	전송할 메시지

speak(option)

아바타가 주어진 텍스트를 그대로 읽도록 합니다 (LLM 처리 없이).

문자열 또는 옵션 객체를 전달할 수 있습니다.

// 텍스트만
SDK.speak('이 문장을 그대로 읽어주세요');

// 옵션 객체로
SDK.speak({ text: '안녕하세요.' });

파라미터	타입	설명
option	string | SpeakOption	텍스트 문자열 또는 옵션 객체

SpeakOption

필드	타입	필수	설명
text	string	O	아바타가 읽을 텍스트

발화를 멈추고 다시 말하게 하려면

stopSpeaking() 직후 speak()나 sendMessage()를 바로 호출하면 서버에서 요청이 처리되지 않을 수 있습니다. 안전한 호출 패턴은 아바타 제어 > stopSpeaking()을 참고하세요.

sendSpeakAudio(audio, sample_rate)

Base64 인코딩된 오디오 데이터를 전송하여 아바타가 해당 음성으로 립싱크(lip-sync) 합니다.

SDK.sendSpeakAudio(base64AudioData);

// 샘플레이트를 함께 전달
SDK.sendSpeakAudio(base64AudioData, sampleRate);

파라미터	타입	필수	설명
audio	string	O	Base64 인코딩된 오디오 데이터
sample_rate	number	X	전송하는 오디오의 샘플레이트(Hz). 원본 오디오의 실제 샘플레이트를 그대로 전달하세요 — 예: 브라우저 녹음이면 AudioContext.sampleRate(보통 48000). 생략하면 서버가 16000Hz로 간주해 처리하므로, 원본이 16000Hz가 아니면 재생 속도·음정이 왜곡될 수 있습니다.

• 크기 제한은 호출 1회당 적용됩니다. Base64를 디코딩한 원본 바이트가 0.1MB를 넘으면 그 호출은 전송되지 않습니다. 여러 번 나누어 호출하면 각 호출이 개별적으로 검사되며, 누적 총량에는 이 제한이 적용되지 않습니다.
• audio에는 Base64 문자열만 전달하세요. data:audio/...;base64, 같은 data URL prefix가 붙어 있으면 전송되지 않습니다.
• 크기를 초과하거나 Base64 형식이 올바르지 않아도 예외는 발생하지 않습니다. 해당 호출만 전송되지 않고 콘솔에 경고 로그가 남습니다(기본 log_level 기준 — error/silent로 낮추면 표시되지 않습니다).
• audio는 항상 조각 하나의 Base64 문자열입니다(배열이 아님). 긴 오디오는 아래처럼 문자열을 잘라 호출을 반복하고, 전송이 끝나면 endSpeakAudio()를 호출하세요.

const CHUNK_SIZE = 96 * 1024;

for (let i = 0; i < base64Audio.length; i += CHUNK_SIZE) {
  const chunk = base64Audio.slice(i, i + CHUNK_SIZE); // string
  SDK.sendSpeakAudio(chunk, sampleRate);
}
SDK.endSpeakAudio();

endSpeakAudio()

오디오 립싱크 전송을 종료합니다. 마지막 청크를 전송한 뒤 1회 호출합니다. 서버가 이 신호를 받으면 수신한 오디오로 립싱크 처리를 시작합니다.

SDK.endSpeakAudio();

clearMessages()

<chat-container> 사용 시 대화 메시지 목록을 비웁니다.

SDK.clearMessages();