Skip to main content
PUT
https://api.agenthuman.com
/
v1
/
sessions
/
{session_id}
/
start
Start Session
curl --request PUT \
  --url https://api.agenthuman.com/v1/sessions/{session_id}/start \
  --header 'x-api-key: <api-key>'
{
  "success": true,
  "ws_uri": "try_again",
  "expiration": "2024-01-15T14:35:00Z",
  "message": "Session started successfully"
}
What This Does: Allocates a GPU-enabled server for your session and activates the avatar. Returns the WebSocket URI where you’ll send audio commands. The avatar server will join your Daily.co room automatically.

​
Path Parameters

​
session_id
string
required
The ID of the session to start

​
Response

​
success
boolean
Whether the session was started successfully
​
ws_uri
string
WebSocket URI for sending audio commands to the avatar server
​
expiration
string | null
ISO 8601 timestamp when session will expire (based on subscription plan limits). Null for unlimited sessions.
​
message
string
Success message

​
Important Notes

Session State: Only sessions in created status can be started. Once started, the session transitions to started status and begins consuming your subscription’s session time.
Server Assignment: Starting a session triggers server allocation for video processing. This may take a few seconds while a GPU-enabled server is assigned to your session. The ws_uri may initially return as try_again while the server starts up.
Subscription Limits: Session expiration time is determined by your subscription plan:
  • Free Plan: Limited session duration
  • Paid Plans: Extended or unlimited session duration

​
Behavior

  • Validates that the session exists and belongs to the authenticated user
  • If the session is already started, returns the existing ws_uri (safe retry)
  • Rejects sessions that have already ended
  • Assigns a video processing server (RunPod serverless or local)
  • Sets started_at timestamp
  • Calculates and sets expiration timestamp based on subscription plan
  • Returns ws_uri for sending audio commands
  • Session status transitions from created to started

​
Use Cases

  • Start a session before connecting to Daily.co room
  • Activate a pre-created session for immediate use
  • Begin consuming subscription session time

​
Idempotency

If you call start on an already-started session, the API will return the existing ws_uri without error, allowing safe retries. 
{
  "success": true,
  "ws_uri": "try_again",
  "expiration": "2024-01-15T14:35:00Z",
  "message": "Session started successfully"
}

​
Server Assignment Process

When you start a session:
  1. Server Request: API requests a GPU-enabled server from the pool
  2. Allocation: A server is assigned to your session (may take 5-10 seconds)
  3. Initialization: Server loads the avatar model and prepares for video generation
  4. Ready: ws_uri is provided for sending audio commands
Production Tip: If ws_uri is try_again, wait a moment and call Start Session again. This endpoint is idempotent and will return the real WebSocket URI once the server updates it.

​
Next Steps

After starting a session:
  1. Connect to the Daily.co room using daily_room.url and daily_room.token from the session object
  2. Use the ws_uri to connect to WebSocket for sending audio commands
  3. Send audio via WebSocket for avatar video generation
  4. End the session when done using End Session