> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trugen.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Start a Vision Session
> Attach Hawkeye-1 to any LiveKit room and start real-time video analysis with the modules you choose.
`POST /v2/vision` starts a new Hawkeye session on a LiveKit room you already have. Hawkeye joins as a subscriber, analyses the target participant's video, and streams alerts to your callback URL whenever a class is detected.
Billing is a flat **1¢ per minute** per session. Sessions stop automatically once `max_duration` (in minutes) is reached.
## Endpoint
```bash theme={null}
POST https://api.trugen.ai/v2/vision
Header: x-api-key:
Content-Type: application/json
```
## Request
For each module, you only pick the **classes** you care about. Everything else — evaluation frequency, thresholds — is set to sensible defaults server-side.
```json theme={null}
{
"livekit_url": "wss://your-livekit-domain.livekit.cloud",
"access_token": "eyJhbGciOi...",
"participant": "auto",
"callback_url": "wss://your-callback-endpoint.example.com/vision",
"max_duration": 10,
"modules": {
"face_pose_detection": ["Looking Left", "Looking Right"],
"emotion_recognition": ["angry", "sad", "disgust", "fear", "happy", "surprise", "neutral"],
"eyegaze_tracking": ["Looking left", "Looking right"],
"face_count": ["2"],
"face_out_of_focus": ["out_of_frame"]
}
}
```
### Top-level fields
| Field | Required | Description |
| -------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `livekit_url` | ✅ | `wss://` URL of the LiveKit room Hawkeye should join. |
| `access_token` | ✅ | LiveKit access token with `roomJoin: true` for that room. Hawkeye connects with this identity. |
| `participant` | ➖ | Identity of the participant to analyse. Defaults to `"auto"` — Hawkeye picks the first non-agent participant in the room. Pass a specific LiveKit identity to lock analysis onto that participant instead. |
| `callback_url` | ➖ | WebSocket URL to receive real-time alerts. Omit if you only intend to poll the [Get Session Status](/docs/agents/vision/session-status) endpoint. |
| `max_duration` | ✅ | Hard cap in **minutes**. Hawkeye disconnects when reached. |
| `modules` | ➖ | Modules to enable, keyed by module name. Each value is a list of class names to alert on. Omit `modules` entirely for all modules with all default classes. |
### Rules of thumb
* **Skip `modules` altogether** → Hawkeye runs every module with every default class.
* **Include a module with an empty list** (`"emotion_recognition": []`) → that module runs with its full default class list.
* **Include a module with specific classes** → only those classes emit alerts. Any unknown class name is rejected with `400`.
When you set `participant` to a specific identity, it must match the LiveKit **identity** the participant joined with (not their display name). If that participant hasn't joined yet, Hawkeye waits — if they never appear, the session idles until `max_duration` fires.
## Modules & Classes
Detects head turns away from centre.
**Classes:** `Looking Left`, `Looking Right`
Classifies the participant's facial expression each second.
**Classes:** `angry`, `sad`, `disgust`, `fear`, `happy`, `surprise`, `neutral`
Independent of head pose — catches subtle off-screen glances.
**Classes:** `Looking left`, `Looking right`
Counts distinct faces in the frame. The class name is the exact face count you want to alert on.
**Classes:** any numeric string, e.g. `"2"`, `"3"`, `"4"`
Fires when the target participant's face moves out of the camera view.
**Classes:** `out_of_frame`
## Minimum viable payload
Everything defaulted — all modules, all classes:
```json theme={null}
{
"livekit_url": "wss://your-livekit-domain.livekit.cloud",
"access_token": "eyJhbGciOi...",
"callback_url": "wss://your-callback-endpoint.example.com/vision",
"max_duration": 10
}
```
## Only a couple of modules
Just watch emotions and face count:
```json theme={null}
{
"livekit_url": "wss://your-livekit-domain.livekit.cloud",
"access_token": "eyJhbGciOi...",
"callback_url": "wss://your-callback-endpoint.example.com/vision",
"max_duration": 10,
"modules": {
"emotion_recognition": ["angry", "sad"],
"face_count": ["2", "3"]
}
}
```
## Response
```json theme={null}
{
"session_id": "8f2a1e5b-4c9d-4a3f-9c11-2c07be7d1c22",
"status": "IN_QUEUE",
"max_duration": 10,
"modules": [
"emotion_recognition",
"eyegaze_tracking",
"face_count",
"face_out_of_focus",
"face_pose_detection"
]
}
```
| Field | Description |
| -------------- | ------------------------------------------------------------------------------------------------------ |
| `session_id` | TruGen session identifier — use this to poll [Get Session Status](/docs/agents/vision/session-status). |
| `status` | Initial lifecycle state, usually `IN_QUEUE`. Transitions to `IN_PROGRESS` when the worker joins. |
| `max_duration` | Echoed back in minutes. |
| `modules` | Sorted list of module names that were resolved for this session. |
## Alert Format
When a class is detected, Hawkeye pushes a JSON message to your `callback_url`:
```json theme={null}
{
"session_id": "8f2a1e5b-4c9d-4a3f-9c11-2c07be7d1c22",
"module": "emotion_recognition",
"class": "angry",
"timestamp": "2026-08-11T14:24:11Z"
}
```
Use this to drive dashboards, escalate to a moderator, or feed downstream analytics — Hawkeye handles the vision, you handle the reaction.
## What's Next?
Poll a running session, or check the final state after it ends.
What Vision Understanding does and when to use it.