Vonage Video (API Client)

1.5.1 · active · verified Thu Apr 16

The `vonage-video` package provides programmatic access to the Vonage Video API, enabling server-side applications to manage video sessions, tokens, archives, and broadcasts. While it exists as a standalone PyPI package, it is primarily designed to be installed as a dependency of the main `vonage` Python SDK (currently v4.x.x). The `vonage` SDK is the recommended entry point for interacting with all Vonage APIs, including Video. Vonage maintains an active release cadence for its SDKs, with frequent updates and improvements.

Common errors

```
AttributeError: 'Vonage' object has no attribute 'video'
```
cause The installed `vonage` SDK version might be too old or `vonage-video` (as a dependency) might not be correctly installed/available, preventing the `video` module from being attached to the client.

fix Ensure you have the latest `vonage` SDK installed: `pip install --upgrade vonage`. If the issue persists, check Python environment and dependencies.
```
ModuleNotFoundError: No module named 'opentok'
```
cause This error occurs when trying to run code written for the legacy `opentok` SDK after migrating to the `vonage` SDK or when `opentok` was never installed.

fix If migrating, update your code to use the `vonage` SDK and its `client.video` methods and `vonage_video` data models. If it's a new project, ensure you are not importing `opentok` and are using `vonage` instead.
```
from vonage.video import SessionOptions # ModuleNotFoundError: No module named 'vonage.video'
```
cause While `client.video` provides access to methods, data models like `SessionOptions` are imported directly from the top-level `vonage_video` package, not a nested submodule of `vonage`.

fix Change the import statement to `from vonage_video import SessionOptions` (and similar for other models).

Warnings

breaking Migration from OpenTok Python SDK to Vonage Python SDK requires significant changes. Positional parameters are replaced with data models, methods return Pydantic data models, and some method names have changed. Authentication now primarily uses Application ID and Private Key (for JWTs) instead of API Key and Secret for Video API operations.
Fix: Refer to the official 'OpenTok to Vonage Video Server SDK Transition Guide (Python)' for detailed migration steps. Update method calls, parameter structures, and authentication mechanisms.
gotcha While `vonage-video` exists on PyPI, it's typically installed as a dependency of the main `vonage` SDK. Directly installing `vonage-video` and trying to use its classes might lead to missing broader SDK context or unexpected behavior, especially for API client instantiation.
Fix: Always install `pip install vonage` to get the full Vonage Python SDK. Access Video API functionality via `client = Vonage(auth=...); client.video.create_session(...)`.
gotcha Authentication for the Vonage Video API uses an Application ID and a Private Key (for JWT generation). The traditional API Key and Secret are generally used for other Vonage APIs (like SMS, Voice) but not directly for Video API calls through the `vonage` client.
Fix: Ensure you have created a Vonage Application with the 'Video' capability enabled in your Vonage Dashboard. Download the private key file and use its path along with the Application ID for `Auth` initialization.

Install

pip install vonage Recommended: Install via main Vonage SDK
pip install vonage-video Direct installation (not recommended for most use cases)

Imports

Vonage
```
from vonage import Vonage, Auth
```
The recommended way to access Video API functionality is through the main `vonage` client.
SessionOptions
wrong:
```
from vonage.video import SessionOptions
```
correct:
```
from vonage_video import SessionOptions
```
Data models for Video API methods are imported directly from `vonage_video`, not nested under `vonage.video`.
MediaMode
```
from vonage_video.constants import MediaMode
```
Constants like MediaMode are found within the `vonage_video.constants` submodule.

Quickstart

This quickstart demonstrates how to initialize the Vonage client, create a video session, and generate a client token. It uses environment variables for authentication credentials, which is recommended for security. Ensure you have a Vonage Application with Video capabilities enabled and the corresponding Application ID and Private Key file.

import os
from vonage import Vonage, Auth
from vonage_video.constants import MediaMode
from vonage_video import SessionOptions

# Replace with your actual Vonage Application ID and Private Key path
# Obtain these from your Vonage Dashboard after creating a Video-enabled application.
VONAGE_APPLICATION_ID = os.environ.get('VONAGE_APPLICATION_ID', 'YOUR_APPLICATION_ID')
VONAGE_PRIVATE_KEY_PATH = os.environ.get('VONAGE_PRIVATE_KEY_PATH', 'path/to/your/private.key')

if VONAGE_APPLICATION_ID == 'YOUR_APPLICATION_ID' or not os.path.exists(VONAGE_PRIVATE_KEY_PATH):
    print("Please set VONAGE_APPLICATION_ID environment variable and VONAGE_PRIVATE_KEY_PATH, and ensure the private key file exists.")
    print("Refer to https://developer.vonage.com/en/messages/application/create for creating an application.")
else:
    try:
        auth = Auth(
            application_id=VONAGE_APPLICATION_ID,
            private_key=VONAGE_PRIVATE_KEY_PATH,
        )
        client = Vonage(auth=auth)

        # Create a session
        session_options = SessionOptions(media_mode=MediaMode.ROUTED)
        session = client.video.create_session(session_options)
        session_id = session.session_id
        print(f"Created Session ID: {session_id}")

        # Generate a token for a client to connect to the session
        token = client.video.generate_client_token(session_id)
        print(f"Generated Client Token: {token}")

    except Exception as e:
        print(f"An error occurred: {e}")

view raw JSON →