버전: 최신 버전

Start Session

세션 토큰으로 인터랙티브 아바타 세션을 시작합니다. 응답으로 받은 livekit.url과 livekit.token으로 실시간 영상 스트리밍에 연결합니다.

LiveKit 이란?

LiveKit은 WebRTC 기반의 실시간 영상 스트리밍 인프라입니다. Start Session API 응답으로 livekit.url, livekit.token, room_name을 받은 뒤 client에서 room.connect(url, token)과 같은 메서드로 LiveKit server에 연결합니다. 연결이 성공하면 아바타의 영상, 음성, 데이터 채널이 실시간으로 스트리밍됩니다.

POST /api/v2/sessions/start

Headers

헤더	값
Authorization	Bearer {session_token}
Content-Type	application/json

Body

필드	타입	필수 여부	설명
avatar_id	string	required	사용할 Avatar / model ID
avatar_persona	object	optional	Persona 및 LLM override. 생략 시 server default가 적용됩니다: English(`en`), OpenAI, `gpt-4.1-nano`.
avatar_persona.language	string	optional	예: `en`, `ko`, `en-US`
avatar_persona.llm_configurations	object	optional	LLM provider/model 설정. 생략 시 server default가 적용됩니다.
avatar_persona.llm_configurations.provider	string	optional	예: `openai`, `anthropic`, `google`, `custom`
avatar_persona.llm_configurations.model	string	optional	Model ID
avatar_persona.llm_configurations.temperature	number	optional	LLM으로 전달되는 temperature
avatar_persona.llm_configurations.custom_settings	object	optional	`greeting_text`, `system_prompt` override
avatar_persona.llm_configurations.custom_http	object	optional	`provider`가 `"custom"`일 때 사용합니다. `endpoint` 또는 `url`이 필요합니다.
max_session_duration	integer	optional	세션 최대 길이(분). Plan limit 이하여야 합니다.
lip_audio_mode	string	optional	`llm_tts` 또는 `external_pcm`. 생략 시 기본 audio 동작이 적용됩니다.

max_session_duration을 생략하면 Account subscription limit이 적용됩니다. max_session_numbers는 request body에서 받지 않으며 subscription plan에 따라 결정됩니다.

Custom HTTP LLM

자체 HTTP LLM endpoint를 session에서 사용하려면 avatar_persona.llm_configurations.provider: "custom"과 custom_http를 사용합니다.

필드	타입	설명
endpoint	string	Custom LLM server의 전체 POST URL
url	string	`endpoint` alias. `endpoint`가 없으면 `endpoint`로 mapping됩니다.
connect_timeout_sec, read_timeout_sec, timeout_sec	number	연결/읽기 timeout(초)
max_messages, max_chars, max_buffer_chars	number	대화 trim 및 text flush 제한
http_error_message	string	Upstream HTTP 4xx/5xx 발생 시 반환할 message prefix
stream_connect_retries, stream_connect_retry_delay_sec	number	첫 SSE line 또는 response body를 받기 전 retry 설정
headers, extra_headers	object	정적 header. 둘 중 하나 사용을 권장합니다. 둘 다 있으면 `headers`를 사용합니다.
auth_plugins	array	Auth plugin objects
stream	boolean	기본값은 SSE용 `true`. 단일 JSON 응답이면 `false`를 사용합니다.
api_preset	string	`openai_compatible`(기본), `anthropic_messages`, `gemini_generate_content`

api_preset은 custom endpoint로 보낼 HTTP payload 형식과 응답 parser를 선택하는 값입니다. Provider 공식 API의 모든 옵션을 그대로 지원한다는 의미는 아닙니다. 더 복잡한 provider-specific 옵션이 필요하면, 자체 HTTP gateway에서 해당 옵션을 처리하고 이 API가 지원하는 응답 형식으로 반환하세요.

Preset	적합한 경우	Streaming 응답	Non-streaming 응답
`openai_compatible`	OpenAI-compatible Chat Completions endpoint 또는 일반적인 LLM gateway	Text delta가 들어 있는 SSE chunk	`choices[0].message.content`에 text가 들어 있는 단일 JSON
`anthropic_messages`	Anthropic Messages 형식을 따르는 endpoint	Text delta가 들어 있는 SSE event	`content` text block이 들어 있는 단일 JSON
`gemini_generate_content`	Gemini GenerateContent 형식을 따르는 endpoint	`streamGenerateContent` 기반 SSE 응답	`generateContent` 기반 단일 JSON

Protocol 세부사항, 지원되는 커스터마이징 범위, socket/WebSocket 제한은 Custom HTTP LLM을 참고하세요.

동작 메모:

api_preset 기본값은 openai_compatible입니다. Anthropic Messages API payload에는 anthropic_messages, Gemini GenerateContent payload에는 gemini_generate_content를 사용합니다.
api_preset이 anthropic_messages이면 model이 필수입니다.
stream 기본값은 true이며 SSE를 기대합니다. Upstream이 단일 JSON 응답을 반환할 때만 stream: false를 설정하세요. openai_compatible에서는 choices[0].message.content에서 text를 읽습니다.
Header merge 순서는 default headers(Content-Type, Accept) → headers / extra_headers → auth_plugins입니다. 뒤 값이 앞 값을 덮어씁니다.
기본 timing 값은 connect_timeout_sec: 10, read_timeout_sec: 120, stream_connect_retries: 1, stream_connect_retry_delay_sec: 0.4입니다.
Production에서는 신뢰할 수 없는 client가 raw API key를 보내게 하기보다 auth_plugins 또는 environment-backed header로 server-side에서 secret을 조합하는 방식을 권장합니다.

Greeting / first utterance

custom_settings.greeting_text가 있고 trim 후 빈 문자열이 아니면, 서비스는 Start Session 성공 직후 server-side chat message를 자동으로 한 번 보냅니다.

Message: [FIRST_MESSAGE] + trimmed greeting_text
Server-sent Talk message type: first_message

팁: [FIRST_MESSAGE] 뒤에 붙은 텍스트는 그대로 아바타가 발화합니다. 아바타가 말해야 할 최종 발화문이 이미 준비되어 있을 때, 해당 응답을 직접 주입하는 용도로 활용할 수 있습니다.

lip_audio_mode가 external_pcm이면 서비스는 자동 첫 message를 보내지 않습니다.

예시

기본 session

cURL
Node.js
Python

curl https://ai-streamer.deepbrain.io/api/v2/sessions/start \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -d '{
    "avatar_id": "${YOUR_AVATAR_ID}"
  }'

import axios from "axios";
const sessionToken = "${SESSION_TOKEN}";

axios
  .post(
    "https://ai-streamer.deepbrain.io/api/v2/sessions/start",
    {
      avatar_id: "${YOUR_AVATAR_ID}",
    },
    {
      headers: {
        Authorization: `Bearer ${sessionToken}`,
        "Content-Type": "application/json",
      },
    },
  )
  .then((res) => {
    console.log(res.data);
  })
  .catch((error) => {
    console.error(error);
  });

import requests

url = 'https://ai-streamer.deepbrain.io/api/v2/sessions/start'
session_token = '${SESSION_TOKEN}'

headers = {
    'Authorization': f'Bearer {session_token}',
    'Content-Type': 'application/json'
}
body = {
    'avatar_id': '${YOUR_AVATAR_ID}'
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

Custom LLM 사용

Custom HTTP LLM endpoint에 연결합니다.

cURL
Node.js
Python

curl https://ai-streamer.deepbrain.io/api/v2/sessions/start \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -d '{
    "avatar_id": "${YOUR_AVATAR_ID}",
    "avatar_persona": {
      "language": "en",
      "llm_configurations": {
        "provider": "custom",
        "model": "my-llm-model",
        "custom_settings": {
          "system_prompt": "You are a helpful assistant.",
          "greeting_text": "Hello! How can I help you today?"
        },
        "custom_http": {
          "endpoint": "https://your-llm-backend.example.com/v1/chat/completions",
          "api_preset": "openai_compatible",
          "stream": true,
          "read_timeout_sec": 180,
          "headers": {
            "Authorization": "Bearer ${YOUR_LLM_API_KEY}"
          }
        }
      }
    }
  }'

import axios from "axios";
const sessionToken = "${SESSION_TOKEN}";

axios
  .post(
    "https://ai-streamer.deepbrain.io/api/v2/sessions/start",
    {
      avatar_id: "${YOUR_AVATAR_ID}",
      avatar_persona: {
        language: "en",
        llm_configurations: {
          provider: "custom",
          model: "my-llm-model",
          custom_settings: {
            system_prompt: "You are a helpful assistant.",
            greeting_text: "Hello! How can I help you today?",
          },
          custom_http: {
            endpoint:
              "https://your-llm-backend.example.com/v1/chat/completions",
            api_preset: "openai_compatible",
            stream: true,
            read_timeout_sec: 180,
            headers: {
              Authorization: "Bearer ${YOUR_LLM_API_KEY}",
            },
          },
        },
      },
    },
    {
      headers: {
        Authorization: `Bearer ${sessionToken}`,
        "Content-Type": "application/json",
      },
    },
  )
  .then((res) => {
    console.log(res.data);
  })
  .catch((error) => {
    console.error(error);
  });

import requests

url = 'https://ai-streamer.deepbrain.io/api/v2/sessions/start'
session_token = '${SESSION_TOKEN}'

headers = {
    'Authorization': f'Bearer {session_token}',
    'Content-Type': 'application/json'
}
body = {
    'avatar_id': '${YOUR_AVATAR_ID}',
    'avatar_persona': {
        'language': 'en',
        'llm_configurations': {
            'provider': 'custom',
            'model': 'my-llm-model',
            'custom_settings': {
                'system_prompt': 'You are a helpful assistant.',
                'greeting_text': 'Hello! How can I help you today?',
            },
            'custom_http': {
                'endpoint': 'https://your-llm-backend.example.com/v1/chat/completions',
                'api_preset': 'openai_compatible',
                'stream': True,
                'read_timeout_sec': 180,
                'headers': {
                    'Authorization': 'Bearer ${YOUR_LLM_API_KEY}',
                },
            },
        },
    },
}

response = requests.post(url, headers=headers, json=body)
print(response.json())

성공 (`201`, `code: 1000`)

{
  "code": 1000,
  "data": {
    "session_id": "${SESSION_ID}",
    "max_session_duration": 20,
    "max_session_numbers": 10,
    "use_server_ready": true,
    "livekit": {
      "url": "wss://your-livekit-host",
      "room_name": "room-…",
      "token": "${LIVEKIT_ACCESS_TOKEN}"
    }
  },
  "message": "Session created successfully"
}

요청에 lip_audio_mode: "external_pcm"이 포함되면 응답 data에 LiveKit byte stream topic, PCM format, segment 동작을 설명하는 lip_audio가 추가됩니다. lip_audio_mode가 생략되었거나 llm_tts이면 lip_audio는 생략됩니다.

use_server_ready는 LiveKit server-side readiness를 위한 client coordination flag입니다. 현재 V2 start에서는 true로 반환됩니다.

Next Step

Start Session 호출 후 livekit.url과 livekit.token을 사용하여 LiveKit에 연결하면 아바타의 영상과 음성이 실시간으로 스트리밍됩니다. 사용자 message 없이 session을 유지해야 하면 Session Keep-Alive API를 주기적으로 호출하세요.

LiveKit 이란?​

Headers​

Body​

Custom HTTP LLM​

Greeting / first utterance​

예시​

기본 session​

Custom LLM 사용​

성공 (201, code: 1000)​

Next Step​