Skip to main content
POST
/
v1
/
links
/
start-session
Start Session via Link
curl --request POST \
  --url https://api.agenthuman.com/v1/links/start-session \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "link_id": "<string>",
  "aspect_ratio": "<string>"
}
'
{
  "success": true,
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "livekit_url": "wss://your-instance.livekit.cloud",
  "participant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agent_identity": "agenthuman-avatar-agent"
}
What This Does: Starts a live avatar session using a shareable link ID as the authentication token. A LiveKit room is created automatically and the caller receives the connection details needed to join it. This endpoint is designed for public-facing frontends (e.g. embedded room pages) where no API key is available.
No API key required. The link_id itself acts as the credential. Keep your link IDs private if you want to control access or use use_limit and expires_at when creating the link to restrict usage.

​
Body

​
link_id
string
required
The ID of the link to use (starts with lnk_). The link must be active, not expired and within its usage limit. The link’s associated agent must have an avatar_image_url configured.
​
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 or invalid.

​
Response

​
success
boolean
Whether the session was started successfully.
​
session_id
string
The ID of the created session (prefixed with sess_).
​
livekit_url
string
The LiveKit server WebSocket URL to connect to (e.g. wss://your-instance.livekit.cloud).
​
participant_token
string
A signed LiveKit JWT token for the end user to join the room. Pass this to the LiveKit client SDK (Room.connect(livekit_url, participant_token)).
​
agent_identity
string
The LiveKit participant identity of the avatar agent (e.g. agenthuman-avatar-agent). Useful for identifying which participant is the AI avatar in the room.

​
Behavior

  • Validates the link_id: must exist, be active, not past expires_at and within use_limit
  • Looks up the linked agent and uses its avatar_image_url as the avatar for the session
  • Checks the link owner’s subscription quota (concurrency limit and minutes remaining) before proceeding
  • Creates a new LiveKit room with a unique name
  • Mints two tokens: one for the avatar agent (server-side, used internally), one for the end user (returned in the response)
  • Processes and validates the avatar image (face detection, size checks)
  • Creates a session record and allocates a GPU server to run the avatar
  • Increments the link’s uses counter
  • Sessions created via links count against the link owner’s usage quota

​
Use Cases

  • Embedding a shareable agent room in a public webpage
  • Letting external users start a session without exposing your API key
  • Building a link-based demo or support widget
{
  "success": true,
  "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
  "livekit_url": "wss://your-instance.livekit.cloud",
  "participant_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "agent_identity": "agenthuman-avatar-agent"
}