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

# Initiate Room

> Create a LiveKit room for an avatar session and receive a client join token

<Note>
  **What This Does:** Creates a LiveKit room and returns the WebSocket URL and a JWT token your client can use to join immediately. The avatar agent connects automatically when the client joins.
</Note>

### Body

All fields are optional. When omitted, server-side defaults are used.

<ParamField body="avatar" type="string" optional>
  Avatar ID to use for the session (e.g. `avat_01KMZHXFPBVCXA5ATK85HCP8G1`). Must be an `avat_...` ID returned by the [Upload Face](/api-reference/endpoints/upload-face-avatar) endpoint.
</ParamField>

<ParamField body="aspect_ratio" type="string" optional>
  Video aspect ratio. Must be one of: `1:1`, `4:3`, `3:4`. Defaults to `1:1`.
</ParamField>

<ParamField body="voice_id" type="string" optional>
  ElevenLabs voice ID to use for TTS. Defaults to the server-configured voice.
</ParamField>

<ParamField body="enable_transcription" type="boolean" optional>
  Whether to enable real-time transcription of user speech. Defaults to `true`.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  `true` when the room was created successfully.
</ResponseField>

<ResponseField name="room" type="object">
  Room connection details.

  <Expandable title="room fields">
    <ResponseField name="name" type="string">
      Unique room name (e.g. `ah-01JR...`).
    </ResponseField>

    <ResponseField name="url" type="string">
      LiveKit WebSocket URL. Pass this to the LiveKit client SDK.
    </ResponseField>

    <ResponseField name="token" type="string">
      Signed JWT the client uses to join the room. Pass directly to `new Room().connect(url, token)`.
    </ResponseField>
  </Expandable>
</ResponseField>

### How It Works

1. A LiveKit room is created and configured with the options you provide.
2. A client join token is generated.
3. When the client connects using the returned `url` + `token`, the avatar agent starts automatically.

<Info>
  **No separate session call needed.** Unlike the `/v1/sessions` endpoint (which requires you to bring your own LiveKit room), this endpoint handles room creation for you. The avatar agent starts automatically on client join.
</Info>

### Client Integration

```javascript theme={null}
const res = await fetch('https://api.agenthuman.com/v1/openclaw/initiate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    avatar: 'avat_01KMZHXFPBVCXA5ATK85HCP8G1',
    aspect_ratio: '1:1',
    voice_id: 'hpp4J3VqNfWAUOO0d1Us',
  }),
});

const { room } = await res.json();

// Connect with the LiveKit client SDK
import { Room } from 'livekit-client';
const livekitRoom = new Room();
await livekitRoom.connect(room.url, room.token);
```

<ResponseExample>
  ```json 201 - Success theme={null}
  {
    "success": true,
    "room": {
      "name": "ah-01JR4XKPQM7T2N3V5W8Y6Z9B",
      "url": "wss://your-livekit-host.livekit.cloud",
      "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }
  }
  ```

  ```json 401 - Unauthorized theme={null}
  {
    "success": false,
    "error": {
      "message": "Unauthorized"
    }
  }
  ```

  ```json 500 - Server Configuration Error theme={null}
  {
    "success": false,
    "error": {
      "message": "LiveKit is not configured on this server"
    }
  }
  ```
</ResponseExample>