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

# Create Session

> Create and start a new avatar video session

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

### Body

<ParamField body="avatar" type="string" required>
  The avatar to use for this session. Accepts one of three formats:

  **Recommended:** An avatar ID returned by the [Upload Face](/api-reference/endpoints/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](/api-reference/endpoints/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.**
</ParamField>

<ParamField body="aspect_ratio" type="string" optional>
  Video aspect ratio for the session. Must be one of: `4:3`, `3:4` or `1:1`. Defaults to `4:3` if not provided.
</ParamField>

<ParamField body="room" type="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
</ParamField>

<ParamField body="metadata" type="object" optional>
  Optional metadata object to attach to the session. Must be a valid JSON object. Defaults to `{}` if not provided.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Whether the session was created successfully
</ResponseField>

<ResponseField name="session" type="object">
  The created session object (See [Session schema](/api-reference/schemas/session)).
</ResponseField>

<ResponseField name="usage" type="object">
  Current usage snapshot (minutes + concurrency) returned by usage enforcement.
</ResponseField>

<ResponseField name="message" type="string">
  Success message
</ResponseField>

### Important Notes

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

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

<Warning>
  **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 `{}`.
</Warning>

<Warning>
  **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](/api-reference/endpoints/upload-face) once to get an `avat_...` ID and pass that ID to all subsequent session requests.
</Warning>

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

### 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](/api-reference/endpoints/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](/api-reference/endpoints/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

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

  ```json 400 - Missing Avatar theme={null}
  {
    "success": false,
    "error": {
      "message": "Avatar is required",
      "suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
    }
  }
  ```

  ```json 400 - Invalid Avatar Format theme={null}
  {
    "success": false,
    "error": {
      "message": "Invalid avatar format",
      "suggestion": "Provide an avatar ID (avat_...), a URL (https://...), or a base64-encoded image string (data:image/...;base64,...)"
    }
  }
  ```

  ```json 400 - Avatar Too Small theme={null}
  {
    "success": false,
    "error": {
      "message": "Avatar image is too small",
      "suggestion": "Image must be at least 200x200 pixels"
    }
  }
  ```

  ```json 400 - No Face Detected theme={null}
  {
    "success": false,
    "error": {
      "message": "No face detected in the avatar image",
      "suggestion": "Provide a clear photo with one visible face"
    }
  }
  ```

  ```json 400 - Multiple Faces Detected theme={null}
  {
    "success": false,
    "error": {
      "message": "2 faces detected in the avatar image",
      "suggestion": "The avatar must contain exactly one person"
    }
  }
  ```

  ```json 400 - Face Too Small theme={null}
  {
    "success": false,
    "error": {
      "message": "The face in the avatar image is too small or not clearly visible",
      "suggestion": "Use a closer photo where the face is clearly visible and takes up a significant portion of the image"
    }
  }
  ```

  ```json 400 - Avatar Too Large theme={null}
  {
    "success": false,
    "error": {
      "message": "Avatar image is too large",
      "suggestion": "Image must be under 10 MB"
    }
  }
  ```

  ```json 400 - Avatar URL Not Accessible theme={null}
  {
    "success": false,
    "error": {
      "message": "Failed to fetch avatar image from the provided URL",
      "suggestion": "Ensure the URL is publicly accessible and points to a valid image"
    }
  }
  ```

  ```json 400 - Avatar URL Private Address theme={null}
  {
    "success": false,
    "error": {
      "message": "Avatar URL points to a private or reserved address",
      "suggestion": "Provide a publicly accessible URL"
    }
  }
  ```

  ```json 403 - Free Plan: Avatar ID Required theme={null}
  {
    "success": false,
    "error": {
      "message": "Providing an image URL or base64 requires a paid plan",
      "suggestion": "Upload your image first via POST /v1/avatars/upload-face to get an avatar ID (avat_...), or upgrade your plan"
    }
  }
  ```

  ```json 403 - Avatar Access Denied theme={null}
  {
    "success": false,
    "error": {
      "message": "Avatar access denied",
      "suggestion": "This avatar is exclusive and does not belong to your account"
    }
  }
  ```

  ```json 404 - Avatar ID Not Found theme={null}
  {
    "success": false,
    "error": {
      "message": "Avatar not found",
      "suggestion": "The provided avatar ID does not match any avatar"
    }
  }
  ```

  ```json 400 - Invalid Aspect Ratio theme={null}
  {
    "success": false,
    "error": {
      "message": "Invalid aspect ratio",
      "suggestion": "Aspect ratio must be one of: 4:3, 3:4, 1:1"
    }
  }
  ```

  ```json 400 - Invalid Room theme={null}
  {
    "success": false,
    "error": {
      "message": "Room must be a valid JSON object",
      "suggestion": "Room should be an object like {\"platform\": \"daily\", \"url\": \"https://your-domain.daily.co/your-room-name\", \"token\": \"your-room-token\"}, not an array or primitive"
    }
  }
  ```

  ```json 400 - Invalid Room Platform theme={null}
  {
    "success": false,
    "error": {
      "message": "Invalid room platform",
      "suggestion": "Room platform must be one of: daily, livekit"
    }
  }
  ```

  ```json 402 - Insufficient Minutes theme={null}
  {
    "success": false,
    "error": {
      "code": "INSUFFICIENT_MINUTES",
      "message": "No minutes remaining. Please purchase additional minutes or upgrade your plan at https://app.agenthuman.com/settings/billing"
    }
  }
  ```

  ```json 429 - Concurrency Limit Exceeded theme={null}
  {
    "success": false,
    "error": {
      "code": "CONCURRENCY_LIMIT_EXCEEDED",
      "message": "Maximum concurrent sessions (1) reached. You already have 1 session running. Please end an active session before starting a new one."
    }
  }
  ```
</ResponseExample>