偵測臉部

臉部偵測功能可偵測圖片中的多個臉部，以及相關的重要臉部特徵，例如表情或wearing headwear。

不支援臉部辨識特定個人。

歡迎試用

如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用 Cloud Vision API 的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

免費試用 Cloud Vision API

臉部偵測要求

設定 Google Cloud 專案和驗證

偵測本機圖片中的臉孔

您可以使用 Vision API 對本機圖片檔執行特徵偵測。

如果是 REST 要求，請在要求主體中，以 base64 編碼字串的形式傳送圖片檔案內容。

如果是 gcloud 和用戶端程式庫要求，請在要求中指定本機圖片的路徑。

REST

使用任何要求資料之前，請先修改下列項目的值：

  • BASE64_ENCODED_IMAGE：二進位圖片資料的 Base64 表示法 (ASCII 字串)。這個字串應類似下列字串：
    • /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==
    詳情請參閱「base64 編碼」主題。
  • RESULTS_INT：(選填) 要傳回的結果整數值。如果省略 "maxResults" 欄位及其值，API 會傳回預設值，也就是 10 個結果。這個欄位不適用於下列特徵類型：TEXT_DETECTION、DOCUMENT_TEXT_DETECTION 或 CROP_HINTS。
  • PROJECT_ID： Google Cloud 專案 ID。

HTTP 方法和網址：

POST https://vision.googleapis.com/v1/images:annotate

JSON 要求內文：

{
  "requests": [
    {
      "image": {
        "content": "BASE64_ENCODED_IMAGE"
      },
      "features": [
        {
          "maxResults": RESULTS_INT,
          "type": "FACE_DETECTION"
        }
      ]
    }
  ]
}

如要傳送要求，請選擇以下其中一個選項：

curl

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "x-goog-user-project: PROJECT_ID" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vision.googleapis.com/v1/images:annotate"

PowerShell

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vision.googleapis.com/v1/images:annotate" | Select-Object -Expand Content

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼與 JSON 格式的回應。

FACE_DETECTION 回應包含所有偵測到的臉部定界框、臉部偵測到的地標 (眼睛、鼻子、嘴巴等)，以及臉部和圖片屬性 (喜、悲、怒、驚訝等) 的可信度評分。

Go

在試用這個範例之前，請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Go 設定說明操作。詳情請參閱 Vision Go API 參考文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


// detectFaces gets faces from the Vision API for an image at the given file path.
func detectFaces(w io.Writer, file string) error {
	ctx := context.Background()

	client, err := vision.NewImageAnnotatorClient(ctx)
	if err != nil {
		return err
	}
	defer client.Close()

	f, err := os.Open(file)
	if err != nil {
		return err
	}
	defer f.Close()

	image, err := vision.NewImageFromReader(f)
	if err != nil {
		return err
	}
	annotations, err := client.DetectFaces(ctx, image, nil, 10)
	if err != nil {
		return err
	}
	if len(annotations) == 0 {
		fmt.Fprintln(w, "No faces found.")
	} else {
		fmt.Fprintln(w, "Faces:")
		for i, annotation := range annotations {
			fmt.Fprintln(w, "  Face", i)
			fmt.Fprintln(w, "    Anger:", annotation.AngerLikelihood)
			fmt.Fprintln(w, "    Joy:", annotation.JoyLikelihood)
			fmt.Fprintln(w, "    Surprise:", annotation.SurpriseLikelihood)
		}
	}
	return nil
}

Java

在試用這個範例之前，請先按照使用用戶端程式庫的 Vision API 快速入門導覽課程中的 Java 設定操作說明進行操作。詳情請參閱 Vision API Java 參考文件。


import com.google.cloud.vision.v1.AnnotateImageRequest;
import com.google.cloud.vision.v1.AnnotateImageResponse;
import com.google.cloud.vision.v1.BatchAnnotateImagesResponse;
import com.google.cloud.vision.v1.FaceAnnotation;
import com.google.cloud.vision.v1.Feature;
import com.google.cloud.vision.v1.Image;
import com.google.cloud.vision.v1.ImageAnnotatorClient;
import com.google.protobuf.ByteString;
import java.io.FileInputStream;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;

public class DetectFaces {

  public static void detectFaces() throws IOException {
    // TODO(developer): Replace these variables before running the sample.
    String filePath = "path/to/your/image/file.jpg";
    detectFaces(filePath);
  }

  // Detects faces in the specified local image.
  public static void detectFaces(String filePath) throws IOException {
    List<AnnotateImageRequest> requests = new ArrayList<>();

    ByteString imgBytes = ByteString.readFrom(new FileInputStream(filePath));

    Image img = Image.newBuilder().setContent(imgBytes).build();
    Feature feat = Feature.newBuilder().setType(Feature.Type.FACE_DETECTION).build();
    AnnotateImageRequest request =
        AnnotateImageRequest.newBuilder().addFeatures(feat).setImage(img).build();
    requests.add(request);

    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the "close" method on the client to safely clean up any remaining background resources.
    try (ImageAnnotatorClient client = ImageAnnotatorClient.create()) {
      BatchAnnotateImagesResponse response = client.batchAnnotateImages(requests);
      List<AnnotateImageResponse> responses = response.getResponsesList();

      for (AnnotateImageResponse res : responses) {
        if (res.hasError()) {
          System.out.format("Error: %s%n", res.getError().getMessage());
          return;
        }

        // For full list of available annotations, see http://g.co/cloud/vision/docs
        for (FaceAnnotation annotation : res.getFaceAnnotationsList()) {
          System.out.format(
              "anger: %s%njoy: %s%nsurprise: %s%nposition: %s",
              annotation.getAngerLikelihood(),
              annotation.getJoyLikelihood(),
              annotation.getSurpriseLikelihood(),
              annotation.getBoundingPoly());
        }
      }
    }
  }
}

Node.js

在試用這個範例之前，請先按照「使用用戶端程式庫的 Vision 快速入門導覽課程」中的 Node.js 設定說明操作。詳情請參閱 Vision Node.js API 參考文件。

如要向 Vision 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

// Imports the Google Cloud client library
const vision = require('@google-cloud/vision');

// Creates a client
const client = new vision.ImageAnnotatorClient();

async function detectFaces() {
  /**
   * TODO(developer): Uncomment the following line before running the sample.
   */
  // const fileName = 'Local image file, e.g. /path/to/image.png';

  const [result] = await client.faceDetection(fileName);
  const faces = result.faceAnnotations;
  console.log('Faces:');
  faces.forEach((face, i) => {
    console.log(`  Face #${i + 1}:`);
    console.log(`    Joy: ${face.joyLikelihood}`);
    console.log(`    Anger: ${face.angerLikelihood}`);
    console.log(`    Sorrow: ${face.sorrowLikelihood}`);
    console.log(`    Surprise: ${face