---
title: "Create realtime session"
method: POST
path: "/v1/realtime_sessions"
tags: ["Realtime Sessions"]
---

# Create realtime session

`POST /v1/realtime_sessions`

Create a new realtime session with the specified model configuration. The returned ID is also the conversation ID used later to fetch transcripts and recordings from the avatar conversation endpoints.

## Headers

- `X-Runway-Version` '2024-11-06', required

## Request body

- object
  - `model` 'gwm1_avatars', required — The realtime session model type.
  - `avatar` union, required — The avatar configuration for the session.
    - object — A preset avatar from Runway.
      - `type` 'runway-preset', required
      - `presetId` 'game-character' | 'music-superstar' | 'game-character-man' | 'cat-character' | 'influencer' | 'tennis-coach' | 'human-resource' | 'fashion-designer' | 'cooking-teacher', required — ID of a preset avatar.
    - object — A user-created avatar.
      - `type` 'custom', required
      - `avatarId` string, uuid, required — ID of a user-created avatar.
  - `maxDuration` integer — Maximum session duration in seconds.
  - `personality` string — Override the avatar personality for this session. If not provided, uses the avatar default.
  - `startScript` string — Override the avatar start script for this session. If not provided, uses the avatar default.
  - `tools` union[] — Tools available to the avatar during the session.
    - union — A tool available to the avatar during the session.
      - object — A fire-and-forget tool that sends arguments to the frontend client of the realtime session.
        - `type` 'client_event', required
        - `name` string, required — The tool name. Must start with a letter or underscore, followed by alphanumeric characters or underscores.
        - `description` string, required — A description of when and how the tool should be used. Be specific so the avatar understands the right context to invoke it.
        - `parameters` union[]
          - union
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
      - object — A tool that makes a round-trip RPC call to your backend server during the session.
        - `type` 'backend_rpc', required
        - `name` string, required — The tool name. Must start with a letter or underscore, followed by alphanumeric characters or underscores.
        - `description` string, required — A description of when and how the tool should be used. Be specific so the avatar understands the right context to invoke it.
        - `parameters` union[]
          - union
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
            - object
              - …
        - `timeoutSeconds` number — Maximum time to wait for the backend to respond.
  - `integration` union — External integration. Runway renders the avatar; the integration owns conversation or audio.
    - object — ElevenLabs handles conversation; Runway renders the avatar video.
      - `type` 'elevenlabs', required
      - `signedUrl` string, uri, required — ConvAI signed WebSocket URL (~15 min lifetime).
    - object — Join an external LiveKit room; Runway publishes video, your agent supplies audio.
      - `type` 'livekit', required
      - `url` string, uri, required — WebSocket URL of the external LiveKit server the avatar worker should join.
      - `token` string, required — LiveKit access token granting the avatar worker publish rights in the external room.
      - `roomName` string, required — Name of the external LiveKit room.
      - `agentIdentity` string — The participant identity of the customer agent already in the room. When provided, the avatar worker trusts audio published by this identity.
  - `livekit` object — Use integration with type "livekit" instead.
    - `url` string, uri, required — WebSocket URL of the external LiveKit server the avatar worker should join.
    - `token` string, required — LiveKit access token granting the avatar worker publish rights in the external room.
    - `roomName` string, required — Name of the external LiveKit room.
    - `agentIdentity` string — The participant identity of the customer agent already in the room. When provided, the avatar worker trusts audio published by this identity.

## Response `200`

Success

- object
  - `id` string, uuid, required — The ID of the created realtime session. This same value is later used as the conversation ID in the avatar conversation endpoints.

## Changes

- **2026-07-06** `f411647abba7` — 2 info
  - added the new optional request property `integration`
  - added the new optional request property `livekit`
- **2026-04-15** `6f5bc53a0d36` — 2 info
  - the `maxDuration` request property's max was increased from `300.00` to `1800.00`
  - the `personality` request property's maxLength was increased from `2000` to `10000`
- **2026-04-10** `ee023fb84f0e` — 2 breaking, 2 info
  - removed `subschema #1: StringParameter, subschema #2: IntegerParameter, subschema #3: NumberParameter, subschema #4: BooleanParameter, subschema #5: ArrayParameter, subschema #6: ObjectParameter` from the `tools/items/oneOf[subschema #1: ClientEventTool]/parameters/items/oneOf[subschema #6: ObjectParameter]/properties/items/` request property `oneOf` list
  - removed `subschema #1: StringParameter, subschema #2: IntegerParameter, subschema #3: NumberParameter, subschema #4: BooleanParameter, subschema #5: ArrayParameter, subschema #6: ObjectParameter` from the `tools/items/oneOf[subschema #2: BackendRPCTool]/parameters/items/oneOf[subschema #6: ObjectParameter]/properties/items/` request property `oneOf` list
  - removed discriminator from `tools/items/oneOf[subschema #1: ClientEventTool]/parameters/items/oneOf[subschema #6: ObjectParameter]/properties/items/` request property
  - removed discriminator from `tools/items/oneOf[subschema #2: BackendRPCTool]/parameters/items/oneOf[subschema #6: ObjectParameter]/properties/items/` request property
- …earlier changes not shown

[Full history](https://skmtc.dev/runwayml/apis/runwayml-api/changes/v1/realtime_sessions/post.md)

---

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