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 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,...)
When a URL or base64 string is provided, the image is automatically processed through the same pipeline as Upload Face: face detection, alignment and upload to storage. The resulting avatar ID is then used for the session. This adds processing time to the request. Free plan users must always provide an avatar ID.
​
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
​
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 {}.
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 as user_exclusive are 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 403 error
  • 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"
}