Create Session
curl --request POST \
--url https://api.agenthuman.com/v1/sessions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"avatar": "<string>",
"aspect_ratio": "<string>",
"room": {},
"metadata": {}
}
'import requests
url = "https://api.agenthuman.com/v1/sessions"
payload = {
"avatar": "<string>",
"aspect_ratio": "<string>",
"room": {},
"metadata": {}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({avatar: '<string>', aspect_ratio: '<string>', room: {}, metadata: {}})
};
fetch('https://api.agenthuman.com/v1/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.agenthuman.com/v1/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' => '<string>',
'aspect_ratio' => '<string>',
'room' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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.agenthuman.com/v1/sessions"
payload := strings.NewReader("{\n \"avatar\": \"<string>\",\n \"aspect_ratio\": \"<string>\",\n \"room\": {},\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.agenthuman.com/v1/sessions")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"avatar\": \"<string>\",\n \"aspect_ratio\": \"<string>\",\n \"room\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agenthuman.com/v1/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"avatar\": \"<string>\",\n \"aspect_ratio\": \"<string>\",\n \"room\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"session": {
"session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
"status": "started",
"session_token": "session_token_xxxxxxxxxxxxx",
"started_at": "2024-01-15T10:30:00Z",
"ended_at": null,
"expiration": "2024-01-15T14:30:00Z",
"metadata": {
"user_name": "John Doe",
"session_purpose": "Customer Support"
}
},
"usage": {
"concurrency": {
"current": 1,
"max": 1,
"available": 0
},
"minutes": {
"total_remaining": 120
}
},
"message": "Session created successfully"
}
{
"success": false,
"error": {
"message": "Avatar is required",
"suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
}
}
{
"success": false,
"error": {
"message": "Invalid avatar format",
"suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
}
}
{
"success": false,
"error": {
"message": "Avatar image is too small",
"suggestion": "Image must be at least 200x200 pixels"
}
}
{
"success": false,
"error": {
"message": "No face detected in the avatar image",
"suggestion": "Provide a clear photo with one visible face"
}
}
{
"success": false,
"error": {
"message": "2 faces detected in the avatar image",
"suggestion": "The avatar must contain exactly one person"
}
}
{
"success": false,
"error": {
"message": "The face in the avatar image is too small or not clearly visible",
"suggestion": "Use a closer photo where the face is clearly visible and takes up a significant portion of the image"
}
}
{
"success": false,
"error": {
"message": "Avatar image is too large",
"suggestion": "Image must be under 10 MB"
}
}
{
"success": false,
"error": {
"message": "Failed to fetch avatar image from the provided URL",
"suggestion": "Ensure the URL is publicly accessible and points to a valid image"
}
}
{
"success": false,
"error": {
"message": "Avatar URL points to a private or reserved address",
"suggestion": "Provide a publicly accessible URL"
}
}
{
"success": false,
"error": {
"message": "Providing an image URL or base64 requires a paid plan",
"suggestion": "Upload your image first via POST /v1/avatars/upload-face to get an avatar ID (avat_...), or upgrade your plan"
}
}
{
"success": false,
"error": {
"message": "Avatar access denied",
"suggestion": "This avatar is exclusive and does not belong to your account"
}
}
{
"success": false,
"error": {
"message": "Avatar not found",
"suggestion": "The provided avatar ID does not match any avatar"
}
}
{
"success": false,
"error": {
"message": "Invalid aspect ratio",
"suggestion": "Aspect ratio must be one of: 4:3, 3:4, 1:1"
}
}
{
"success": false,
"error": {
"message": "Room must be a valid JSON object",
"suggestion": "Room should be an object like {\"platform\": \"daily\", \"url\": \"https://your-domain.daily.co/your-room-name\", \"token\": \"your-room-token\"}, not an array or primitive"
}
}
{
"success": false,
"error": {
"message": "Invalid room platform",
"suggestion": "Room platform must be one of: daily, livekit"
}
}
{
"success": false,
"error": {
"code": "INSUFFICIENT_MINUTES",
"message": "No minutes remaining. Please purchase additional minutes or upgrade your plan at https://app.agenthuman.com/settings/billing"
}
}
{
"success": false,
"error": {
"code": "CONCURRENCY_LIMIT_EXCEEDED",
"message": "Maximum concurrent sessions (1) reached. You already have 1 session running. Please end an active session before starting a new one."
}
}
Sessions
Create Session
Create and start a new avatar video session
POST
/
v1
/
sessions
Create Session
curl --request POST \
--url https://api.agenthuman.com/v1/sessions \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"avatar": "<string>",
"aspect_ratio": "<string>",
"room": {},
"metadata": {}
}
'import requests
url = "https://api.agenthuman.com/v1/sessions"
payload = {
"avatar": "<string>",
"aspect_ratio": "<string>",
"room": {},
"metadata": {}
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({avatar: '<string>', aspect_ratio: '<string>', room: {}, metadata: {}})
};
fetch('https://api.agenthuman.com/v1/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.agenthuman.com/v1/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' => '<string>',
'aspect_ratio' => '<string>',
'room' => [
],
'metadata' => [
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"x-api-key: <api-key>"
],
]);
$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.agenthuman.com/v1/sessions"
payload := strings.NewReader("{\n \"avatar\": \"<string>\",\n \"aspect_ratio\": \"<string>\",\n \"room\": {},\n \"metadata\": {}\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
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.agenthuman.com/v1/sessions")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"avatar\": \"<string>\",\n \"aspect_ratio\": \"<string>\",\n \"room\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.agenthuman.com/v1/sessions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"avatar\": \"<string>\",\n \"aspect_ratio\": \"<string>\",\n \"room\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"session": {
"session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
"status": "started",
"session_token": "session_token_xxxxxxxxxxxxx",
"started_at": "2024-01-15T10:30:00Z",
"ended_at": null,
"expiration": "2024-01-15T14:30:00Z",
"metadata": {
"user_name": "John Doe",
"session_purpose": "Customer Support"
}
},
"usage": {
"concurrency": {
"current": 1,
"max": 1,
"available": 0
},
"minutes": {
"total_remaining": 120
}
},
"message": "Session created successfully"
}
{
"success": false,
"error": {
"message": "Avatar is required",
"suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
}
}
{
"success": false,
"error": {
"message": "Invalid avatar format",
"suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
}
}
{
"success": false,
"error": {
"message": "Avatar image is too small",
"suggestion": "Image must be at least 200x200 pixels"
}
}
{
"success": false,
"error": {
"message": "No face detected in the avatar image",
"suggestion": "Provide a clear photo with one visible face"
}
}
{
"success": false,
"error": {
"message": "2 faces detected in the avatar image",
"suggestion": "The avatar must contain exactly one person"
}
}
{
"success": false,
"error": {
"message": "The face in the avatar image is too small or not clearly visible",
"suggestion": "Use a closer photo where the face is clearly visible and takes up a significant portion of the image"
}
}
{
"success": false,
"error": {
"message": "Avatar image is too large",
"suggestion": "Image must be under 10 MB"
}
}
{
"success": false,
"error": {
"message": "Failed to fetch avatar image from the provided URL",
"suggestion": "Ensure the URL is publicly accessible and points to a valid image"
}
}
{
"success": false,
"error": {
"message": "Avatar URL points to a private or reserved address",
"suggestion": "Provide a publicly accessible URL"
}
}
{
"success": false,
"error": {
"message": "Providing an image URL or base64 requires a paid plan",
"suggestion": "Upload your image first via POST /v1/avatars/upload-face to get an avatar ID (avat_...), or upgrade your plan"
}
}
{
"success": false,
"error": {
"message": "Avatar access denied",
"suggestion": "This avatar is exclusive and does not belong to your account"
}
}
{
"success": false,
"error": {
"message": "Avatar not found",
"suggestion": "The provided avatar ID does not match any avatar"
}
}
{
"success": false,
"error": {
"message": "Invalid aspect ratio",
"suggestion": "Aspect ratio must be one of: 4:3, 3:4, 1:1"
}
}
{
"success": false,
"error": {
"message": "Room must be a valid JSON object",
"suggestion": "Room should be an object like {\"platform\": \"daily\", \"url\": \"https://your-domain.daily.co/your-room-name\", \"token\": \"your-room-token\"}, not an array or primitive"
}
}
{
"success": false,
"error": {
"message": "Invalid room platform",
"suggestion": "Room platform must be one of: daily, livekit"
}
}
{
"success": false,
"error": {
"code": "INSUFFICIENT_MINUTES",
"message": "No minutes remaining. Please purchase additional minutes or upgrade your plan at https://app.agenthuman.com/settings/billing"
}
}
{
"success": false,
"error": {
"code": "CONCURRENCY_LIMIT_EXCEEDED",
"message": "Maximum concurrent sessions (1) reached. You already have 1 session running. Please end an active session before starting a new one."
}
}
What This Does: Creates and automatically starts a session with a video room where your avatar will appear. The session is immediately set to
started status and a server is allocated to run the avatar.Body
string
required
The avatar to use for this session. Accepts one of three formats:Recommended: An avatar ID returned by the Upload Face endpoint (e.g.
avat_01H3Z8G9YR3K2N5M6P7Q8W4T). This is the fastest and most reliable option — the avatar has already been validated, aligned and stored, so the session starts immediately.Accepted (paid plans only):- A publicly accessible image URL (e.g.
https://example.com/photo.jpg) - A base64-encoded image string (e.g.
data:image/jpeg;base64,...)
string
Video aspect ratio for the session. Must be one of:
4:3, 3:4 or 1:1. Defaults to 4:3 if not provided.object
required
Video room configuration object with the following fields:
platform(string, required): Room platform - must be “daily” or “livekit”url(string, required): Room URL for joiningtoken(string, required): Authentication token for the room
object
Optional metadata object to attach to the session. Must be a valid JSON object. Defaults to
{} if not provided.Response
boolean
Whether the session was created successfully
object
The created session object (See Session schema).
object
Current usage snapshot (minutes + concurrency) returned by usage enforcement.
string
Success message
Important Notes
Session Lifecycle: Creating a session automatically starts it. The session is created with
started_at set to the current timestamp and a server is immediately allocated to run the avatar. You do not need to call a separate “Start Session” endpoint.Video Room Integration: You must provide your own video room (Daily or LiveKit) configuration in the
room parameter. The API will use this configuration to connect the avatar server to your video room.Metadata Validation: The
metadata field must be a valid JSON object (e.g., {"key": "value"}). Arrays, strings, numbers, booleans or null values will be rejected with a 400 error. If not provided, it defaults to an empty object {}.Use Avatar IDs for best performance: When passing a URL or base64 image, the server runs the full upload-face pipeline (face detection + alignment + upload) before starting the session, which adds latency. For production use, call POST /v1/avatars/upload-face once to get an
avat_... ID and pass that ID to all subsequent session requests.Avatar Face Requirement (URL / base64 inputs): The image must contain exactly one human face that is clearly visible and occupies a significant portion of the frame. Group photos, full-body shots, illustrations or images with no face will be rejected. Use a portrait or head-and-shoulders photo.
Behavior
- Creates a new session using the provided avatar
- Avatar ID (
avat_...): resolved directly to its stored image — no extra processing. Avatars tagged asuser_exclusiveare restricted to the account that uploaded them - URL or base64 (paid plans only): the image is automatically processed through the Upload Face pipeline — face detection (exactly one prominent face required), face alignment, and upload to storage — before the session is created. Any validation error from this pipeline is returned as a session creation error. For best latency, call Upload Face separately in advance and pass the returned avatar ID here
- Free plan: only avatar IDs are accepted; URL and base64 inputs are rejected with a
403error - Automatically starts the session (sets
started_attimestamp) - Allocates a GPU-enabled server for avatar processing
- Calculates expiration time based on your subscription plan’s session duration limits
- Returns
session_tokenneeded for internal server authentication - Validates room platform is “daily” or “livekit”
- Defaults aspect ratio to “4:3” if not provided, validates it’s one of: “4:3”, “3:4” or “1:1”
- Metadata defaults to
{}and must be a valid JSON object - Session IDs are prefixed with
sess_ - Enforces subscription usage limits (minutes remaining, concurrent session limits)
Use Cases
- Create and start a session with your own Daily or LiveKit room
- Set up sessions with custom metadata for tracking
- Initialize avatar sessions programmatically
- Start avatar conversations with specific aspect ratios for different devices
{
"success": true,
"session": {
"session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
"status": "started",
"session_token": "session_token_xxxxxxxxxxxxx",
"started_at": "2024-01-15T10:30:00Z",
"ended_at": null,
"expiration": "2024-01-15T14:30:00Z",
"metadata": {
"user_name": "John Doe",
"session_purpose": "Customer Support"
}
},
"usage": {
"concurrency": {
"current": 1,
"max": 1,
"available": 0
},
"minutes": {
"total_remaining": 120
}
},
"message": "Session created successfully"
}
{
"success": false,
"error": {
"message": "Avatar is required",
"suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
}
}
{
"success": false,
"error": {
"message": "Invalid avatar format",
"suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
}
}
{
"success": false,
"error": {
"message": "Avatar image is too small",
"suggestion": "Image must be at least 200x200 pixels"
}
}
{
"success": false,
"error": {
"message": "No face detected in the avatar image",
"suggestion": "Provide a clear photo with one visible face"
}
}
{
"success": false,
"error": {
"message": "2 faces detected in the avatar image",
"suggestion": "The avatar must contain exactly one person"
}
}
{
"success": false,
"error": {
"message": "The face in the avatar image is too small or not clearly visible",
"suggestion": "Use a closer photo where the face is clearly visible and takes up a significant portion of the image"
}
}
{
"success": false,
"error": {
"message": "Avatar image is too large",
"suggestion": "Image must be under 10 MB"
}
}
{
"success": false,
"error": {
"message": "Failed to fetch avatar image from the provided URL",
"suggestion": "Ensure the URL is publicly accessible and points to a valid image"
}
}
{
"success": false,
"error": {
"message": "Avatar URL points to a private or reserved address",
"suggestion": "Provide a publicly accessible URL"
}
}
{
"success": false,
"error": {
"message": "Providing an image URL or base64 requires a paid plan",
"suggestion": "Upload your image first via POST /v1/avatars/upload-face to get an avatar ID (avat_...), or upgrade your plan"
}
}
{
"success": false,
"error": {
"message": "Avatar access denied",
"suggestion": "This avatar is exclusive and does not belong to your account"
}
}
{
"success": false,
"error": {
"message": "Avatar not found",
"suggestion": "The provided avatar ID does not match any avatar"
}
}
{
"success": false,
"error": {
"message": "Invalid aspect ratio",
"suggestion": "Aspect ratio must be one of: 4:3, 3:4, 1:1"
}
}
{
"success": false,
"error": {
"message": "Room must be a valid JSON object",
"suggestion": "Room should be an object like {\"platform\": \"daily\", \"url\": \"https://your-domain.daily.co/your-room-name\", \"token\": \"your-room-token\"}, not an array or primitive"
}
}
{
"success": false,
"error": {
"message": "Invalid room platform",
"suggestion": "Room platform must be one of: daily, livekit"
}
}
{
"success": false,
"error": {
"code": "INSUFFICIENT_MINUTES",
"message": "No minutes remaining. Please purchase additional minutes or upgrade your plan at https://app.agenthuman.com/settings/billing"
}
}
{
"success": false,
"error": {
"code": "CONCURRENCY_LIMIT_EXCEEDED",
"message": "Maximum concurrent sessions (1) reached. You already have 1 session running. Please end an active session before starting a new one."
}
}