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

# Create self-managed session

> Creates a self-managed session that takes in avatar audio and returns synchronized video/audio.

<Warning>
  **Do not call this endpoint directly.** Use an official plugin such as [LiveKit](/livekit) or [Pipecat](/pipecat) instead to ensure proper session lifecycle management.
</Warning>

<Note>
  To upload an avatar image file directly, switch the request body content type to `multipart/form-data` below.
</Note>


## OpenAPI

````yaml /openapi.json post /liveai/sessions
openapi: 3.1.0
info:
  title: LemonSlice
  description: An API that gives access to a LemonSlice agent via a Daily room.
  license:
    name: MIT
    identifier: MIT
  version: 1.0.0
servers:
  - url: https://lemonslice.com/api
security:
  - apiKeyAuth: []
paths:
  /liveai/sessions:
    post:
      summary: Create self-managed session
      description: >-
        Creates a self-managed session that takes in avatar audio and returns
        synchronized video/audio.
      operationId: createSession
      requestBody:
        description: >-
          The properties used to create a self-managed session. Use
          `application/json` to reference an agent_id or agent_image_url, or
          `multipart/form-data` to upload an image file directly.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SessionInput'
            examples:
              by_agent_image_url:
                summary: Create a session using an agent_image_url
                value:
                  agent_image_url: https://cdn.lemonslice.com/agents/custom_agent.png
                  agent_prompt: a person talking
                  transport_type: livekit
                  properties:
                    livekit_url: wss://lemonslice-pb123.livekit.cloud
                    livekit_token: eyJhbGciOiJIUzI1NiIsInR5a...
              by_agent_id:
                summary: Create a session using an agent_id
                value:
                  agent_id: agent_abc123
                  transport_type: livekit
                  properties:
                    livekit_url: wss://lemonslice-pb123.livekit.cloud
                    livekit_token: eyJhbGciOiJIUzI1NiIsInR5a...
              daily_transport:
                summary: Create a session using Daily transport
                value:
                  agent_id: agent_abc123
                  transport_type: daily
                  properties:
                    daily_room_url: https://your-domain.daily.co/your-room
                    daily_token: eyJhbGciOiJIUzI1NiIsInR5a...
          multipart/form-data:
            schema:
              type: object
              required:
                - image
                - payload
              properties:
                image:
                  description: >-
                    The avatar image file. The image should be 368x560 pixels
                    with a maximum size of 4 MB. LemonSlice will automatically
                    center-crop to the target aspect ratio if the dimensions do
                    not match.
                  type: string
                  format: binary
                payload:
                  $ref: '#/components/schemas/SessionFormDataPayload'
            encoding:
              payload:
                contentType: application/json
        required: true
      responses:
        '201':
          description: Session created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Session'
              example:
                session_id: 3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a
        '400':
          description: Invalid arguments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Missing required fields
        '401':
          description: Authentication denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Invalid API key
        '402':
          description: Agent owner has insufficient funds
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Agent agent_123abc owner has insufficient funds
        '403':
          description: Agent not owned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Agent agent_123abc is not owned by the authenticated user
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                detail: Agent not found
        '500':
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              example:
                detail: Internal server error
components:
  schemas:
    SessionInput:
      description: >-
        Input to create an agent session. Exactly one of `agent_id` or
        `agent_image_url` must be provided.
      type: object
      required:
        - transport_type
      properties:
        agent_prompt:
          description: >-
            A high-level system prompt that subtly influences the avatar's
            movements, expressions, and emotional demeanor. This prompt is best
            used to suggest general affect or demeanor (for example, 'feel
            excited' or 'look sad') rather than precise or deterministic
            actions.
          type: string
          default: a person talking
        agent_idle_prompt:
          description: >-
            A high-level system prompt that influences the avatar's movements,
            expressions, and emotional demeanor during the idle state.
          type: string
          default: a serious person
        idle_timeout:
          description: >-
            Idle timeout in seconds. If a negative number is provided, the
            session will have no idle timeout.
          type: integer
          default: 60
        response_done_timeout:
          description: >-
            Time in seconds to wait without receiving new audio bytes before
            marking the response as complete. Some TTS models do not send an end
            response event, or do not send it in a timely manner. This parameter
            enables detection of response completion when such events are
            missing or delayed. This parameter can also be used to ensure proper
            conversation flow with multi-message LLMs (e.g. `gpt-realtime-2`).
          type:
            - number
            - 'null'
          default: null
          x-mint:
            post:
              - 'default: null'
        aspect_ratio:
          description: Output aspect ratio for the avatar video.
          type: string
          enum:
            - 2x3
            - 9x16
            - 1x1
          default: 2x3
        model:
          description: Model variant. Leave `null` to use the normal flagship model.
          type:
            - string
            - 'null'
          enum:
            - lite
            - flash
            - pro
            - null
          default: null
          x-mint:
            post:
              - 'default: null'
        simulcast:
          description: >-
            Enable WebRTC simulcast, which publishes multiple resolutions of the
            avatar video so subscribers receive the best quality their bandwidth
            allows. LiveKit transport only.
          type: boolean
          default: false
        transport_type:
          description: >-
            The interface type for how the audio is sent and how the A/V is
            returned.
          type: string
          enum:
            - livekit
            - daily
        properties:
          description: Additional properties needed to connect to the transport layer.
          oneOf:
            - $ref: '#/components/schemas/LiveKitTransportProperties'
              title: LiveKit
            - $ref: '#/components/schemas/DailyTransportProperties'
              title: Daily
      oneOf:
        - title: By agent_image_url
          type: object
          required:
            - agent_image_url
          properties:
            agent_image_url:
              description: >-
                A URL to an agent image to use. The image should be 368x560
                pixels. LemonSlice will automatically center-crop your image to
                the target aspect ratio if the dimensions do not match the
                expected values. Provide either agent_image_url or agent_id, but
                not both.
              type: string
              format: uri
              example: https://example.com/custom_agent.png
          not:
            required:
              - agent_id
        - title: By agent_id
          type: object
          required:
            - agent_id
          properties:
            agent_id:
              description: >-
                The ID of the LemonSlice agent. Provide either `agent_id` or
                `agent_image_url`, but not both.
              type: string
              example: agent_abc123
          not:
            required:
              - agent_image_url
      unevaluatedProperties: false
    SessionFormDataPayload:
      description: >-
        The properties used to create a self-managed session alonside an image
        upload.
      type: object
      required:
        - transport_type
      properties:
        agent_prompt:
          description: >-
            A high-level system prompt that subtly influences the avatar's
            movements, expressions, and emotional demeanor.
          type: string
          default: a person talking
        agent_idle_prompt:
          description: >-
            A high-level system prompt that influences the avatar's movements,
            expressions, and emotional demeanor during the idle state.
          type: string
          default: a serious person
        idle_timeout:
          description: >-
            Idle timeout in seconds. If a negative number is provided, the
            session will have no idle timeout.
          type: integer
          default: 60
        response_done_timeout:
          description: >-
            Time in seconds to wait without receiving new audio bytes before
            marking the response as complete.
          type:
            - number
            - 'null'
          default: null
          x-mint:
            post:
              - 'default: null'
        aspect_ratio:
          description: Output aspect ratio for the avatar video.
          type: string
          enum:
            - 2x3
            - 9x16
            - 1x1
          default: 2x3
        model:
          description: Model variant. Leave `null` to use the normal flagship model.
          type:
            - string
            - 'null'
          enum:
            - lite
            - flash
            - pro
            - null
          default: null
          x-mint:
            post:
              - 'default: null'
        simulcast:
          description: Enable WebRTC simulcast. LiveKit transport only.
          type: boolean
          default: false
        transport_type:
          description: >-
            The interface type for how the audio is sent and how the A/V is
            returned.
          type: string
          enum:
            - livekit
            - daily
          example: livekit
        properties:
          description: Additional properties needed to connect to the transport layer.
          oneOf:
            - $ref: '#/components/schemas/LiveKitTransportProperties'
              title: LiveKit
            - $ref: '#/components/schemas/DailyTransportProperties'
              title: Daily
      additionalProperties: false
    Session:
      type: object
      required:
        - session_id
      properties:
        session_id:
          description: The ID of the session.
          type: string
          example: 3f7c2b91-9e1f-4a6a-8e9d-2c7c3e7d9b5a
    Error:
      type: object
      properties:
        detail:
          type: string
          example: Agent not found
    ServerError:
      type: object
      properties:
        detail:
          type: string
          example: Internal server error
    LiveKitTransportProperties:
      type: object
      required:
        - livekit_url
        - livekit_token
      properties:
        livekit_url:
          type: string
          format: uri
          example: wss://lemonslice-pb123.livekit.cloud
        livekit_token:
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5a...
      additionalProperties: true
      example:
        livekit_url: wss://lemonslice-pb123.livekit.cloud
        livekit_token: eyJhbGciOiJIUzI1NiIsInR5a...
    DailyTransportProperties:
      type: object
      properties:
        daily_room_url:
          description: >-
            Daily room URL to use. If not provided, LemonSlice will create a new
            room at an additional cost of 0.51 credits per participant minute.
          type: string
          format: uri
          example: https://your-domain.daily.co/your-room
        daily_token:
          description: Daily token for authenticating with the room.
          type: string
          example: eyJhbGciOiJIUzI1NiIsInR5a...
        enable_recording:
          description: >-
            Enable Daily call recording. If set, recordings_bucket must also be
            provided. Enabling recording incurs an additional charge of 0.378
            credits per minute.
          type: string
          enum:
            - cloud
            - cloud-audio-only
            - local
            - raw-tracks
        recordings_bucket:
          description: >-
            The S3 bucket configuration where recordings will be saved. Follows
            the Daily recording bucket specification.
          type: object
          properties:
            bucket_name:
              description: The name of the S3 bucket.
              type: string
            bucket_region:
              description: The AWS region of the S3 bucket.
              type: string
            assume_role_arn:
              description: The ARN of the IAM role for Daily to assume for storage.
              type: string
            allow_api_access:
              description: >-
                Whether Daily's recording access link API should allow
                downloading the recording.
              type: boolean
          required:
            - bucket_name
            - bucket_region
            - assume_role_arn
      dependentRequired:
        enable_recording:
          - recordings_bucket
      additionalProperties: true
      example:
        daily_room_url: https://your-domain.daily.co/your-room
        daily_token: eyJhbGciOiJIUzI1NiIsInR5a...
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Your LemonSlice API token.

````