Create a session
curl --request POST \
--url https://api.boson.ai/v1/avatar/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"avatar_id": "builtin_claire_v1",
"transport": {
"url": "wss://my-project.livekit.cloud",
"room_name": "<string>",
"participant_token": "<string>",
"participant_identity": "boson-avatar-agent",
"publisher_identity": "agent-7f3a",
"type": "livekit",
"audio_source": "data_stream"
},
"model": "higgs-avatar",
"max_duration_seconds": 1800
}
'import requests
url = "https://api.boson.ai/v1/avatar/sessions"
payload = {
"avatar_id": "builtin_claire_v1",
"transport": {
"url": "wss://my-project.livekit.cloud",
"room_name": "<string>",
"participant_token": "<string>",
"participant_identity": "boson-avatar-agent",
"publisher_identity": "agent-7f3a",
"type": "livekit",
"audio_source": "data_stream"
},
"model": "higgs-avatar",
"max_duration_seconds": 1800
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
avatar_id: 'builtin_claire_v1',
transport: {
url: 'wss://my-project.livekit.cloud',
room_name: '<string>',
participant_token: '<string>',
participant_identity: 'boson-avatar-agent',
publisher_identity: 'agent-7f3a',
type: 'livekit',
audio_source: 'data_stream'
},
model: 'higgs-avatar',
max_duration_seconds: 1800
})
};
fetch('https://api.boson.ai/v1/avatar/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.boson.ai/v1/avatar/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'avatar_id' => 'builtin_claire_v1',
'transport' => [
'url' => 'wss://my-project.livekit.cloud',
'room_name' => '<string>',
'participant_token' => '<string>',
'participant_identity' => 'boson-avatar-agent',
'publisher_identity' => 'agent-7f3a',
'type' => 'livekit',
'audio_source' => 'data_stream'
],
'model' => 'higgs-avatar',
'max_duration_seconds' => 1800
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.boson.ai/v1/avatar/sessions"
payload := strings.NewReader("{\n \"avatar_id\": \"builtin_claire_v1\",\n \"transport\": {\n \"url\": \"wss://my-project.livekit.cloud\",\n \"room_name\": \"<string>\",\n \"participant_token\": \"<string>\",\n \"participant_identity\": \"boson-avatar-agent\",\n \"publisher_identity\": \"agent-7f3a\",\n \"type\": \"livekit\",\n \"audio_source\": \"data_stream\"\n },\n \"model\": \"higgs-avatar\",\n \"max_duration_seconds\": 1800\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.boson.ai/v1/avatar/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"avatar_id\": \"builtin_claire_v1\",\n \"transport\": {\n \"url\": \"wss://my-project.livekit.cloud\",\n \"room_name\": \"<string>\",\n \"participant_token\": \"<string>\",\n \"participant_identity\": \"boson-avatar-agent\",\n \"publisher_identity\": \"agent-7f3a\",\n \"type\": \"livekit\",\n \"audio_source\": \"data_stream\"\n },\n \"model\": \"higgs-avatar\",\n \"max_duration_seconds\": 1800\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.boson.ai/v1/avatar/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"avatar_id\": \"builtin_claire_v1\",\n \"transport\": {\n \"url\": \"wss://my-project.livekit.cloud\",\n \"room_name\": \"<string>\",\n \"participant_token\": \"<string>\",\n \"participant_identity\": \"boson-avatar-agent\",\n \"publisher_identity\": \"agent-7f3a\",\n \"type\": \"livekit\",\n \"audio_source\": \"data_stream\"\n },\n \"model\": \"higgs-avatar\",\n \"max_duration_seconds\": 1800\n}"
response = http.request(request)
puts response.read_body{
"id": "avrt_3f9c2a7e8b1d4c6f",
"object": "avatar.realtime.session",
"status": "active",
"model": "higgs-avatar",
"avatar_id": "builtin_claire_v1",
"avatar_identity": "boson-avatar-agent",
"created_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}Avatar Realtime API
Create a session
Start a realtime avatar session: the avatar joins the LiveKit room you name in transport, as the participant whose token you minted, and publishes lip-synced video together with the speech audio that transport.publisher_identity streams to it over a LiveKit data stream. The response is the session object with status: "active"; the avatar is already in the room. Release it with DELETE /v1/avatar/sessions/{session_id} when the conversation ends. Creation is not idempotent: if the response is lost, do not replay the request blindly; look for the avatar participant in the room instead.
POST
/
v1
/
avatar
/
sessions
Create a session
curl --request POST \
--url https://api.boson.ai/v1/avatar/sessions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"avatar_id": "builtin_claire_v1",
"transport": {
"url": "wss://my-project.livekit.cloud",
"room_name": "<string>",
"participant_token": "<string>",
"participant_identity": "boson-avatar-agent",
"publisher_identity": "agent-7f3a",
"type": "livekit",
"audio_source": "data_stream"
},
"model": "higgs-avatar",
"max_duration_seconds": 1800
}
'import requests
url = "https://api.boson.ai/v1/avatar/sessions"
payload = {
"avatar_id": "builtin_claire_v1",
"transport": {
"url": "wss://my-project.livekit.cloud",
"room_name": "<string>",
"participant_token": "<string>",
"participant_identity": "boson-avatar-agent",
"publisher_identity": "agent-7f3a",
"type": "livekit",
"audio_source": "data_stream"
},
"model": "higgs-avatar",
"max_duration_seconds": 1800
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
avatar_id: 'builtin_claire_v1',
transport: {
url: 'wss://my-project.livekit.cloud',
room_name: '<string>',
participant_token: '<string>',
participant_identity: 'boson-avatar-agent',
publisher_identity: 'agent-7f3a',
type: 'livekit',
audio_source: 'data_stream'
},
model: 'higgs-avatar',
max_duration_seconds: 1800
})
};
fetch('https://api.boson.ai/v1/avatar/sessions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.boson.ai/v1/avatar/sessions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'avatar_id' => 'builtin_claire_v1',
'transport' => [
'url' => 'wss://my-project.livekit.cloud',
'room_name' => '<string>',
'participant_token' => '<string>',
'participant_identity' => 'boson-avatar-agent',
'publisher_identity' => 'agent-7f3a',
'type' => 'livekit',
'audio_source' => 'data_stream'
],
'model' => 'higgs-avatar',
'max_duration_seconds' => 1800
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.boson.ai/v1/avatar/sessions"
payload := strings.NewReader("{\n \"avatar_id\": \"builtin_claire_v1\",\n \"transport\": {\n \"url\": \"wss://my-project.livekit.cloud\",\n \"room_name\": \"<string>\",\n \"participant_token\": \"<string>\",\n \"participant_identity\": \"boson-avatar-agent\",\n \"publisher_identity\": \"agent-7f3a\",\n \"type\": \"livekit\",\n \"audio_source\": \"data_stream\"\n },\n \"model\": \"higgs-avatar\",\n \"max_duration_seconds\": 1800\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.boson.ai/v1/avatar/sessions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"avatar_id\": \"builtin_claire_v1\",\n \"transport\": {\n \"url\": \"wss://my-project.livekit.cloud\",\n \"room_name\": \"<string>\",\n \"participant_token\": \"<string>\",\n \"participant_identity\": \"boson-avatar-agent\",\n \"publisher_identity\": \"agent-7f3a\",\n \"type\": \"livekit\",\n \"audio_source\": \"data_stream\"\n },\n \"model\": \"higgs-avatar\",\n \"max_duration_seconds\": 1800\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.boson.ai/v1/avatar/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"avatar_id\": \"builtin_claire_v1\",\n \"transport\": {\n \"url\": \"wss://my-project.livekit.cloud\",\n \"room_name\": \"<string>\",\n \"participant_token\": \"<string>\",\n \"participant_identity\": \"boson-avatar-agent\",\n \"publisher_identity\": \"agent-7f3a\",\n \"type\": \"livekit\",\n \"audio_source\": \"data_stream\"\n },\n \"model\": \"higgs-avatar\",\n \"max_duration_seconds\": 1800\n}"
response = http.request(request)
puts response.read_body{
"id": "avrt_3f9c2a7e8b1d4c6f",
"object": "avatar.realtime.session",
"status": "active",
"model": "higgs-avatar",
"avatar_id": "builtin_claire_v1",
"avatar_identity": "boson-avatar-agent",
"created_at": "2023-11-07T05:31:56Z",
"expires_at": "2023-11-07T05:31:56Z",
"ended_at": "2023-11-07T05:31:56Z"
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>",
"param": "<string>"
}
}Authorizations
Your Boson API key, sent as Authorization: Bearer $BOSON_API_KEY.
Body
application/json
The face to render: a preset or an avatar owned by this API key, from GET /v1/avatars.
Required string length:
1 - 256Example:
"builtin_claire_v1"
The LiveKit room the avatar joins. You own the room and mint the avatar's token with your LiveKit API key and secret.
Show child attributes
Show child attributes
Avatar model ID, the same ID as POST /v1/videos uses. Optional; defaults to higgs-avatar.
Available options:
higgs-avatar Rendered video size in pixels (portrait or square works best). Optional; defaults to 480x640. The reference image is center-cropped to this aspect ratio.
Show child attributes
Show child attributes
Hard cap on the session length; the session ends and the avatar leaves the room when it is reached. Optional; defaults to the account limit (3600 s), which a larger value may not exceed (invalid_duration).
Required range:
1 <= x <= 14400Example:
1800
Response
The session is active and the avatar has joined the room.
A realtime avatar session (the create / retrieve / release response).
Session ID, e.g. avrt_....
Example:
"avrt_3f9c2a7e8b1d4c6f"
Available options:
avatar.realtime.session active: the avatar is in the room. releasing: a release was requested and is not confirmed yet. terminated: the session has ended (released, expired, room emptied, or ended by Boson for another reason).
Available options:
active, releasing, terminated Example:
"higgs-avatar"
Example:
"builtin_claire_v1"
The LiveKit identity the avatar joined as (transport.participant_identity).
Example:
"boson-avatar-agent"
When the avatar joined the room (ISO 8601, UTC).
Latest end time: the session ends at this time if it is still running (created_at + max_duration_seconds).
When the session ended; null while it is active.