---
title: "Create Session"
method: POST
path: "/api/open/v4/liveAvatar/session/create"
tags: ["Session Management"]
---

# Create Session

`POST /api/open/v4/liveAvatar/session/create`

Create a new streaming avatar session

## Request body

- CreateSessionRequest
  - `avatar_id` string, required — Digital human model in real-time avatar. If you want to use a custom uploaded video, you need to call the avatar/create interface to create a template. This process takes some time to process. You can check the processing status through the avatar/detail interface. When status=3, you can use the avatar_id field to pass it in.
  - `duration` number — Session duration in seconds (max: 3600). Credits are pre-charged for the full duration, but any unused credits will be refunded after the session ends. Rates depend on your subscription plan.
  - `knowledge_id` string — Knowledge base ID to provide context for AI responses. Create and manage knowledge bases using the Knowledge Base API. When provided, the AI will use documents and URLs from the knowledge base to enhance response accuracy.
  - `voice_id` string — Voice ID to change avatar's voice. Get valid IDs from Voice List API. Note that voice IDs from Akool Multilingual 2 cannot be used with Streaming Avatar.
  - `voice_url` string — Custom voice model URL. Get valid URLs from Voice List API
  - `language` string — Language code to use for the session. Get valid codes from Language List API
  - `mode_type` 1 | 2 — Avatar interaction mode that determines how the avatar responds to input: - `1`: Retelling mode - Avatar repeats the provided content verbatim - `2`: Dialogue mode - Avatar engages in conversational interaction
  - `scene_mode` 'fast_dialogue' — Scene mode for the session. - `fast_dialogue`: Low-latency dialogue mode. Optimized for realtime voice interaction and **voice input only**.
  - `e2e_type` 'openai' — End-to-end (E2E) pipeline provider. Only applicable when `scene_mode` is `fast_dialogue`. - `openai`: OpenAI
  - `background_url` string — URL of background image/video for avatar scene
  - `voice_params` union — Voice configuration for the session. Use `Option 2` when `scene_mode` is `fast_dialogue`. Otherwise use `Option 1`.
    - VoiceParams — Voice parameters for normal mode
      - `speed` number — Controls the speed of the generated speech. Values range from 0.8 to 1.2, with 1.0 being the default speed.
      - `pron_map` object — Pronunciation mapping for custom words. Example: pron_map with akool mapped to ai ku er
      - `stt_language` string — Language code for speech-to-text recognition to improve accuracy by using language-specific models. If not specified, default language or auto-detection will be used.
      - `stt_type` 'openai_realtime' — Speech-to-text type. "openai_realtime" = OpenAI Realtime
      - `turn_detection` TurnDetection
        - `type` 'server_vad' | 'semantic_vad' — Turn detection type. "server_vad" = Server VAD, "semantic_vad" = Semantic VAD
        - `threshold` number — Activation threshold (0 to 1). A higher threshold will require louder audio to activate the model, and thus might perform better in noisy environments. Available when type is "server_vad".
        - `prefix_padding_ms` integer — Amount of audio (in milliseconds) to include before the VAD detected speech. Available when type is "server_vad".
        - `silence_duration_ms` integer — Duration of silence (in milliseconds) to detect speech stop. With shorter values turns will be detected more quickly. Available when type is "server_vad".
      - `elevenlabs_settings` ElevenlabsSettings — ElevenLabs custom voice configuration. Allows you to use your own ElevenLabs API key and customize voice parameters. The voice_id should be specified in the main voice_id field of the session request.
        - `api_key` string — Your ElevenLabs API key for authentication
        - `model_id` string — ElevenLabs model ID to use for voice generation (e.g., "eleven_flash_v2_5", "eleven_turbo_v2_5", "eleven_multilingual_v2")
        - `stability` number — Controls the stability of the voice. Higher values make the voice more consistent, lower values add more variation. Range is 0 to 1.
        - `similarity_boost` number — Controls how closely the AI should adhere to the original voice. Higher values stick closer to the original voice. Range is 0 to 1.
        - `style` number — Controls the style exaggeration of the voice. Range is 0 to 1.
        - `use_speaker_boost` boolean — Enhances the similarity to the original speaker. Recommended for improved voice cloning quality.
      - `minimax_settings` MinimaxSettings — Minimax custom voice configuration. Allows you to use your own Minimax API key and customize voice parameters.
        - `api_key` string — Your Minimax API key for authentication
        - `model` string — Minimax speech model ID to use for voice generation
        - `language_boost` string — Language boost option for Minimax speech generation
        - `voice_setting` MinimaxVoiceSetting — Minimax voice parameters
          - `voice_id` string — Minimax voice ID
          - `speed` number — Voice speed
          - `vol` number — Voice volume
          - `pitch` number — Voice pitch
          - `emotion` string — Voice emotion
    - FastDialogueVoiceParams — Voice parameters for `scene_mode=fast_dialogue`
      - `voice_id` 'alloy' | 'ash' | 'ballad' | 'coral' | 'echo' | 'sage' | 'shimmer' | 'verse' | 'marin' | 'cedar' — Preset voice ID used in fast dialogue mode. Notes: - Voices returned by the Voice List API are **not** available in this mode.
      - `stt_language` string — Language code for speech-to-text recognition to improve accuracy by using language-specific models. If not specified, default language or auto-detection will be used.
      - `turn_detection` TurnDetection
        - `type` 'server_vad' | 'semantic_vad' — Turn detection type. "server_vad" = Server VAD, "semantic_vad" = Semantic VAD
        - `threshold` number — Activation threshold (0 to 1). A higher threshold will require louder audio to activate the model, and thus might perform better in noisy environments. Available when type is "server_vad".
        - `prefix_padding_ms` integer — Amount of audio (in milliseconds) to include before the VAD detected speech. Available when type is "server_vad".
        - `silence_duration_ms` integer — Duration of silence (in milliseconds) to detect speech stop. With shorter values turns will be detected more quickly. Available when type is "server_vad".
      - `elevenlabs_settings` ElevenlabsSettings — ElevenLabs custom voice configuration. Allows you to use your own ElevenLabs API key and customize voice parameters. The voice_id should be specified in the main voice_id field of the session request.
        - `api_key` string — Your ElevenLabs API key for authentication
        - `model_id` string — ElevenLabs model ID to use for voice generation (e.g., "eleven_flash_v2_5", "eleven_turbo_v2_5", "eleven_multilingual_v2")
        - `stability` number — Controls the stability of the voice. Higher values make the voice more consistent, lower values add more variation. Range is 0 to 1.
        - `similarity_boost` number — Controls how closely the AI should adhere to the original voice. Higher values stick closer to the original voice. Range is 0 to 1.
        - `style` number — Controls the style exaggeration of the voice. Range is 0 to 1.
        - `use_speaker_boost` boolean — Enhances the similarity to the original speaker. Recommended for improved voice cloning quality.
      - `minimax_settings` MinimaxSettings — Minimax custom voice configuration. Allows you to use your own Minimax API key and customize voice parameters.
        - `api_key` string — Your Minimax API key for authentication
        - `model` string — Minimax speech model ID to use for voice generation
        - `language_boost` string — Language boost option for Minimax speech generation
        - `voice_setting` MinimaxVoiceSetting — Minimax voice parameters
          - `voice_id` string — Minimax voice ID
          - `speed` number — Voice speed
          - `vol` number — Voice volume
          - `pitch` number — Voice pitch
          - `emotion` string — Voice emotion
  - `stream_type` 'agora' | 'livekit' | 'trtc' — Stream type to use for the session. "agora" = Agora (default), "livekit" = Livekit, "trtc" = TRTC
  - `credentials` Credentials
    - `agora_uid` number — Agora SDK user ID (required when stream_type is "agora")
    - `agora_app_id` string — Agora App ID (optional when stream_type is "agora")
    - `agora_channel` string — Agora channel name (required when stream_type is "agora")
    - `agora_token` string — Agora access token (required when stream_type is "agora")
    - `livekit_url` string — LiveKit server URL (required when stream_type is "livekit")
    - `livekit_token` string — LiveKit access token (required when stream_type is "livekit")
    - `livekit_room_name` string — LiveKit room name (optional when stream_type is "livekit")
    - `livekit_server_identity` string — LiveKit server identity (optional when stream_type is "livekit")
    - `livekit_client_identity` string — LiveKit client identity (optional when stream_type is "livekit")
    - `trtc_sdk_app_id` number — TRTC App ID (required when stream_type is "trtc")
    - `trtc_sdk_room_id` string — TRTC room ID (required when stream_type is "trtc")
    - `trtc_sdk_user_id` string — TRTC user ID (required when stream_type is "trtc")
    - `trtc_sdk_user_sig` string — TRTC authentication token (userSig) (required when stream_type is "trtc")

## Response `200`

Session created successfully

- object
  - `code` integer, required — Interface returns business status code (1000: success)
  - `msg` string, required — Interface returns status information
  - `data` SessionResponse
    - `_id` string — Session ID
    - `uid` integer — User ID
    - `type` integer — Session type
    - `status` 1 | 2 | 3 | 4 — Session status (1:queueing, 2:processing, 3:completed, 4:failed)
    - `stream_type` string — Stream type used for the session
    - `credentials` Credentials
      - `agora_uid` number — Agora SDK user ID (required when stream_type is "agora")
      - `agora_app_id` string — Agora App ID (optional when stream_type is "agora")
      - `agora_channel` string — Agora channel name (required when stream_type is "agora")
      - `agora_token` string — Agora access token (required when stream_type is "agora")
      - `livekit_url` string — LiveKit server URL (required when stream_type is "livekit")
      - `livekit_token` string — LiveKit access token (required when stream_type is "livekit")
      - `livekit_room_name` string — LiveKit room name (optional when stream_type is "livekit")
      - `livekit_server_identity` string — LiveKit server identity (optional when stream_type is "livekit")
      - `livekit_client_identity` string — LiveKit client identity (optional when stream_type is "livekit")
      - `trtc_sdk_app_id` number — TRTC App ID (required when stream_type is "trtc")
      - `trtc_sdk_room_id` string — TRTC room ID (required when stream_type is "trtc")
      - `trtc_sdk_user_id` string — TRTC user ID (required when stream_type is "trtc")
      - `trtc_sdk_user_sig` string — TRTC authentication token (userSig) (required when stream_type is "trtc")

---

[API](https://skmtc.dev/akool/apis/face-detection-api.md) · [All operations](https://skmtc.dev/akool/apis/face-detection-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/akool/face-detection-api/revisions/ce2ff5679949/schema)