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

# Live Capture Sessions

> Incremental audio ingestion for browser microphones and softphones

Designed for browser microphones and softphones that produce audio incrementally. Each session supports exactly one SSE consumer at a time.

## Initialize Session -- `POST /analyze/live/start`

<EndpointMethod method="post" path="/analyze/live/start" />

<ParamField body="filename" type="string">
  Optional hint used to infer the extension.
</ParamField>

<ParamField body="suffix" type="string">
  Explicit extension (e.g., `.wav`). Defaults to `.mp4`.
</ParamField>

<ParamField body="ttl_seconds" type="integer">
  Session lifetime (60-3600). Default 900s.
</ParamField>

### Response

```json theme={null}
{
  "session_id": "live_6a0a64c0",
  "conversation_id": "liveconv_353cee7a",
  "chunk_endpoint": "/analyze/live/live_6a0a64c0/chunk",
  "events_endpoint": "/analyze/live/live_6a0a64c0/events",
  "control_endpoint": "/analyze/live/live_6a0a64c0/control",
  "next_chunk_seq": 0,
  "expires_at": "2025-11-08T18:12:04.991Z",
  "status": "waiting_media"
}
```

## Upload Chunks -- `POST /analyze/live/{session_id}/chunk`

<EndpointMethod method="post" path="/analyze/live/{session_id}/chunk" />

<ParamField path="session_id" type="string" required>
  Live session identifier from `/analyze/live/start`.
</ParamField>

<ParamField body="chunk_seq" type="integer" required>
  Zero-based, must equal `next_chunk_seq`.
</ParamField>

<ParamField body="chunk" type="binary" required>
  PCM/Opus audio chunks.
</ParamField>

Response includes `received_bytes` and updated `next_chunk_seq`. Out-of-order uploads return `409 Conflict`.

## Subscribe to Events -- `GET /analyze/live/{session_id}/events`

<EndpointMethod method="get" path="/analyze/live/{session_id}/events" />

<ParamField path="session_id" type="string" required>
  Live session identifier.
</ParamField>

* Returns the same SSE catalog as `/analyze/stream`.
* Only one connection allowed; a second call returns `409`.
* When streaming completes, the session is cleaned up.

## Control Session -- `POST /analyze/live/{session_id}/control`

<EndpointMethod method="post" path="/analyze/live/{session_id}/control" />

<ParamField path="session_id" type="string" required>
  Live session identifier.
</ParamField>

<ParamField body="action" type="string" required>
  One of: `finalize`, `cancel`, `keepalive`
</ParamField>

<ParamField body="reason" type="string">
  Optional reason for the action.
</ParamField>

### Actions

| Action      | Effect                                         |
| ----------- | ---------------------------------------------- |
| `finalize`  | Stop ingest and begin final processing stages. |
| `cancel`    | Abort processing; SSE clients receive `error`. |
| `keepalive` | Extend TTL without uploading media.            |

Payload schema:

```json theme={null}
{
  "action": "finalize" | "cancel" | "keepalive",
  "reason": "optional string"
}
```

Response echoes `status`, `detail`, and new `expires_at`.

<Warning>
  Only one SSE consumer may be attached to a live session at a time. Attempting to attach a second listener will return `409 Conflict`.
</Warning>

<CardGroup cols={2}>
  <Card title="Live Capture Python Cookbook (Async)" icon="book" href="/api-reference/cookbook/live-capture-python">
    Async Python examples using `httpx` for implementing live capture workflows with `asyncio`.
  </Card>

  <Card title="Live Capture Python Cookbook (Sync)" icon="book" href="/api-reference/cookbook/live-capture-python-sync">
    Synchronous Python examples using `requests` for WSGI apps, Lambda, and non-async environments.
  </Card>
</CardGroup>