Skip to main content
POST
/
api
/
open
/
v4
/
liveAvatar
/
session
/
create
Create Session
curl --request POST \
  --url https://openapi.akool.com/api/open/v4/liveAvatar/session/create \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "avatar_id": "dvp_Tristan_cloth2_1080P",
  "knowledge_id": "64f8a1b2c3d4e5f6a7b8c9d0",
  "duration": 3600,
  "voice_id": "iP95p4xoKVk53GoZ742B",
  "language": "en",
  "mode_type": 2,
  "background_url": "https://example.com/background.jpg",
  "stream_type": "agora",
  "credentials": {
    "agora_uid": 100000,
    "agora_app_id": "your-app-id",
    "agora_channel": "your-channel",
    "agora_token": "your-token"
  },
  "voice_params": {
    "speed": 1,
    "pron_map": {
      "akool": "ai ku er"
    },
    "stt_type": "openai_realtime",
    "turn_detection": {
      "type": "server_vad",
      "threshold": 0.5,
      "prefix_padding_ms": 300,
      "silence_duration_ms": 500
    }
  }
}'
{
  "code": 1000,
  "msg": "OK",
  "data": {
    "_id": "<string>",
    "uid": 123,
    "type": 123,
    "status": 1,
    "stream_type": "<string>",
    "credentials": {
      "agora_uid": 123,
      "agora_app_id": "<string>",
      "agora_channel": "<string>",
      "agora_token": "<string>",
      "livekit_url": "<string>",
      "livekit_token": "<string>",
      "livekit_room_name": "<string>",
      "livekit_server_identity": "<string>",
      "livekit_client_identity": "<string>",
      "trtc_sdk_app_id": 123,
      "trtc_sdk_room_id": "<string>",
      "trtc_sdk_user_id": "<string>",
      "trtc_sdk_user_sig": "<string>"
    }
  }
}
Both the avatar_id and voice_id can be easily obtained by copying them directly from the web interface. You can also create and manage your streaming avatars using our intuitive web platform.Create and manage your avatars at: https://akool.com/apps/upload/avatar?from=%2Fapps%2Fstreaming-avatar%2Fedit
Knowledge Base Integration: You can enhance your streaming avatar with contextual AI responses by integrating a Knowledge Base. When creating a session, provide a knowledge_id parameter to enable the AI to use documents and URLs from your knowledge base for more accurate and relevant responses.

Authorizations

​
x-api-key
string
header
required

Your API Key used for request authorization. If both Authorization and x-api-key have values, Authorization will be used first and x-api-key will be discarded.

Body

application/json
​
avatar_id
string
required

Digital human model in real-time avatar. If you want to use a custom uploaded video, you need to call the avatar/create interface to create a template. This process takes some time to process. You can check the processing status through the avatar/detail interface. When status=3, you can use the avatar_id field to pass it in.

​
duration
number

Session duration in seconds (max: 3600). Credits are pre-charged for the full duration, but any unused credits will be refunded after the session ends. Rates depend on your subscription plan.

Required range: x <= 3600
​
knowledge_id
string

Knowledge base ID to provide context for AI responses. Create and manage knowledge bases using the Knowledge Base API. When provided, the AI will use documents and URLs from the knowledge base to enhance response accuracy.

​
voice_id
string

Voice ID to change avatar's voice. Get valid IDs from Voice List API

​
voice_url
string

Custom voice model URL. Get valid URLs from Voice List API

​
language
string

Language code to use for the session. Get valid codes from Language List API

​
mode_type
enum<integer>

Avatar interaction style. "1" = Retelling (avatar repeats content), "2" = Dialogue (avatar engages in conversation)

Available options:
1,
2
​
background_url
string

URL of background image/video for avatar scene

​
voice_params
object
​
stream_type
enum<string>
default:agora

Stream type to use for the session. "agora" = Agora (default), "livekit" = Livekit, "trtc" = TRTC

Available options:
agora,
livekit,
trtc
​
credentials
object

Response

200 - application/json

Session created successfully

​
code
integer
required

Interface returns business status code (1000: success)

Example:

1000

​
msg
string
required

Interface returns status information

Example:

"OK"

​
data
object