Registry /
gcp / google-cloud-videointelligence
The Google Cloud Video Intelligence API Python client library (current version 2.19.0) enables developers to analyze video content by detecting objects, scenes, activities, and transcribing speech. It provides capabilities to extract metadata, such as labels, shot changes, explicit content, and more, from videos stored in Google Cloud Storage or provided as data bytes. The library is actively maintained with frequent updates as part of the larger `google-cloud-python` ecosystem.
Install & Compatibility
Where this runs
tested against v2.19.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 2.033s · 69.8MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 5.5s · import 1.495s · 68MB
68MB installed
● package 68MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
VideoIntelligenceServiceClient
✓ from google.cloud import videointelligence_v1 as videointelligence
Feature
✓ from google.cloud.videointelligence_v1 import Feature
LabelDetectionConfig
✓ from google.cloud.videointelligence_v1 import LabelDetectionConfig
LabelDetectionMode
✓ from google.cloud.videointelligence_v1 import LabelDetectionMode
This quickstart demonstrates how to use the `google-cloud-videointelligence` client library to detect labels within a video stored in Google Cloud Storage. It initializes the client, configures label detection, sends an annotation request, and waits for the long-running operation to complete, then prints the detected labels.
import os
from google.cloud import videointelligence_v1 as videointelligence
# Set GOOGLE_APPLICATION_CREDENTIALS environment variable or ensure gcloud is authenticated.
# For local development, run `gcloud auth application-default login`.
# os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'path/to/your/key.json'
def analyze_video_labels(gcs_uri):
"""Detects labels in the video specified by the GCS URI."""
client = videointelligence.VideoIntelligenceServiceClient()
features = [videointelligence.Feature.LABEL_DETECTION]
# Optional: Configure label detection mode for more granular control
config = videointelligence.LabelDetectionConfig(
label_detection_mode=videointelligence.LabelDetectionMode.SHOT_AND_FRAME_MODE,
stationary_camera=False # Set to True if analyzing footage from a stationary camera
)
video_context = videointelligence.VideoContext(label_detection_config=config)
print(f'Processing video for label annotations: {gcs_uri}')
operation = client.annotate_video(
request={
"input_uri": gcs_uri,
"features": features,
"video_context": video_context
}
)
# Long-running operations must be waited for.
print('\nWaiting for operation to complete...')
result = operation.result(timeout=600) # Adjust timeout as needed (in seconds)
print('\nFinished processing.')
# First result is retrieved because a single video is processed
annotation_result = result.annotation_results[0]
for i, shot_label in enumerate(annotation_result.shot_label_annotations):
print(f'Video shot label: {shot_label.entity.description} ({shot_label.entity.entity_id})')
for segment in shot_label.segments:
start_time = (segment.segment.start_time_offset.seconds +
segment.segment.start_time_offset.nanos / 1e9)
end_time = (segment.segment.end_time_offset.seconds +
segment.segment.end_time_offset.nanos / 1e9)
print(f'\tSegment: {start_time:.1f}s to {end_time:.1f}s (confidence: {segment.confidence:.2f})')
for i, frame_label in enumerate(annotation_result.frame_label_annotations):
print(f'Video frame label: {frame_label.entity.description} ({frame_label.entity.entity_id})')
for frame in frame_label.frames:
time_offset = (frame.time_offset.seconds +
frame.time_offset.nanos / 1e9)
print(f'\tFrame: {time_offset:.1f}s (confidence: {frame.confidence:.2f})')
if __name__ == '__main__':
# Replace with your GCS video URI
# Public sample video from Google Cloud documentation
video_uri = "gs://cloud-samples-data/video/chicago.mp4"
analyze_video_labels(video_uri)
Errors
Common errors & fixes
google.api_core.exceptions.RetryError: Timeout of 600.0s exceeded, last exception: 504 Deadline Exceeded
This error occurs when the video processing time exceeds the default or configured timeout limit, often with longer videos or complex analysis features.
fixFor longer videos, upload the video to Google Cloud Storage and use `input_uri` instead of `input_content`. If using `input_uri`, increase the `timeout` parameter in the `operation.result()` call or split the video into smaller segments.
PERMISSION_DENIED: The caller does not have permission
This error indicates that the Google Cloud service account or user credentials used by your application lack the necessary IAM permissions to access the Video Intelligence API or the Google Cloud Storage bucket containing the video.
fixEnsure the service account has the 'Cloud Video Intelligence User' role and 'Storage Object Viewer' (or similar read) permissions on the relevant GCS bucket. Also, verify that the Video Intelligence API is enabled in your Google Cloud project.
Request contains an invalid argument.
This often happens when the `input_uri` for the video is in an incorrect format (e.g., `https://` instead of `gs://`) or when `input_content` is used for a video that should be in Cloud Storage.
fixEnsure that video URIs are in the `gs://bucket-id/object-id` format for videos in Google Cloud Storage. If passing video bytes directly, use the `input_content` parameter and ensure `input_uri` is not set.
ModuleNotFoundError: No module named 'google.cloud.videointelligence'
This error typically occurs when the `google-cloud-videointelligence` library is not installed or the Python environment is not correctly configured to find the installed packages.
fixInstall the library using pip: `pip install google-cloud-videointelligence`. If already installed, ensure you are running your script within the correct Python virtual environment where the library was installed.
Audit
Dependencies
PythonrequiredRequired Python version.