Skip to main content
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": {}
}
'
{
  "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"
}
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

​
avatar
string
required
The avatar image to use for this session. Accepts one of three formats:
  • A publicly accessible image URL (e.g. https://example.com/avatar.jpg)
  • A base64-encoded image string (e.g. data:image/jpeg;base64,...)
  • An avatar ID from the Avatar Assets API (e.g. avat_01H3Z8G9YR3K2N5M6P7Q8W4T)
Supported formats: png, jpeg/jpg, gif, webp.Constraints:
  • Minimum size: 200×200 pixels
  • Maximum size: 10 MB
  • URLs must point to a publicly accessible address — private IPs, localhost and internal addresses are blocked
  • The image is fetched and resized server-side before being passed to the avatar pipeline
  • Exactly one human face must be clearly visible in the image
  • The face must occupy a significant portion of the image — full-body shots or photos where the face is a small detail are rejected
​
aspect_ratio
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.
​
room
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 joining
  • token (string, required): Authentication token for the room
  • display_name (string, optional): Display name for the avatar in the room (defaults to “AI Avatar (AH)”)
​
metadata
object
Optional metadata object to attach to the session. Must be a valid JSON object. Defaults to {} if not provided.

​
Response

​
success
boolean
Whether the session was created successfully
​
session
object
The created session object (See Session schema).
​
usage
object
Current usage snapshot (minutes + concurrency) returned by usage enforcement.
​
message
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 {}.
Avatar Face Requirement: The avatar image must contain exactly one human face that is clearly visible and occupies a significant portion of the image. Group photos, full-body shots, illustrations or images with no face will be rejected with a 400 error. Use a portrait or head-and-shoulders photo for best results.

​
Behavior

  • Creates a new session using the provided avatar (URL, base64 or avatar ID)
  • If a URL or avatar ID is provided, the image is fetched server-side, validated and resized (max 800px wide, JPEG at 85% quality) before being passed to the avatar processing pipeline — the URL must be publicly accessible
  • Avatar IDs (avat_xxx) are resolved to signed Cloudinary URLs; user_exclusive avatars are restricted to their owner
  • Face validation is run on every avatar image: the image must contain exactly one clearly visible human face that occupies a prominent portion of the frame — group photos, full-body shots or images with no face are rejected
  • Automatically starts the session (sets started_at timestamp)
  • Allocates a GPU-enabled server for avatar processing
  • Calculates expiration time based on your subscription plan’s session duration limits
  • Returns session_token needed 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"
}