检测人脸

Video Intelligence API 人脸检测功能会查找视频中的人脸。

通过 Cloud Storage 中的文件进行人脸检测

以下示例演示了如何对 Cloud Storage 中的文件执行人脸检测。

REST

发送视频注释请求

下面演示了如何向 videos:annotate 方法发送 POST 请求。该示例使用 Google Cloud CLI 创建访问令牌。对于 有关安装 gcloud CLI 的说明，请参阅 Video Intelligence API 快速入门。

在使用任何请求数据之前，请先进行以下替换：

  • INPUT_URI：包含要添加注释的文件的 Cloud Storage 存储分区（包括文件名）。必须以 gs:// 开头。
    例如：`"inputUri": "gs://cloud-samples-data/video/googlework_short.mp4"`
  • PROJECT_NUMBER：您的 Google Cloud 项目的数字标识符

HTTP 方法和网址：

POST https://videointelligence.googleapis.com/v1/videos:annotate

请求 JSON 正文：

{
    "inputUri": "INPUT_URI",
    "features": ["FACE_DETECTION"]
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

如果响应成功，Video Intelligence API 将返回您的操作的 name。上面显示了此类响应的示例，其中：

  • PROJECT_NUMBER：您项目的编号
  • LOCATION_ID：在其中添加注释的 Cloud 区域。支持的云区域为：us-east1、us-west1、europe-west1、asia-east1。如果未指定地区，则根据视频文件位置来确定地区。
  • OPERATION_ID：是为请求创建的长时间运行的操作的 ID，并在启动操作时在响应中提供，例如 12345...

获取注释结果

要检索操作的结果，请使用从 videos：annotate 调用返回的操作名称发出 GET 请求，如以下示例所示。

在使用任何请求数据之前，请先进行以下替换：

  • OPERATION_NAME：Video Intelligence API 返回的操作名称。操作名称采用 projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID 格式
  • PROJECT_NUMBER：您的 Google Cloud 项目的数字标识符

HTTP 方法和网址：

GET https://videointelligence.googleapis.com/v1/OPERATION_NAME

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

人脸检测注释以 faceAnnotations 列表的形式返回。注意：仅当值为 True 时，才会返回 done 字段。该操作不会包含在操作未完成的响应中。

Java

如需向 Video Intelligence 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.videointelligence.v1.AnnotateVideoProgress;
import com.google.cloud.videointelligence.v1.AnnotateVideoRequest;
import com.google.cloud.videointelligence.v1.AnnotateVideoResponse;
import com.google.cloud.videointelligence.v1.DetectedAttribute;
import com.google.cloud.videointelligence.v1.FaceDetectionAnnotation;
import com.google.cloud.videointelligence.v1.FaceDetectionConfig;
import com.google.cloud.videointelligence.v1.Feature;
import com.google.cloud.videointelligence.v1.TimestampedObject;
import com.google.cloud.videointelligence.v1.Track;
import com.google.cloud.videointelligence.v1.VideoAnnotationResults;
import com.google.cloud.videointelligence.v1.VideoContext;
import com.google.cloud.videointelligence.v1.VideoIntelligenceServiceClient;
import com.google.cloud.videointelligence.v1.VideoSegment;

public class DetectFacesGcs {

  public static void detectFacesGcs() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String gcsUri = "gs://cloud-samples-data/video/googlework_short.mp4";
    detectFacesGcs(gcsUri);
  }

  // Detects faces in a video stored in Google Cloud Storage using the Cloud Video Intelligence API.
  public static void detectFacesGcs(String gcsUri) throws Exception {
    try (VideoIntelligenceServiceClient videoIntelligenceServiceClient =
        VideoIntelligenceServiceClient.create()) {

      FaceDetectionConfig faceDetectionConfig =
          FaceDetectionConfig.newBuilder()
              // Must set includeBoundingBoxes to true to get facial attributes.
              .setIncludeBoundingBoxes(true)
              .setIncludeAttributes(true)
              .build();
      VideoContext videoContext =
          VideoContext.newBuilder().setFaceDetectionConfig(faceDetectionConfig).build();

      AnnotateVideoRequest request =
          AnnotateVideoRequest.newBuilder()
              .setInputUri(gcsUri)
              .addFeatures(Feature.FACE_DETECTION)
              .setVideoContext(videoContext)
              .build();

      // Detects faces in a video
      OperationFuture<AnnotateVideoResponse, AnnotateVideoProgress> future =
          videoIntelligenceServiceClient.annotateVideoAsync(request);

      System.out.println("Waiting for operation to complete...");
      AnnotateVideoResponse response = future.get();

      // Gets annotations for video
      VideoAnnotationResults annotationResult = response.getAnnotationResultsList().get(0);

      // Annotations for list of people detected, tracked and recognized in video.
      for (FaceDetectionAnnotation faceDetectionAnnotation :
          annotationResult.getFaceDetectionAnnotationsList()) {
        System.out.print("Face detected:\n");
        for (Track track : faceDetectionAnnotation.getTracksList()) {
          VideoSegment segment = track.getSegment();
          System.out.printf(
              "\tStart: %d.%.0fs\n",
              segment.getStartTimeOffset().getSeconds(),
              segment.getStartTimeOffset().getNanos() / 1e6);
          System.out.printf(
              "\tEnd: %d.%.0fs\n",
              segment.getEndTimeOffset().getSeconds(), segment.getEndTimeOffset().getNanos() / 1e6);

          // Each segment includes timestamped objects that
          // include characteristics of the face detected.
          TimestampedObject firstTimestampedObject = track.getTimestampedObjects(0);

          for (DetectedAttribute attribute : firstTimestampedObject.getAttributesList()) {
            // Attributes include glasses, headwear, smiling, direction of gaze
            System.out.printf(
                "\tAttribute %s: %s %s\n",
                attribute.getName(), attribute.getValue(), attribute.getConfidence());
          }
        }
      }
    }
  }
}

Node.js

如需向 Video Intelligence 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const gcsUri = 'GCS URI of the video to analyze, e.g. gs://my-bucket/my-video.mp4';

// Imports the Google Cloud Video Intelligence library + Node's fs library
const Video = require('@google-cloud/video-intelligence').v1;

// Creates a client
const video = new Video.VideoIntelligenceServiceClient();

async function detectFacesGCS() {
  const request = {
    inputUri: gcsUri,
    features: ['FACE_DETECTION'],
    videoContext: {
      faceDetectionConfig: {
        // Must set includeBoundingBoxes to true to get facial attributes.
        includeBoundingBoxes: true,
        includeAttributes: true,
      },
    },
  };
  // Detects faces in a video
  // We get the first result because we only process 1 video
  const [operation] = await video.annotateVideo(request);
  const results = await operation.promise();
  console.log('Waiting for operation to complete...');

  // Gets annotations for video
  const faceAnnotations =
    results[0].annotationResults[0].faceDetectionAnnotations;

  for (const {tracks} of faceAnnotations) {
    console.log('Face detected:');

    for (const {segment, timestampedObjects} of tracks) {
      console.log(
        `\tStart: ${segment.startTimeOffset.seconds}.` +
          `${(segment.startTimeOffset.nanos / 1e6).toFixed(0)}s`
      );
      console.log(
        `\tEnd: ${segment.endTimeOffset.seconds}.` +
          `${(segment.endTimeOffset.nanos / 1e6).toFixed(0)}s`
      );

      // Each segment includes timestamped objects that
      // include characteristics of the face detected.
      const [firstTimestapedObject] = timestampedObjects;

      for (const {name} of firstTimestapedObject.attributes) {
        // Attributes include 'glasses', 'headwear', 'smiling'.
        console.log(`\tAttribute: ${name}; `);
      }
    }
  }
}

detectFacesGCS();

Python

如需向 Video Intelligence 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

from google.cloud import videointelligence_v1 as videointelligence


def detect_faces(gcs_uri="gs://YOUR_BUCKET_ID/path/to/your/video.mp4"):
    """Detects faces in a video."""

    client = videointelligence.VideoIntelligenceServiceClient()

    # Configure the request
    config = videointelligence.FaceDetectionConfig(
        include_bounding_boxes=True, include_attributes=True
    )
    context = videointelligence.VideoContext(face_detection_config=config)

    # Start the asynchronous request
    operation = client.annotate_video(
        request={
            "features": [videointelligence.Feature.FACE_DETECTION],
            "input_uri": gcs_uri,
            "video_context": context,
        }
    )

    print("\nProcessing video for face detection annotations.")
    result = operation.result(timeout=300)

    print("\nFinished processing.\n")

    # Retrieve the first result, because a single video was processed.
    annotation_result = result.annotation_results[0]

    for annotation in annotation_result.face_detection_annotations:
        print("Face detected:")
        for track in annotation.tracks:
            print(
                "Segment: {}s to {}s".format(
                    track.segment.start_time_offset.seconds
                    + track.segment.start_time_offset.microseconds / 1e6,
                    track.segment.end_time_offset.seconds
                    + track.segment.end_time_offset.microseconds / 1e6,
                )
            )

            # Each segment includes timestamped faces that include
            # characteristics of the face detected.
            # Grab the first timestamped face
            timestamped_object = track.timestamped_objects[0]
            box = timestamped_object.normalized_bounding_box
            print("Bounding box:")
            print("\tleft  : {}".format(box.left))
            print("\ttop   : {}".format(box.top))
            print("\tright : {}".format(box.right))
            print("\tbottom: {}".format(box.bottom))

            # Attributes include glasses, headwear, smiling, direction of gaze
            print("Attributes:")
            for attribute in timestamped_object.attributes:
                print(
                    "\t{}:{} {}".format(
                        attribute.name, attribute.value, attribute.confidence
                    )
                )

其他语言

C#： 请遵循 C# 设置说明 在客户端库页面上 然后访问 适用于 .NET 的 Video Intelligence 参考文档。

PHP： 请遵循 PHP 设置说明 在客户端库页面上 然后访问 适用于 PHP 的 Video Intelligence 参考文档。

Ruby： 请遵循 Ruby 设置说明 在客户端库页面上 然后访问 Ruby 版 Video Intelligence 参考文档。

从本地文件进行人脸检测

以下示例使用人脸检测从本地机器上传的视频文件中查找视频中的实体。

REST

发送处理请求

要对本地视频文件执行人脸检测，请对视频文件的内容进行 base64 编码。如需了解如何对视频文件的内容进行 base64 编码，请参阅 Base64 编码。然后，向 videos:annotate 方法发出 POST 请求。在请求的 inputContent 字段中添加 base64 编码的内容，并指定 FACE_DETECTION 功能。

以下示例展示了使用 curl 的 POST 请求。该示例使用 Google Cloud CLI 创建访问令牌。有关安装 gcloud CLI，请参阅 Video Intelligence API 快速入门

在使用任何请求数据之前，请先进行以下替换：

  • inputContent: 二进制文件格式的本地视频文件
    ，例如：AAAAGGZ0eXBtcDQyAAAAAGlzb21tcDQyAAGVYW1vb3YAAABsbXZoZAAAAADWvhlR1r4ZUQABX5ABCOxoAAEAAAEAAAAAAA4
  • PROJECT_NUMBER：您的 Google Cloud 项目的数字标识符

HTTP 方法和网址：

POST https://videointelligence.googleapis.com/v1/videos:annotate

请求 JSON 正文：

{
    inputContent: "Local video file in binary format",
    "features": ["FACE_DETECTION"]
}

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

如果请求成功，则 Video Intelligence 会为您的操作分配 name。上面的示例展示了此类响应的示例，其中 project-number 是您的项目编号，operation-id 是为请求创建的长时间运行的操作的 ID。

{ "name": "us-west1.17122464255125931980" }

获取结果

要检索操作结果，请向 operations 端点发送 GET 请求并指定操作名称。

在使用任何请求数据之前，请先进行以下替换：

  • OPERATION_NAME：Video Intelligence API 返回的操作名称。操作名称采用 projects/PROJECT_NUMBER/locations/LOCATION_ID/operations/OPERATION_ID 格式
  • PROJECT_NUMBER：您的 Google Cloud 项目的数字标识符

HTTP 方法和网址：

GET https://videointelligence.googleapis.com/v1/OPERATION_NAME

如需发送您的请求，请展开以下选项之一：

您应该收到类似以下内容的 JSON 响应：

Java

如需向 Video Intelligence 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 


import com.google.api.gax.longrunning.OperationFuture;
import com.google.cloud.videointelligence.v1.AnnotateVideoProgress;
import com.google.cloud.videointelligence.v1.AnnotateVideoRequest;
import com.google.cloud.videointelligence.v1.AnnotateVideoResponse;
import com.google.cloud.videointelligence.v1.DetectedAttribute;
import com.google.cloud.videointelligence.v1.FaceDetectionAnnotation;
import com.google.cloud.videointelligence.v1.FaceDetectionConfig;
import com.google.cloud.videointelligence.v1.Feature;
import com.google.cloud.videointelligence.v1.TimestampedObject;
import com.google.cloud.videointelligence.v1.Track;
import com.google.cloud.videointelligence.v1.VideoAnnotationResults;
import com.google.cloud.videointelligence.v1.VideoContext;
import com.google.cloud.videointelligence.v1.VideoIntelligenceServiceClient;
import com.google.cloud.videointelligence.v1.VideoSegment;
import com.google.protobuf.ByteString;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.Paths;

public class DetectFaces {

  public static void detectFaces() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String localFilePath = "resources/googlework_short.mp4";
    detectFaces(localFilePath);
  }

  // Detects faces in a video stored in a local file using the Cloud Video Intelligence API.
  public static void detectFaces(String localFilePath) throws Exception {
    try (VideoIntelligenceServiceClient videoIntelligenceServiceClient =
        VideoIntelligenceServiceClient.create()) {
      // Reads a local video file and converts it to base64.
      Path path = Paths.get(localFilePath);
      byte[] data = Files.readAllBytes(path);
      ByteString inputContent = ByteString.copyFrom(data);

      FaceDetectionConfig faceDetectionConfig =
          FaceDetectionConfig.newBuilder()
              // Must set includeBoundingBoxes to true to get facial attributes.
              .setIncludeBoundingBoxes(true)
              .setIncludeAttributes(true)
              .build();
      VideoContext videoContext =
          VideoContext.newBuilder().setFaceDetectionConfig(faceDetectionConfig).build();

      AnnotateVideoRequest request =
          AnnotateVideoRequest.newBuilder()
              .setInputContent(inputContent)
              .addFeatures(Feature.FACE_DETECTION)
              .setVideoContext(videoContext)
              .build();

      // Detects faces in a video
      OperationFuture<AnnotateVideoResponse, AnnotateVideoProgress> future =
          videoIntelligenceServiceClient.annotateVideoAsync(request);

      System.out.println("Waiting for operation to complete...");
      AnnotateVideoResponse response = future.get();

      // Gets annotations for video
      VideoAnnotationResults annotationResult = response.getAnnotationResultsList().get(0);

      // Annotations for list of faces detected, tracked and recognized in video.
      for (FaceDetectionAnnotation faceDetectionAnnotation :
          annotationResult.getFaceDetectionAnnotationsList()) {
        System.out.print("Face detected:\n");
        for (Track track : faceDetectionAnnotation.getTracksList()) {
          VideoSegment segment = track.getSegment();
          System.out.printf(
              "\tStart: %d.%.0fs\n",
              segment.getStartTimeOffset().getSeconds(),
              segment.getStartTimeOffset().getNanos() / 1e6);
          System.out.printf(
              "\tEnd: %d.%.0fs\n",
              segment.getEndTimeOffset().getSeconds(), segment.getEndTimeOffset().getNanos() / 1e6);

          // Each segment includes timestamped objects that
          // include characteristics of the face detected.
          TimestampedObject firstTimestampedObject = track.getTimestampedObjects(0);

          for (DetectedAttribute attribute : firstTimestampedObject.getAttributesList()) {
            // Attributes include glasses, headwear, smiling, direction of gaze
            System.out.printf(
                "\tAttribute %s: %s %s\n",
                attribute.getName(), attribute.getValue(), attribute.getConfidence());
          }
        }
      }
    }
  }
}

Node.js

如需向 Video Intelligence 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

/**
 * TODO(developer): Uncomment these variables before running the sample.
 */
// const path = 'Local file to analyze, e.g. ./my-file.mp4';

// Imports the Google Cloud Video Intelligence library + Node's fs library
const Video = require('@google-cloud/video-intelligence').v1;
const fs = require('fs');

// Creates a client
const video = new Video.VideoIntelligenceServiceClient();

// Reads a local video file and converts it to base64
const file = fs.readFileSync(path);
const inputContent = file.toString('base64');

async function detectFaces() {
  const request = {
    inputContent: inputContent,
    features: ['FACE_DETECTION'],
    videoContext: {
      faceDetectionConfig: {
        // Must set includeBoundingBoxes to true to get facial attributes.
        includeBoundingBoxes: true,
        includeAttributes: true,
      },
    },
  };
  // Detects faces in a video
  // We get the first result because we only process 1 video
  const [operation] = await video.annotateVideo(request);
  const results = await operation.promise();
  console.log('Waiting for operation to complete...');

  // Gets annotations for video
  const faceAnnotations =
    results[0].annotationResults[0].faceDetectionAnnotations;
  for (const {tracks} of faceAnnotations) {
    console.log('Face detected:');
    for (const {segment, timestampedObjects} of tracks) {
      console.log(
        `\tStart: ${segment.startTimeOffset.seconds}` +
          `.${(segment.startTimeOffset.nanos / 1e6).toFixed(0)}s`
      );
      console.log(
        `\tEnd: ${segment.endTimeOffset.seconds}.` +
          `${(segment.endTimeOffset.nanos / 1e6).toFixed(0)}s`
      );

      // Each segment includes timestamped objects that
      // include characteristics of the face detected.
      const [firstTimestapedObject] = timestampedObjects;

      for (const {name} of firstTimestapedObject.attributes) {
        // Attributes include 'glasses', 'headwear', 'smiling'.
        console.log(`\tAttribute: ${name}; `);
      }
    }
  }
}

detectFaces();

Python

如需向 Video Intelligence 进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。 

import io

from google.cloud import videointelligence_v1 as videointelligence


def detect_faces(local_file_path="path/to/your/video-file.mp4"):
    """Detects faces in a video from a local file."""

    client = videointelligence.VideoIntelligenceServiceClient()

    with io.open(local_file_path, "rb") as f:
        input_content = f.read()

    # Configure the request
    config = videointelligence.FaceDetectionConfig(
        include_bounding_boxes=True, include_attributes=True
    )
    context = videointelligence.VideoContext(face_detection_config=config)

    # Start the asynchronous request
    operation = client.annotate_video(
        request={
            "features": [videointelligence.Feature.FACE_DETECTION],
            "input_content": input_content,
            "video_context": context,
        }
    )

    print("\nProcessing video for face detection annotations.")
    result = operation.result(timeout=300)

    print("\nFinished processing.\n")

    # Retrieve the first result, because a single video was processed.
    annotation_result = result.annotation_results[0]

    for annotation in annotation_result.face_detection_annotations:
        print("Face detected:")
        for track in annotation.tracks:
            print(
                "Segment: {}s to {}s".format(
                    track.segment.start_time_offset.seconds
                    + track.segment.start_time_offset.microseconds / 1e6,
                    track.segment.end_time_offset.seconds
                    + track.segment.end_time_offset.microseconds / 1e6,
                )
            )

            # Each segment includes timestamped faces that include
            # characteristics of the face detected.
            # Grab the first timestamped face
            timestamped_object = track.timestamped_objects[0]
            box = timestamped_object.normalized_bounding_box
            print("Bounding box:")
            print("\tleft  : {}".format(box.left))
            print("\ttop   : {}".format(box.top))
            print("\tright : {}".format(box.right))
            print("\tbottom: {}".format(box.bottom))

            # Attributes include glasses, headwear, smiling, direction of gaze
            print("Attributes:")
            for attribute in timestamped_object.attributes:
                print(
                    "\t{}:{} {}".format(
                        attribute.name, attribute.value, attribute.confidence
                    )
                )

其他语言

C#： 请遵循 C# 设置说明 在客户端库页面上 然后访问 适用于 .NET 的 Video Intelligence 参考文档。

PHP： 请遵循 PHP 设置说明 在客户端库页面上 然后访问 适用于 PHP 的 Video Intelligence 参考文档。

Ruby： 请遵循 Ruby 设置说明 在客户端库页面上 然后访问 Ruby 版 Video Intelligence 参考文档。