Introduction - Documentation

Welcome to Agent Human API

Transform your applications with AI-powered video avatars that respond in real-time. Agent Human provides a simple REST API to generate lifelike talking head videos from audio, perfect for customer service, virtual assistants, education and more. Architecture: We handle the complexity of real-time video generation using GPU-accelerated processing, while your chosen video platform (Daily or LiveKit) manages WebRTC streaming for you. Just send audio commands and receive professional avatar video.

Base URL

All API requests should be made to:

https://api.agenthuman.com

What You Can Build

The Agent Human API enables you to:

Create Interactive Sessions - Start WebRTC video sessions with AI avatars using Daily or LiveKit infrastructure
Real-time Video Generation - Send audio and receive synchronized talking head video
Track Analytics - Monitor session duration, status and usage metrics

Quick Start

Get started in minutes:

Step 1: Get Your API Key

Generate an API key

Log in to your Agent Human Dashboard
Navigate to Settings → API Keys
Click “New API Key”
Name your key (e.g., “Development” or “Production”)
Copy and save the key securely - it won’t be shown again!

API keys are shown only once. Store them securely and never commit to version control.

Set up your environment

Store your API key as an environment variable:Linux/macOS:

export AGENTHUMAN_API_KEY="ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Windows (PowerShell):

$env:AGENTHUMAN_API_KEY="ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Or in a .env file:

AGENTHUMAN_API_KEY=ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Using environment variables keeps your API keys secure and out of your source code.

Step 2: Create a Session

// Create a new video session
// Note: You must provide your own Daily.co or LiveKit room configuration
const sessionResponse = await fetch('https://api.agenthuman.com/v1/sessions', {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    avatar: 'https://example.com/avatar.jpg', // URL or base64 image (data:image/...;base64,...)
    aspect_ratio: '4:3', // Options: '4:3', '3:4', '1:1'
    room: {
      platform: 'daily', // or 'livekit'
      url: 'https://your-domain.daily.co/your-room',
      token: 'your-daily-token'
    },
    metadata: {
      user_name: 'John Doe',
      purpose: 'Demo session'
    }
  })
});

const { success, session, message } = await sessionResponse.json();
console.log(message); // "Session created successfully"
console.log(`Session ID: ${session.session_id}`);
console.log(`Status: ${session.status}`); // "started"
console.log(`Access Token: ${session.session_token}`);

// Session is now started and avatar server is allocated

# Create a new video session
# Note: You must provide your own Daily.co or LiveKit room configuration
response = requests.post(
  'https://api.agenthuman.com/v1/sessions',
  headers={
    'x-api-key': API_KEY,
    'Content-Type': 'application/json'
  },
  json={
    'avatar': 'https://example.com/avatar.jpg',  # URL or base64 image (data:image/...;base64,...)
    'aspect_ratio': '4:3',  # Options: '4:3', '3:4', '1:1'
    'room': {
      'platform': 'daily',  # or 'livekit'
      'url': 'https://your-domain.daily.co/your-room',
      'token': 'your-daily-token'
    },
    'metadata': {
      'user_name': 'John Doe',
      'purpose': 'Demo session'
    }
  }
)

data = response.json()
session = data['session']
print(data['message'])  # "Session created successfully"
print(f"Session ID: {session['session_id']}")
print(f"Status: {session['status']}")  # "started"
print(f"Access Token: {session['session_token']}")

# Session is now started and avatar server is allocated

# Create a session with your avatar ID
curl -X POST https://api.agenthuman.com/v1/sessions \
  -H "x-api-key: $AGENTHUMAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "avatar": "https://example.com/avatar.jpg",
    "aspect_ratio": "4:3",
    "room": {
      "platform": "daily",
      "url": "https://your-domain.daily.co/your-room",
      "token": "your-daily-token"
    },
    "metadata": {
      "user_name": "John Doe",
      "purpose": "Demo session"
    }
  }'

Sessions are automatically started when created. The session is created with started status and a GPU-enabled server is immediately allocated to run the avatar.

Video Room Setup: You must provide your own Daily.co or LiveKit room configuration in the room parameter. The API will connect the avatar server to your video room.

Core Concepts

Sessions

Video conversations with avatars. Lifecycle: Started (at creation) → Ended. You provide your own Daily or LiveKit room for WebRTC video streaming.

WebRTC Streaming

Real-time audio/video communication using Daily or LiveKit infrastructure for low-latency avatar video delivery.

Response Format

Most /v1/* API responses include a success field. Authentication and some middleware responses may instead return an error string.

Success Responses

{
  "success": true,
  "sessions": [
    {
      "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
      "status": "started",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

{
  "success": true,
  "session": {
    "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
    "status": "created",
    "session_token": "session_token_xxxxx",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "message": "Session created successfully"
}

Error Responses

All errors include helpful messages and optional suggestions:

{
  "success": false,
  "error": {
    "message": "Invalid avatar format",
    "suggestion": "Provide a URL (https://...) or a base64-encoded image string (data:image/...;base64,...)"
  }
}

Resource IDs

All resources use prefixed IDs for easy identification:

Resource	Prefix	Example
Sessions	`sess_`	`sess_01H3Z8G9YR3K2N5M6P7Q8W4T`
API Keys	`ah_live_` / `ah_test_`	`ah_live_1234567890abcdef...`

Resource IDs are immutable and globally unique. Use them for reliable references across API calls.

HTTP Status Codes

Status Code	Description
`200`	Success - Request completed successfully
`201`	Created - Resource created successfully
`400`	Bad Request - Invalid request parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource does not exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error - Server error
`503`	Service Unavailable - Service temporarily offline

Rate Limiting

Agent Human implements rate limiting to ensure fair usage and system stability. Limits apply per API key.

Rate Limits by Endpoint Type

Endpoint Type	Limit	Window	HTTP Status
Read Operations (GET)	300 requests	1 minute	429
Write Operations (POST, PUT, DELETE)	60 requests	1 minute	429
Session Start	150 requests	1 minute	429

Rate Limit Headers

Every API response includes rate limit information in the headers:

RateLimit-Limit: 300
RateLimit-Remaining: 285
RateLimit-Reset: 12

Header	Description
`RateLimit-Limit`	Maximum requests allowed in the current window
`RateLimit-Remaining`	Requests remaining in the current window
`RateLimit-Reset`	Seconds until the current window resets

When Rate Limited

Response (429 Too Many Requests): You may receive a 429 response with a simple message body, for example:

Too many requests, please slow down.

Headers included:

Retry-After: 60
RateLimit-Reset: 60

Best Practices

Monitor Rate Limit Headers

Track RateLimit-Remaining in your application and slow down requests when approaching the limit.

const response = await fetch('https://api.agenthuman.com/v1/sessions', {
  headers: { 'x-api-key': API_KEY }
});

const remaining = response.headers.get('RateLimit-Remaining');
if (parseInt(remaining) < 10) {
  console.warn('Approaching rate limit, consider slowing down');
}

Implement Exponential Backoff

When you receive a 429 response, wait before retrying with exponentially increasing delays.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status !== 429) {
      return response;
    }
    
    // Exponential backoff: 1s, 2s, 4s, etc.
    const delay = Math.pow(2, i) * 1000;
    await new Promise(resolve => setTimeout(resolve, delay));
  }
  
  throw new Error('Max retries exceeded');
}

Batch Requests When Possible

Instead of making multiple individual requests, batch operations where the API supports it.

Use GET /v1/sessions to fetch all sessions at once instead of individual requests
Cache session data locally to reduce API calls

Cache Responses

Cache API responses that don’t change frequently (session details).

const cache = new Map();
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes

async function getCachedSession(sessionId) {
  const cached = cache.get(sessionId);
  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }
  
  const response = await fetch(`https://api.agenthuman.com/v1/sessions/${sessionId}`, {
    headers: { 'x-api-key': API_KEY }
  });
  const data = await response.json();
  
  cache.set(sessionId, { data, timestamp: Date.now() });
  return data;
}

Rate Limit Scope

Rate limits are applied per API key, meaning:

Different API keys have independent rate limits
Test and production keys have separate quotas
Team members with different keys don’t share limits

Session Limits: In addition to API rate limits, your subscription plan has limits on:

Concurrent sessions: How many avatar sessions you can run simultaneously (e.g., Free: 2, Explorer: 5, Growth: 10, Pro: 20)
Total session time: Monthly minutes included in your plan

These limits are separate from API request rate limits. See the Usage endpoint to check your current usage.

Working with the API

Prerequisites

Before you begin, ensure you have:

An Agent Human account (Sign up here)
Your API key from the dashboard
An HTTP client library for your language

SDK & HTTP Clients

Agent Human works with any standard HTTP client:

JavaScript/Node.js

Recommended libraries:

fetch (built-in in Node.js 18+)
axios - Full-featured HTTP client
node-fetch - Node.js implementation of fetch

npm install axios dotenv

Python

Recommended libraries:

requests - Simple and elegant HTTP library
httpx - Modern async-capable HTTP client
aiohttp - Async HTTP client/server

pip install requests python-dotenv

Other Languages

PHP: Guzzle, cURL
Ruby: Net::HTTP, HTTParty, Faraday
Go: net/http, resty
Java: OkHttp, Apache HttpClient
.NET: HttpClient, RestSharp

Best Practices

Secure Keys

Store API keys in environment variables, never in source code or version control

Handle Errors

Check success field and handle errors gracefully with retry logic

Respect Limits

Monitor rate limit headers and implement exponential backoff

Use HTTPS

Always use HTTPS endpoints for secure communication

Common Workflows

Complete Session Lifecycle

A typical session flow from creation to completion:

const headers = { 'x-api-key': API_KEY };

// 1. Create and start a session (happens in one step)
const createRes = await fetch('https://api.agenthuman.com/v1/sessions', {
  method: 'POST',
  headers: { ...headers, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    avatar: 'https://example.com/avatar.jpg', // URL or base64 image
    aspect_ratio: '4:3',
    room: {
      platform: 'daily',
      url: 'https://your-domain.daily.co/your-room',
      token: 'your-daily-token'
    },
    metadata: { user_id: 'user_123' }
  })
});
const { session } = await createRes.json();
console.log(`Session started: ${session.session_id}`);

// 2. Connect to your video room (Daily or LiveKit) for WebRTC video
// Use session.room.url and session.room.token

// 3. End the session when done
const endRes = await fetch(
  `https://api.agenthuman.com/v1/sessions/${session.session_id}/end`,
  {
    method: 'POST',
    headers: { 'x-api-key': API_KEY }
  }
);
const { session: endedSession } = await endRes.json();
console.log(`Session duration: ${endedSession.duration} seconds`);

Filter and Monitor Sessions

Query sessions with filters and track their status:

import requests

API_KEY = os.getenv('AGENTHUMAN_API_KEY')
headers = {'x-api-key': API_KEY}

# Get all active sessions
active_res = requests.get(
  'https://api.agenthuman.com/v1/sessions?status=started',
  headers=headers
)
active_sessions = active_res.json()['sessions']
print(f"Active sessions: {len(active_sessions)}")

# Get detailed info for a specific session
session_res = requests.get(
  f'https://api.agenthuman.com/v1/sessions/{session_id}',
  headers=headers
)
session_details = session_res.json()['session']
print(f"Session status: {session_details['status']}")

Error Handling Pattern

Always check the success field and handle errors appropriately:

async function createSessionSafely(avatar) {
  try {
    const response = await fetch('https://api.agenthuman.com/v1/sessions', {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ avatar })
    });
    
    const data = await response.json();
    
    // Most /v1 endpoints return { success: boolean, ... }, but auth/middleware
    // failures may return { error: string }.
    if (!response.ok || data.success === false) {
      const errorMessage =
        typeof data.error === 'string'
          ? data.error
          : data.error?.message || data.error || 'Request failed';

      console.error('API Error:', errorMessage);

      const suggestion = typeof data.error === 'object' ? data.error?.suggestion : undefined;
      if (suggestion) console.log('Suggestion:', suggestion);

      return null;
    }
    
    return data.session;
  } catch (error) {
    // Handle network error
    console.error('Network error:', error.message);
    return null;
  }
}

Next Steps

Authentication

Learn how to authenticate with API keys

Create Session

Create and start a session with your video room

Making Avatars Talk

Send audio to create talking avatars

Need Help?

Email Support

support@agenthuman.comOur team typically responds within 24 hours

Stuck? Check our detailed endpoint documentation or reach out to our support team. We’re here to help!

​Welcome to Agent Human API

​Base URL

​What You Can Build

​Quick Start

​Step 1: Get Your API Key

​Step 2: Create a Session

​Core Concepts

Sessions

WebRTC Streaming

​Response Format

​Success Responses

​Error Responses

​Resource IDs

​HTTP Status Codes

​Rate Limiting

​Rate Limits by Endpoint Type

​Rate Limit Headers

​When Rate Limited

​Best Practices

​Rate Limit Scope

​Working with the API

​Prerequisites

​SDK & HTTP Clients

​Best Practices

Secure Keys

Handle Errors

Respect Limits

Use HTTPS

​Common Workflows

​Next Steps

Authentication

Create Session

Making Avatars Talk

​Need Help?

Email Support

Welcome to Agent Human API

Base URL

What You Can Build

Quick Start

Step 1: Get Your API Key

Step 2: Create a Session

Core Concepts

Response Format

Success Responses

Error Responses

Resource IDs

HTTP Status Codes

Rate Limiting

Rate Limits by Endpoint Type

Rate Limit Headers

When Rate Limited

Best Practices

Rate Limit Scope

Working with the API

Prerequisites

SDK & HTTP Clients

Best Practices

Common Workflows

Next Steps

Need Help?