LiveKit Server API

Warnings

• gotcha The `livekit-api` library is built on `asyncio`. All service methods return awaitable objects. Calling these methods without `await` or outside an `async` context will lead to runtime errors.
  Fix: Ensure all interactions with `livekit-api` services and methods are properly `await`ed within an `async` function, which is then run using `asyncio.run()`.
• gotcha Access tokens generated by `api.AccessToken` require explicit grants (e.g., `api.VideoGrants`) to define what actions a participant can perform. Incorrectly configured grants are a common cause of 'permission denied' errors.
  Fix: Always review `api.VideoGrants` (or other grant types like `api.RecorderGrants`) when generating tokens. Ensure `room_join=True` and any other necessary permissions (e.g., `can_publish`, `can_subscribe`) are set for the intended participant role.
• gotcha Hardcoding `LIVEKIT_HOST`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` directly in your code is a significant security risk and makes deployments brittle. These are sensitive credentials.
  Fix: Always retrieve sensitive credentials using environment variables (e.g., `os.environ.get('LIVEKIT_API_KEY')`) or a secure configuration management system.
• breaking Significant changes in the underlying LiveKit server API or protocol can lead to unexpected behavior or API breakage if the `livekit-api` SDK version is not kept reasonably up-to-date with the server version.
  Fix: Regularly update `livekit-api` to the latest stable version. Consult the LiveKit server release notes and documentation for any required SDK version compatibility updates.

Install

• pip install livekit-api Install stable version

Imports

• RoomServiceClient

  from livekit.api import RoomServiceClient

  Primary client for managing LiveKit rooms.
• AccessToken

  from livekit.api import AccessToken

  Class for generating JWT access tokens for participants.
• VideoGrants

  from livekit.api import VideoGrants

  Used to define permissions for access tokens.
• CreateRoomRequest

  from livekit.api import CreateRoomRequest

  Request object for creating new rooms.

Quickstart

This quickstart demonstrates how to create a LiveKit room and generate an access token for a participant using `livekit-api`. It uses environment variables for LiveKit host and credentials for security. The operations are asynchronous and should be run within an asyncio event loop.

import os
import asyncio
from livekit import api

host = os.environ.get("LIVEKIT_HOST", "http://localhost:7880")
api_key = os.environ.get("LIVEKIT_API_KEY", "devkey")
api_secret = os.environ.get("LIVEKIT_API_SECRET", "secret")

async def main():
    if not api_key or not api_secret:
        print("LIVEKIT_API_KEY and LIVEKIT_API_SECRET must be set.")
        return

    # Initialize LiveKit client
    svc = api.RoomServiceClient(host, api_key, api_secret)

    room_name = "my-test-room"
    try:
        room = await svc.create_room(
            api.CreateRoomRequest(
                name=room_name,
                empty_timeout=60 * 10, # 10 minutes
            )
        )
        print(f"Room '{room.name}' created.")
    except api.ApiException as e:
        if e.status == 409: # Room already exists
            print(f"Room '{room_name}' already exists.")
        else:
            raise

    # Generate an access token for a participant
    token = api.AccessToken(api_key, api_secret) \
        .with_identity("user1") \
        .with_name("Test User") \
        .with_grants(api.VideoGrants(room_join=True, room=room_name)) \
        .to_jwt()

    print(f"Access Token: {token}")

if __name__ == "__main__":
    asyncio.run(main())