> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agenthuman.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Getting started with the Agent Human API

## 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

<AccordionGroup>
  <Accordion icon="key" title="Generate an API key">
    1. Log in to your [Agent Human Dashboard](https://app.agenthuman.com)
    2. Navigate to [**Settings → API Keys**](https://app.agenthuman.com/settings/apikeys)
    3. Click **"New API Key"**
    4. Name your key (e.g., "Development" or "Production")
    5. Copy and save the key securely - it won't be shown again!

    <Warning>
      API keys are shown only once. Store them securely and never commit to version control.
    </Warning>
  </Accordion>

  <Accordion icon="shield" title="Set up your environment">
    Store your API key as an environment variable:

    **Linux/macOS:**

    ```bash theme={null}
    export AGENTHUMAN_API_KEY="ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    **Windows (PowerShell):**

    ```powershell theme={null}
    $env:AGENTHUMAN_API_KEY="ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    ```

    **Or in a `.env` file:**

    ```env theme={null}
    AGENTHUMAN_API_KEY=ah_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
    ```

    <Tip>
      Using environment variables keeps your API keys secure and out of your source code.
    </Tip>
  </Accordion>
</AccordionGroup>

### Step 2: Create a Session

<CodeGroup>
  ```javascript JavaScript theme={null}
  // 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
  ```

  ```python Python theme={null}
  # 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
  ```

  ```bash cURL theme={null}
  # 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"
      }
    }'
  ```
</CodeGroup>

<Info>
  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.
</Info>

<Note>
  **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.
</Note>

## Core Concepts

<CardGroup cols={2}>
  <Card title="Sessions" icon="video">
    Video conversations with avatars. Lifecycle: **Started** (at creation) → **Ended**. You provide your own Daily or LiveKit room for WebRTC video streaming.
  </Card>

  <Card title="WebRTC Streaming" icon="signal">
    Real-time audio/video communication using Daily or LiveKit infrastructure for low-latency avatar video delivery.
  </Card>
</CardGroup>

### Response Format

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

### Success Responses

<CodeGroup>
  ```json List Response theme={null}
  {
    "success": true,
    "sessions": [
      {
        "session_id": "sess_01H3Z8G9YR3K2N5M6P7Q8W4T",
        "status": "started",
        "created_at": "2024-01-15T10:30:00Z"
      }
    ]
  }
  ```

  ```json Create/Update Response theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

### Error Responses

All errors include helpful messages and optional suggestions:

```json theme={null}
{
  "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...`   |

<Note>
  Resource IDs are **immutable** and **globally unique**. Use them for reliable references across API calls.
</Note>

## 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:

```http theme={null}
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:

```text theme={null}
Too many requests, please slow down.
```

**Headers included:**

```http theme={null}
Retry-After: 60
RateLimit-Reset: 60
```

### Best Practices

<AccordionGroup>
  <Accordion icon="gauge-high" title="Monitor Rate Limit Headers">
    Track `RateLimit-Remaining` in your application and slow down requests when approaching the limit.

    ```javascript theme={null}
    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');
    }
    ```
  </Accordion>

  <Accordion icon="clock-rotate-left" title="Implement Exponential Backoff">
    When you receive a 429 response, wait before retrying with exponentially increasing delays.

    ```javascript theme={null}
    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');
    }
    ```
  </Accordion>

  <Accordion icon="layer-group" title="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
  </Accordion>

  <Accordion icon="database" title="Cache Responses">
    Cache API responses that don't change frequently (session details).

    ```javascript theme={null}
    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;
    }
    ```
  </Accordion>
</AccordionGroup>

### 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

<Warning>
  **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](/api-reference/endpoints/get-usage-summary) to check your current usage.
</Warning>

## Working with the API

### Prerequisites

Before you begin, ensure you have:

* An Agent Human account ([Sign up here](https://app.agenthuman.com))
* Your API key from the dashboard
* An HTTP client library for your language

### SDK & HTTP Clients

Agent Human works with any standard HTTP client:

<AccordionGroup>
  <Accordion icon="js" title="JavaScript/Node.js">
    **Recommended libraries:**

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

    ```bash theme={null}
    npm install axios dotenv
    ```
  </Accordion>

  <Accordion icon="python" title="Python">
    **Recommended libraries:**

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

    ```bash theme={null}
    pip install requests python-dotenv
    ```
  </Accordion>

  <Accordion icon="code" title="Other Languages">
    * **PHP**: Guzzle, cURL
    * **Ruby**: Net::HTTP, HTTParty, Faraday
    * **Go**: net/http, resty
    * **Java**: OkHttp, Apache HttpClient
    * **.NET**: HttpClient, RestSharp
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={2}>
  <Card title="Secure Keys" icon="lock">
    Store API keys in environment variables, never in source code or version control
  </Card>

  <Card title="Handle Errors" icon="triangle-exclamation">
    Check `success` field and handle errors gracefully with retry logic
  </Card>

  <Card title="Respect Limits" icon="gauge-high">
    Monitor rate limit headers and implement exponential backoff
  </Card>

  <Card title="Use HTTPS" icon="shield">
    Always use HTTPS endpoints for secure communication
  </Card>
</CardGroup>

## Common Workflows

<AccordionGroup>
  <Accordion icon="video" title="Complete Session Lifecycle">
    A typical session flow from creation to completion:

    ```javascript theme={null}
    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`);
    ```
  </Accordion>

  <Accordion icon="filter" title="Filter and Monitor Sessions">
    Query sessions with filters and track their status:

    ```python theme={null}
    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']}")
    ```
  </Accordion>

  <Accordion icon="trash" title="Error Handling Pattern">
    Always check the `success` field and handle errors appropriately:

    ```javascript theme={null}
    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;
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to authenticate with API keys
  </Card>

  <Card title="Create Session" icon="video" href="/api-reference/endpoints/create-session">
    Create and start a session with your video room
  </Card>

  <Card title="Making Avatars Talk" icon="signal" href="/api-reference/endpoints/making-avatars-talk">
    Send audio to create talking avatars
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope">
    **[support@agenthuman.com](mailto:support@agenthuman.com)**

    Our team typically responds within 24 hours
  </Card>
</CardGroup>

<Note>
  **Stuck?** Check our detailed [endpoint documentation](/api-reference/endpoints/create-session) or reach out to our support team. We're here to help!
</Note>