---
title: "Create realtime emotion session"
method: POST
path: "/v2/realtime/session"
tags: ["Realtime Emotion API"]
---

# Create realtime emotion session

`POST /v2/realtime/session`

## Request

- Base URL: `https://api.imentiv.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.imentiv.ai/v2/realtime/session`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://api.imentiv.ai/oauth/authorize`
    - Token URL: `https://api.imentiv.ai/oauth/token` scopes: `realtime.write`

Create a new session for real-time video/audio emotion analysis via WebRTC.

## Request body

- PublicCreateSessionRequest: Options for a new realtime session. Every field is optional — send ``{}``, or omit the body entirely, for a full video + audio session.
  - `audio_only` boolean: Set true for a voice-only session: send no camera track on the WebRTC offer and expect no facial-emotion results. Any video track sent anyway is ignored. Defaults to false, a full video + audio session.
  - `emotion_analysis_enabled` boolean: Set false to run the session with no emotion analysis: no facial, vocal or text emotion model runs for it, and its results and windows carry no emotion values. Transcription is unaffected. It holds for the whole session, and a queued place keeps it however a later claim is sent. Defaults to true.

## Response `200`

A slot was free: the session exists and is ready for the WebRTC offer.

- CreateSessionResponse: Response model for session creation.
  - `session_id` string, required: Unique session identifier
  - `status` string, required: Session status
  - `message` string, required: Status message
  - `webrtc_url` string, nullable: WebRTC connection URL for media streaming
  - `ice_servers` IceServer[]: ICE server configuration for WebRTC. Includes public STUN servers and TURN servers with ephemeral credentials for NAT traversal.
    - `urls` union, required: STUN/TURN server URL(s). Can be single URL or list for multiple transports.
      - string
      - string[]
    - `username` string, nullable: Username for TURN authentication (not needed for STUN)
    - `credential` string, nullable: Credential/password for TURN authentication (not needed for STUN)
  - `ice_servers_ttl` integer, nullable: Time-to-live for TURN credentials in seconds. Clients should refresh credentials before this expires for long-running sessions. None if TURN is disabled.
  - `emotion_analysis_enabled` boolean: Whether emotion analysis runs for this session. False when the session was started with `emotion_analysis_enabled` false. A caller that needs it off should check this before sending media.

## Other responses

- `202`: Every session slot is busy and this request is holding a place in the queue. No session exists yet, so there is nothing to connect to. Claim the returned session_id every `poll_after_ms` (POST .../admission) until it answers 200 — each claim also holds the place, so a caller that stops claiming is dropped from the queue. DELETE .../admission to leave early.
- `422`: Validation Error
- `503`: At capacity and no place in the queue was available (the queue is full, or a held place expired). The body carries `{"code": "at_capacity"}`. This is a capacity signal, not a fault — retry later rather than treating it as an error.

## Changes

- **2026-10-31** `bd825cd86e8c`: 2 info
  - added the new optional request property `emotion_analysis_enabled`
  - added the optional property `emotion_analysis_enabled` to the response with the `200` status
- **2026-10-01** `72330e2229c7`: 3 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
  - the endpoint scheme security `BearerAuth` was added to the API
  - the endpoint scheme security `OAuth2Delegated` was added to the API
- **2026-09-22** `536bf48bb9fb`: 1 info
  - removed `#/components/schemas/CreateSessionResponse, #/components/schemas/SessionQueuedResponse` from the response body `anyOf` list for the response status `200`
- **2026-09-08** `b10651168511`: 3 info
  - added `#/components/schemas/CreateSessionResponse, #/components/schemas/SessionQueuedResponse` to the response body `anyOf` list for the response status `200`
  - added the non-success response with the status `503`
  - added the success response with the status `202`
- **2026-08-28** `3c1aeed97c95`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/changes/v2/realtime/session/post.md)

---

[API](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai.md) - [All operations](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/llms.txt) - [OpenAPI document](https://skmtc.dev/imentiv/apis/welcome-to-imentiv-ai/revisions/bc15cec7e794?raw)