> ## Documentation Index > Fetch the complete documentation index at: https://platform.perso.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create Session > Create a new interactive session with the specified capabilities. ## Capabilities Choose one or more capabilities for your session. Each capability has different required fields: | Capability | Description | Required Fields | |------------|-------------|-----------------| | `STF_WEBRTC` | Full interactive avatar with video streaming | `prompt`, `llm_type`, `model_style`, `tts_type` | | `STF_ONPREMISE` | On-premise avatar rendering | `model_style` | | `LLM` | Language model conversation only | `prompt`, `llm_type` | | `TTS` | Text-to-speech only | `tts_type` | | `STT` | Speech-to-text only | `stt_type` | > **Note:** `STF_WEBRTC` and `STF_ONPREMISE` cannot be used together. > **Note:** `interactive_agent_config` cannot be combined with `llm_type` or `prompt` — > providing either of them alongside `interactive_agent_config` is rejected with `400`. ## Default Behavior If no capability is specified, the session defaults to `STF_WEBRTC`. ## Example Select **"STF_WEBRTC Session"** from the **Examples** dropdown above to see a complete request example. ## OpenAPI ````yaml /specs/openapi-interactive.json post /api/v1/session/ openapi: 3.0.3 info: title: Perso Interactive API version: 0.0.0 servers: - url: https://platform.perso.ai security: [] tags: - name: Embed paths: /api/v1/session/: post: tags: - Session Lifecycle summary: Create Session description: > Create a new interactive session with the specified capabilities. ## Capabilities Choose one or more capabilities for your session. Each capability has different required fields: | Capability | Description | Required Fields | |------------|-------------|-----------------| | `STF_WEBRTC` | Full interactive avatar with video streaming | `prompt`, `llm_type`, `model_style`, `tts_type` | | `STF_ONPREMISE` | On-premise avatar rendering | `model_style` | | `LLM` | Language model conversation only | `prompt`, `llm_type` | | `TTS` | Text-to-speech only | `tts_type` | | `STT` | Speech-to-text only | `stt_type` | > **Note:** `STF_WEBRTC` and `STF_ONPREMISE` cannot be used together. > **Note:** `interactive_agent_config` cannot be combined with `llm_type` or `prompt` — > providing either of them alongside `interactive_agent_config` is rejected with `400`. ## Default Behavior If no capability is specified, the session defaults to `STF_WEBRTC`. ## Example Select **"STF_WEBRTC Session"** from the **Examples** dropdown above to see a complete request example. operationId: v1_session_create requestBody: content: application/json: schema: $ref: '#/components/schemas/SessionCreateRequest' examples: STFWEBRTCSession: value: capability: - STF_WEBRTC prompt: plp-ce0cd928367c09b3a511e92c4fec5405 llm_type: gpt-4o tts_type: chohye_volume model_style: chaehee_livechat-front-black_suit-natural stt_type: gpt-4o-mini-transcribe summary: Create an STF_WEBRTC session description: >- Example request for creating an STF_WEBRTC session with all required fields. application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/SessionCreateRequest' multipart/form-data: schema: $ref: '#/components/schemas/SessionCreateRequest' responses: '201': content: application/json: schema: $ref: '#/components/schemas/SessionCreate' description: '' '400': description: Bad Request - Invalid input data or parameters. '401': description: Unauthorized - Invalid or missing authentication credentials. '403': description: Forbidden - You do not have permission to perform this action. '405': description: Method Not Allowed - Invalid HTTP method '406': description: Not Acceptable - Invalid request accept headers '415': description: Unsupported Media Type - Invalid content type '500': description: Internal Server Error - An unexpected error occurred. security: - PersoPlatform-APIKey: [] components: schemas: SessionCreateRequest: type: object properties: prompt: type: string minLength: 1 nullable: true description: >- Prompt identifier defining the system prompt + intro message. Mutually exclusive with `interactive_agent_config`. capability: type: array items: $ref: '#/components/schemas/CapabilityTypeEnum' description: List of session capabilities to enable (e.g. STF_WEBRTC, STT, LLM). document: type: string minLength: 1 nullable: true description: Optional document identifier to attach as a knowledge source. llm_type: type: string minLength: 1 nullable: true description: >- LLM model identifier (use **List LLM Types**). Mutually exclusive with `interactive_agent_config`. tts_type: type: string minLength: 1 nullable: true description: TTS voice/type identifier (use **List TTS Types**). text_normalization_config: type: string minLength: 1 nullable: true description: >- Identifier of the text-normalization config applied to TTS input. Configs bundle regex rulesets that rewrite text before speech synthesis (e.g. `20℉` → `화씨 20도`, `₩1,000` → `1,000 원`). text_normalization_locale: type: string nullable: true description: >- Locale code (e.g. `ko-KR`) used to select locale-specific rules from the configured ruleset. If omitted, only locale-agnostic rules run; if set, both locale-agnostic and matching-locale rules run. maxLength: 10 stt_type: type: string minLength: 1 nullable: true description: >- STT engine identifier (use **List STT Types**). Required only if STT capability is in `capability`. stt_text_normalization_config: type: string minLength: 1 nullable: true description: >- Identifier of the text-normalization config applied to STT output. Same ruleset mechanism as TTS normalization but runs on the transcribed text before it is forwarded to the LLM. stt_text_normalization_locale: type: string nullable: true description: >- Locale code used to select locale-specific rules from the STT normalization config. Behaviour matches `text_normalization_locale`. maxLength: 10 model_style: type: string minLength: 1 nullable: true description: >- Model style name controlling the avatar's visual style (use **List Model Styles**). agent: type: string nullable: true description: >- Legacy free-form agent identifier string (deprecated — prefer `agent_config`). maxLength: 255 agent_config: type: string minLength: 1 nullable: true description: >- Optional agent designer config identifier to drive a tool-using agent. interactive_agent_config: type: string minLength: 1 nullable: true description: >- Optional interactive-agent config identifier (`pliac-*`). When set, llm.request turns run on the external interactive-agent server instead of a single-shot completion. Cannot be combined with `llm_type` or `prompt` — providing either alongside is rejected. padding_left: type: number format: double maximum: 1 minimum: -1 nullable: true description: >- Horizontal avatar position offset, between `-1.0` and `1.0`. Negative = left, positive = right of frame center. padding_top: type: number format: double maximum: 1 minimum: 0 nullable: true description: >- Vertical avatar position offset from the top, between `0.0` and `1.0` of the frame height. padding_height: type: number format: double maximum: 5 minimum: 0 nullable: true description: Avatar height scale multiplier (`0`-`5`); 1.0 = unscaled. background_image: type: string minLength: 1 nullable: true description: Optional background image identifier for the avatar scene. extra_data: nullable: true description: >- Free-form JSON payload stored alongside the session for caller-defined metadata. mcp_servers: type: array items: type: string minLength: 1 description: >- List of MCP server names available to the LLM during the session (use **List MCP Types**). SessionCreate: type: object properties: session_id: type: string readOnly: true created_at: type: string format: date-time readOnly: true prompt: type: string nullable: true description: >- Prompt identifier defining the system prompt + intro message. Mutually exclusive with `interactive_agent_config`. capability: type: array items: $ref: '#/components/schemas/CapabilityTypeEnum' description: List of session capabilities to enable (e.g. STF_WEBRTC, STT, LLM). document: type: string nullable: true description: Optional document identifier to attach as a knowledge source. llm_type: type: string nullable: true description: >- LLM model identifier (use **List LLM Types**). Mutually exclusive with `interactive_agent_config`. tts_type: type: string nullable: true description: TTS voice/type identifier (use **List TTS Types**). text_normalization_config: type: string nullable: true description: >- Identifier of the text-normalization config applied to TTS input. Configs bundle regex rulesets that rewrite text before speech synthesis (e.g. `20℉` → `화씨 20도`, `₩1,000` → `1,000 원`). text_normalization_locale: type: string nullable: true description: >- Locale code (e.g. `ko-KR`) used to select locale-specific rules from the configured ruleset. If omitted, only locale-agnostic rules run; if set, both locale-agnostic and matching-locale rules run. maxLength: 10 stt_type: type: string nullable: true description: >- STT engine identifier (use **List STT Types**). Required only if STT capability is in `capability`. stt_text_normalization_config: type: string nullable: true description: >- Identifier of the text-normalization config applied to STT output. Same ruleset mechanism as TTS normalization but runs on the transcribed text before it is forwarded to the LLM. stt_text_normalization_locale: type: string nullable: true description: >- Locale code used to select locale-specific rules from the STT normalization config. Behaviour matches `text_normalization_locale`. maxLength: 10 model_style: type: string nullable: true description: >- Model style name controlling the avatar's visual style (use **List Model Styles**). agent: type: string nullable: true description: >- Legacy free-form agent identifier string (deprecated — prefer `agent_config`). maxLength: 255 agent_config: type: string nullable: true description: >- Optional agent designer config identifier to drive a tool-using agent. interactive_agent_config: type: string nullable: true description: >- Optional interactive-agent config identifier (`pliac-*`). When set, llm.request turns run on the external interactive-agent server instead of a single-shot completion. Cannot be combined with `llm_type` or `prompt` — providing either alongside is rejected. status: allOf: - $ref: '#/components/schemas/SessionStatusEnum' readOnly: true padding_left: type: number format: double maximum: 1 minimum: -1 nullable: true description: >- Horizontal avatar position offset, between `-1.0` and `1.0`. Negative = left, positive = right of frame center. padding_top: type: number format: double maximum: 1 minimum: 0 nullable: true description: >- Vertical avatar position offset from the top, between `0.0` and `1.0` of the frame height. padding_height: type: number format: double maximum: 5 minimum: 0 nullable: true description: Avatar height scale multiplier (`0`-`5`); 1.0 = unscaled. background_image: type: string nullable: true description: Optional background image identifier for the avatar scene. extra_data: nullable: true description: >- Free-form JSON payload stored alongside the session for caller-defined metadata. mcp_servers: type: array items: type: string description: >- List of MCP server names available to the LLM during the session (use **List MCP Types**). required: - created_at - session_id - status CapabilityTypeEnum: enum: - LLM - TTS - STT - STF_ONPREMISE - STF_WEBRTC type: string description: |- * `LLM` - LLM * `TTS` - TTS * `STT` - STT * `STF_ONPREMISE` - STF_ONPREMISE * `STF_WEBRTC` - STF_WEBRTC SessionStatusEnum: enum: - CREATED - EXCHANGED - IN_PROGRESS - TERMINATED type: string description: |- * `CREATED` - Created * `EXCHANGED` - Exchanged * `IN_PROGRESS` - In Progress * `TERMINATED` - Terminated securitySchemes: PersoPlatform-APIKey: type: apiKey in: header name: PersoPlatform-APIKey ````