---
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.

---

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