{"id":503,"library":"google-cloud-videointelligence","title":"Google Cloud Video Intelligence","description":"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.","status":"active","version":"2.19.0","language":"python","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-videointelligence","tags":["google-cloud","video","ai","ml","computer-vision"],"install":[{"cmd":"pip install google-cloud-videointelligence","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required Python version.","package":"Python","version":">=3.9","optional":false}],"imports":[{"symbol":"VideoIntelligenceServiceClient","correct":"from google.cloud import videointelligence_v1 as videointelligence"},{"symbol":"Feature","correct":"from google.cloud.videointelligence_v1 import Feature"},{"symbol":"LabelDetectionConfig","correct":"from google.cloud.videointelligence_v1 import LabelDetectionConfig"},{"symbol":"LabelDetectionMode","correct":"from google.cloud.videointelligence_v1 import LabelDetectionMode"}],"quickstart":{"code":"import os\nfrom google.cloud import videointelligence_v1 as videointelligence\n\n# Set GOOGLE_APPLICATION_CREDENTIALS environment variable or ensure gcloud is authenticated.\n# For local development, run `gcloud auth application-default login`.\n# os.environ['GOOGLE_APPLICATION_CREDENTIALS'] = 'path/to/your/key.json'\n\ndef analyze_video_labels(gcs_uri):\n    \"\"\"Detects labels in the video specified by the GCS URI.\"\"\"\n    client = videointelligence.VideoIntelligenceServiceClient()\n    features = [videointelligence.Feature.LABEL_DETECTION]\n\n    # Optional: Configure label detection mode for more granular control\n    config = videointelligence.LabelDetectionConfig(\n        label_detection_mode=videointelligence.LabelDetectionMode.SHOT_AND_FRAME_MODE,\n        stationary_camera=False # Set to True if analyzing footage from a stationary camera\n    )\n    video_context = videointelligence.VideoContext(label_detection_config=config)\n\n    print(f'Processing video for label annotations: {gcs_uri}')\n    operation = client.annotate_video(\n        request={\n            \"input_uri\": gcs_uri,\n            \"features\": features,\n            \"video_context\": video_context\n        }\n    )\n\n    # Long-running operations must be waited for.\n    print('\\nWaiting for operation to complete...')\n    result = operation.result(timeout=600)  # Adjust timeout as needed (in seconds)\n\n    print('\\nFinished processing.')\n    # First result is retrieved because a single video is processed\n    annotation_result = result.annotation_results[0]\n\n    for i, shot_label in enumerate(annotation_result.shot_label_annotations):\n        print(f'Video shot label: {shot_label.entity.description} ({shot_label.entity.entity_id})')\n        for segment in shot_label.segments:\n            start_time = (segment.segment.start_time_offset.seconds + \n                          segment.segment.start_time_offset.nanos / 1e9)\n            end_time = (segment.segment.end_time_offset.seconds + \n                        segment.segment.end_time_offset.nanos / 1e9)\n            print(f'\\tSegment: {start_time:.1f}s to {end_time:.1f}s (confidence: {segment.confidence:.2f})')\n\n    for i, frame_label in enumerate(annotation_result.frame_label_annotations):\n        print(f'Video frame label: {frame_label.entity.description} ({frame_label.entity.entity_id})')\n        for frame in frame_label.frames:\n            time_offset = (frame.time_offset.seconds + \n                           frame.time_offset.nanos / 1e9)\n            print(f'\\tFrame: {time_offset:.1f}s (confidence: {frame.confidence:.2f})')\n\nif __name__ == '__main__':\n    # Replace with your GCS video URI\n    # Public sample video from Google Cloud documentation\n    video_uri = \"gs://cloud-samples-data/video/chicago.mp4\"\n    analyze_video_labels(video_uri)\n","lang":"python","description":"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."},"warnings":[{"fix":"Use `gcloud auth application-default login` or set `os.environ['GOOGLE_APPLICATION_CREDENTIALS']`.","message":"Authentication is critical. Ensure your environment is correctly authenticated, typically via Application Default Credentials. For local development, `gcloud auth application-default login` is recommended, or explicitly setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable to a service account key file path.","severity":"gotcha","affected_versions":"All versions"},{"fix":"After calling an asynchronous client method (e.g., `client.annotate_video()`), store the returned value as an `operation` and then call `result = operation.result(timeout=...)`.","message":"Most video annotation operations are asynchronous and return a `google.api_core.operation.Operation` object. You must explicitly call `.result()` on this operation object and wait for its completion to retrieve the actual API response. Failure to do so will result in an `Operation` object, not the annotation results.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always import specific API versions (e.g., `from google.cloud import videointelligence_v1 as videointelligence`) and consult the documentation for the features supported by that version.","message":"The Video Intelligence API has different versions (e.g., `v1`, `v1p1beta1`). Ensure you import the correct version (e.g., `videointelligence_v1`) and use features available in that specific version. Beta features may not be stable or present in the stable API.","severity":"gotcha","affected_versions":"All versions"},{"fix":"If consistent results are critical, consider explicitly setting the `model` field in the `LabelDetectionConfig` or `ShotChangeDetectionConfig` to `builtin/stable`. Monitor release notes for model updates and deprecations.","message":"For features like `LABEL_DETECTION` and `SHOT_CHANGE_DETECTION`, you can specify different underlying models (e.g., `builtin/stable`, `builtin/latest`). Google may update or deprecate these models, which could lead to changes in detection results over time if not explicitly pinned or monitored.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Restrict access to stored logs. Do not rely on specific log message formats or contents for application logic.","message":"The library's logging events (when enabled via `GOOGLE_SDK_PYTHON_LOGGING_SCOPE`) may contain sensitive information. Google may also refine the occurrence, level, and content of log messages without flagging such changes as breaking. Do not depend on the immutability of logging events or store sensitive data in logs without proper access restrictions.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T14:26:43.431Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"For 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.","cause":"This error occurs when the video processing time exceeds the default or configured timeout limit, often with longer videos or complex analysis features.","error":"google.api_core.exceptions.RetryError: Timeout of 600.0s exceeded, last exception: 504 Deadline Exceeded"},{"fix":"Ensure 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.","cause":"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.","error":"PERMISSION_DENIED: The caller does not have permission"},{"fix":"Ensure 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.","cause":"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.","error":"Request contains an invalid argument."},{"fix":"Install 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.","cause":"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.","error":"ModuleNotFoundError: No module named 'google.cloud.videointelligence'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.68,"mem_mb":23.8,"disk_size":"68.7M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.05,"mem_mb":20.4,"disk_size":"66M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.45,"mem_mb":25.7,"disk_size":"73.3M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.51,"mem_mb":22.6,"disk_size":"71M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.4,"mem_mb":25,"disk_size":"64.8M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.92,"mem_mb":21.9,"disk_size":"63M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":2.36,"mem_mb":26,"disk_size":"64.4M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.99,"mem_mb":22.8,"disk_size":"62M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.49,"mem_mb":23.6,"disk_size":"68.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":1.17,"mem_mb":20.2,"disk_size":"67M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}