次の方法で共有


Face - Detect With Stream

画像内の人間の顔を検出し、顔の四角形を返し、必要に応じて faceId、ランドマーク、属性を使用します。

  • イメージは保存されません。 抽出された顔機能のみがサーバーに格納されます。 faceId は顔の特徴の識別子であり、顔 -の識別、顔 -の確認、および顔の - 類似したの検索で使用されます。 保存された顔機能は有効期限が切れ、元の検出呼び出しの後に faceIdTimeToLive で指定された時刻に削除されます。
  • 省略可能なパラメーターには、faceId、ランドマーク、属性が含まれます。 属性には、年齢、性別、headPose、smile、facialHair、眼鏡、感情、ヘア、メイク、オクルージョン、アクセサリー、ぼかし、露出、ノイズ、マスク、qualityForRecognition が含まれます。 特定の属性に対して返される結果の一部は、精度が高くない場合があります。
  • JPEG、PNG、GIF (最初のフレーム)、BMP 形式がサポートされています。 許可されるイメージ ファイルのサイズは 1 KB から 6 MB です。
  • 画像に対して最大 100 個の顔を返すことができます。 顔は、大きいから小さい顔の四角形のサイズでランク付けされます。
  • Face - IdentifyFace - Verify、および Face - Find Similar ('returnFaceId' is true) をクエリする場合に最適な結果を得るには、正面、クリア、最小サイズ 200 x 200 ピクセル (目の間に 100 ピクセル) の顔を使用してください。
  • 検出可能な顔の最小サイズは、1920 x 1080 ピクセル以下の画像では 36 x 36 ピクセルです。 サイズが 1920 x 1080 ピクセルを超える画像では、顔の最小サイズが比例して大きくなる必要があります。
  • 異なる 'detectionModel' 値を指定できます。 さまざまな検出モデルを使用して比較するには、「検出モデルを指定する方法」を参照してください
  • 異なる 'recognitionModel' 値が提供されます。 Verify、Identify、Find Similar などのフォローアップ操作が必要な場合は、"recognitionModel" パラメーターを使用して認識モデルを指定してください。 'recognitionModel' の既定値は 'recognition_01' です。最新のモデルが必要な場合は、このパラメーターで必要なモデルを明示的に指定してください。 指定すると、検出された faceId は、指定された認識モデルに関連付けられます。 詳細については、「認識モデルの指定 を参照してください。
POST {Endpoint}/face/v1.0-preview/detect
POST {Endpoint}/face/v1.0-preview/detect?overload=stream&returnFaceId={returnFaceId}&returnFaceLandmarks={returnFaceLandmarks}&returnFaceAttributes={returnFaceAttributes}&recognitionModel={recognitionModel}&returnRecognitionModel={returnRecognitionModel}&detectionModel={detectionModel}&faceIdTimeToLive={faceIdTimeToLive}

URI パラメーター

名前 / 必須 説明
Endpoint
path True

string

サポートされている Cognitive Services エンドポイント (プロトコルとホスト名、例: https://westus.api.cognitive.microsoft.com)。

detectionModel
query

DetectionModel

検出モデルの名前。 検出モデルは、送信された画像内の顔を検出するために使用されます。 検出モデル名は、Face - Detect または (Large)FaceList - Add Face or (Large)PersonGroup - Add Face の実行時に指定できます。 既定値は 'detection_01' です。別のモデルが必要な場合は、明示的に指定してください。

faceIdTimeToLive
query

integer

minimum: 60
maximum: 86400

キャッシュされる faceId の秒数。 サポートされる範囲は、60 秒から 8,6400 秒までです。 既定値は 86400 (24 時間) です。

recognitionModel
query

RecognitionModel

認識モデルの名前。 認識モデルは、顔の特徴が抽出され、検出された faceIds、(Large)FaceList、または (Large)PersonGroup に関連付けられている場合に使用されます。 認識モデル名は、Face - Detect または (Large)FaceList - Create または (Large)PersonGroup - Create の実行時に指定できます。 既定値は "recognition_01" です。最新のモデルが必要な場合は、必要なモデルを明示的に指定してください。

returnFaceAttributes
query

FaceAttributeType[]

"returnFaceAttributes=age,gender" のようなコンマ区切りの文字列で、指定された 1 つ以上の顔属性を分析して返します。 使用可能な属性は、指定された 'detectionModel' によって異なります。 'detection_01' は年齢、性別、headPose、smile、facialHair、glasses、emotion、hair、makeup、occlusion、accessories、blur、exposure、noise、qualityForRecognition をサポートします。 'detection_02' は属性をサポートせず、'detection_03' は mask と qualityForRecognition のみをサポートします。 さらに、qualityForRecognition は、'recognitionModel' が 'recognition_03' または 'recognition_04' として指定されている場合にのみサポートされます。 各顔属性分析には、追加の計算コストと時間コストがあることに注意してください。

returnFaceId
query

boolean

操作が検出された顔の faceId を返す必要があるかどうかを示す値。 この値を true に設定して検出するには、https://aka.ms/facerecognitionで追加のアクセス承認が必要です。

returnFaceLandmarks
query

boolean

操作が検出された顔のランドマークを返す必要があるかどうかを示す値。

returnRecognitionModel
query

boolean

操作が応答で 'recognitionModel' を返す必要があるかどうかを示す値。

要求ヘッダー

Media Types: "application/octet-stream"

名前 必須 説明
Ocp-Apim-Subscription-Key True

string

要求本文

Media Types: "application/octet-stream"

名前 説明
Image

object (file)

イメージ ストリーム。

応答

名前 説明
200 OK

DetectedFace[]

呼び出しが成功すると、顔の四角形のサイズで降順にランク付けされた顔エントリの配列が返されます。 空の応答は、顔が検出されていないことを示します。

Other Status Codes

APIError

エラー応答。

セキュリティ

Ocp-Apim-Subscription-Key

型: apiKey
/: header

Detect with stream example

要求のサンプル

POST {Endpoint}/face/v1.0-preview/detect?overload=stream&returnFaceAttributes=age,gender,headPose,smile,facialHair,glasses,emotion,hair,makeup,occlusion,accessories,blur,exposure,noise&recognitionModel=recognition_01&returnRecognitionModel=True&detectionModel=detection_01


"{Image binary in base 64 format}"

応答のサンプル

[
  {
    "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
    "recognitionModel": "recognition_01",
    "faceRectangle": {
      "width": 78,
      "height": 78,
      "left": 394,
      "top": 54
    },
    "faceLandmarks": {
      "pupilLeft": {
        "x": 412.7,
        "y": 78.4
      },
      "pupilRight": {
        "x": 446.8,
        "y": 74.2
      },
      "noseTip": {
        "x": 437.7,
        "y": 92.4
      },
      "mouthLeft": {
        "x": 417.8,
        "y": 114.4
      },
      "mouthRight": {
        "x": 451.3,
        "y": 109.3
      },
      "eyebrowLeftOuter": {
        "x": 397.9,
        "y": 78.5
      },
      "eyebrowLeftInner": {
        "x": 425.4,
        "y": 70.5
      },
      "eyeLeftOuter": {
        "x": 406.7,
        "y": 80.6
      },
      "eyeLeftTop": {
        "x": 412.2,
        "y": 76.2
      },
      "eyeLeftBottom": {
        "x": 413,
        "y": 80.1
      },
      "eyeLeftInner": {
        "x": 418.9,
        "y": 78
      },
      "eyebrowRightInner": {
        "x": 4.8,
        "y": 69.7
      },
      "eyebrowRightOuter": {
        "x": 5.5,
        "y": 68.5
      },
      "eyeRightInner": {
        "x": 441.5,
        "y": 75
      },
      "eyeRightTop": {
        "x": 446.4,
        "y": 71.7
      },
      "eyeRightBottom": {
        "x": 447,
        "y": 75.3
      },
      "eyeRightOuter": {
        "x": 451.7,
        "y": 73.4
      },
      "noseRootLeft": {
        "x": 428,
        "y": 77.1
      },
      "noseRootRight": {
        "x": 435.8,
        "y": 75.6
      },
      "noseLeftAlarTop": {
        "x": 428.3,
        "y": 89.7
      },
      "noseRightAlarTop": {
        "x": 442.2,
        "y": 87
      },
      "noseLeftAlarOutTip": {
        "x": 424.3,
        "y": 96.4
      },
      "noseRightAlarOutTip": {
        "x": 446.6,
        "y": 92.5
      },
      "upperLipTop": {
        "x": 437.6,
        "y": 105.9
      },
      "upperLipBottom": {
        "x": 437.6,
        "y": 108.2
      },
      "underLipTop": {
        "x": 436.8,
        "y": 111.4
      },
      "underLipBottom": {
        "x": 437.3,
        "y": 114.5
      }
    },
    "faceAttributes": {
      "age": 71,
      "gender": "male",
      "smile": 0.88,
      "facialHair": {
        "moustache": 0.8,
        "beard": 0.1,
        "sideburns": 0.02
      },
      "glasses": "sunglasses",
      "headPose": {
        "roll": 2.1,
        "yaw": 3,
        "pitch": 1.6
      },
      "emotion": {
        "anger": 0.575,
        "contempt": 0,
        "disgust": 0.006,
        "fear": 0.008,
        "happiness": 0.394,
        "neutral": 0.013,
        "sadness": 0,
        "surprise": 0.004
      },
      "hair": {
        "bald": 0,
        "invisible": false,
        "hairColor": [
          {
            "color": "brown",
            "confidence": 1
          },
          {
            "color": "blond",
            "confidence": 0.88
          },
          {
            "color": "black",
            "confidence": 0.48
          },
          {
            "color": "other",
            "confidence": 0.11
          },
          {
            "color": "gray",
            "confidence": 0.07
          },
          {
            "color": "red",
            "confidence": 0.03
          }
        ]
      },
      "makeup": {
        "eyeMakeup": true,
        "lipMakeup": false
      },
      "occlusion": {
        "foreheadOccluded": false,
        "eyeOccluded": false,
        "mouthOccluded": false
      },
      "accessories": [
        {
          "type": "headWear",
          "confidence": 0.99
        },
        {
          "type": "glasses",
          "confidence": 1
        },
        {
          "type": "mask",
          "confidence": 0.87
        }
      ],
      "blur": {
        "blurLevel": "Medium",
        "value": 0.51
      },
      "exposure": {
        "exposureLevel": "GoodExposure",
        "value": 0.55
      },
      "noise": {
        "noiseLevel": "Low",
        "value": 0.12
      }
    }
  }
]

定義

名前 説明
Accessory

アクセサリアイテムと対応する信頼度レベル。

AccessoryType

アクセサリの種類

APIError

API によって返されるエラー情報

Blur

イメージ内のぼかしの存在を記述するプロパティ。

BlurLevel

ぼかしのレベルを示す列挙値。

Coordinate

画像内の座標

DetectedFace

Face オブジェクトが検出されました。

DetectionModel

顔を抽出するときに使用される検出モデル。

Emotion

0 から 1 までの信頼の形で顔の感情を記述するプロパティ。

Error

エラー本文。

Exposure

画像の露出レベルを記述するプロパティ。

ExposureLevel

露出のレベルを示す列挙値。

FaceAttributes

Face 属性

FaceAttributeType

"returnFaceAttributes=age,gender" のようなコンマ区切りの文字列で、指定された 1 つ以上の顔属性を分析して返します。 使用可能な属性は、指定された 'detectionModel' によって異なります。 'detection_01' は年齢、性別、headPose、smile、facialHair、glasses、emotion、hair、makeup、occlusion、accessories、blur、exposure、noise、qualityForRecognition をサポートします。 'detection_02' は属性をサポートせず、'detection_03' は mask と qualityForRecognition のみをサポートします。 さらに、qualityForRecognition は、'recognitionModel' が 'recognition_03' または 'recognition_04' として指定されている場合にのみサポートされます。 各顔属性分析には、追加の計算コストと時間コストがあることに注意してください。

FaceLandmarks

顔コンポーネントの重要な位置を指す 27 ポイントの顔ランドマークのコレクション。

FaceRectangle

顔が見つかる四角形

FacialHair

顔の毛の属性を記述するプロパティ。

Gender

顔の可能性のある性別。

GlassesType

眼鏡の種類は、いずれかの顔の場合です。

Hair

ヘア属性を記述するプロパティ。

HairColor

髪の色と関連する信頼度

HairColorType

髪の色の名前。

HeadPose

顔の頭部姿勢を示すプロパティ。

Makeup

特定の顔のメイクの存在を記述するプロパティ。

Mask

特定の顔にマスクが存在することを示すプロパティ。

MaskType

顔のいずれかが存在する場合はマスクの種類

Noise

画像のノイズ レベルを記述するプロパティ。

NoiseLevel

ノイズのレベルを示す列挙値。

Occlusion

特定の顔のオクルージョンを記述するプロパティ。

QualityForRecognition

検出に使用されている画像が顔認識を試みるために十分な品質であるかどうかに関する全体的な画質を記述するプロパティ。

RecognitionModel

認識モデルの名前。 認識モデルは、顔の特徴が抽出され、検出された faceIds、(Large)FaceList、または (Large)PersonGroup に関連付けられている場合に使用されます。 認識モデル名は、Face - Detect または (Large)FaceList - Create または (Large)PersonGroup - Create の実行時に指定できます。 既定値は "recognition_01" です。最新のモデルが必要な場合は、必要なモデルを明示的に指定してください。

Accessory

アクセサリアイテムと対応する信頼度レベル。

名前 説明
confidence

number

minimum: 0
maximum: 1

アクセサリの信頼度レベル

type

AccessoryType

アクセサリの種類

AccessoryType

アクセサリの種類

説明
glasses
headWear
mask

APIError

API によって返されるエラー情報

名前 説明
error

Error

エラー本文。

Blur

イメージ内のぼかしの存在を記述するプロパティ。

名前 説明
blurLevel

BlurLevel

ぼかしのレベルを示す列挙値。

value

number

minimum: 0
maximum: 1

0 ~ 1 の範囲のぼかしのレベルを示す数値。

BlurLevel

ぼかしのレベルを示す列挙値。

説明
High
Low
Medium

Coordinate

画像内の座標

名前 説明
x

number

水平方向のコンポーネント (ピクセル単位)。

y

number

垂直方向のコンポーネント (ピクセル単位)。

DetectedFace

Face オブジェクトが検出されました。

名前 規定値 説明
faceAttributes

FaceAttributes

Face 属性

faceId

string (uuid)

faceLandmarks

FaceLandmarks

顔コンポーネントの重要な位置を指す 27 ポイントの顔ランドマークのコレクション。

faceRectangle

FaceRectangle

顔が見つかる四角形

recognitionModel

RecognitionModel

recognition_01

認識モデルの名前。 認識モデルは、顔の特徴が抽出され、検出された faceIds、(Large)FaceList、または (Large)PersonGroup に関連付けられている場合に使用されます。 認識モデル名は、Face - Detect または (Large)FaceList - Create または (Large)PersonGroup - Create の実行時に指定できます。 既定値は "recognition_01" です。最新のモデルが必要な場合は、必要なモデルを明示的に指定してください。

DetectionModel

顔を抽出するときに使用される検出モデル。

説明
detection_01
detection_02
detection_03
detection_preview_1904
expression_01
ir_detection_01

Emotion

0 から 1 までの信頼の形で顔の感情を記述するプロパティ。

名前 説明
anger

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

contempt

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

disgust

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

fear

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

happiness

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

neutral

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

sadness

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

surprise

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

Error

エラー本文。

名前 説明
code

string

message

string

Exposure

画像の露出レベルを記述するプロパティ。

名前 説明
exposureLevel

ExposureLevel

露出のレベルを示す列挙値。

value

number

minimum: 0
maximum: 1

0 ~ 1 の範囲の露出レベルを示す数値。 [0, 0.25) が露出している。 [0.25, 0.75) は良好な露出です。 [0.75, 1]は露出超過です。

ExposureLevel

露出のレベルを示す列挙値。

説明
GoodExposure
OverExposure
UnderExposure

FaceAttributes

Face 属性

名前 説明
accessories

Accessory[]

特定の顔のアクセサリを記述するプロパティ。

age

number

年齢 (年単位)

blur

Blur

イメージ内のぼかしの存在を記述するプロパティ。

emotion

Emotion

0 から 1 までの信頼の形で顔の感情を記述するプロパティ。

exposure

Exposure

画像の露出レベルを記述するプロパティ。

facialHair

FacialHair

顔の毛の属性を記述するプロパティ。

gender

Gender

顔の可能性のある性別。

glasses

GlassesType

眼鏡の種類は、いずれかの顔の場合です。

hair

Hair

ヘア属性を記述するプロパティ。

headPose

HeadPose

顔の頭部姿勢を示すプロパティ。

makeup

Makeup

特定の顔のメイクの存在を記述するプロパティ。

mask

Mask

特定の顔にマスクが存在することを示すプロパティ。

noise

Noise

画像のノイズ レベルを記述するプロパティ。

occlusion

Occlusion

特定の顔のオクルージョンを記述するプロパティ。

qualityForRecognition

QualityForRecognition

検出に使用されている画像が顔認識を試みるために十分な品質であるかどうかに関する全体的な画質を記述するプロパティ。

smile

number

minimum: 0
maximum: 1

笑顔の強さ、[0,1] の間の数値

FaceAttributeType

"returnFaceAttributes=age,gender" のようなコンマ区切りの文字列で、指定された 1 つ以上の顔属性を分析して返します。 使用可能な属性は、指定された 'detectionModel' によって異なります。 'detection_01' は年齢、性別、headPose、smile、facialHair、glasses、emotion、hair、makeup、occlusion、accessories、blur、exposure、noise、qualityForRecognition をサポートします。 'detection_02' は属性をサポートせず、'detection_03' は mask と qualityForRecognition のみをサポートします。 さらに、qualityForRecognition は、'recognitionModel' が 'recognition_03' または 'recognition_04' として指定されている場合にのみサポートされます。 各顔属性分析には、追加の計算コストと時間コストがあることに注意してください。

説明
accessories
age
blur
emotion
exposure
facialHair
gender
glasses
hair
headPose
makeup
mask
noise
occlusion
qualityForRecognition
smile

FaceLandmarks

顔コンポーネントの重要な位置を指す 27 ポイントの顔ランドマークのコレクション。

名前 説明
eyeLeftBottom

Coordinate

画像内の座標

eyeLeftInner

Coordinate

画像内の座標

eyeLeftOuter

Coordinate

画像内の座標

eyeLeftTop

Coordinate

画像内の座標

eyeRightBottom

Coordinate

画像内の座標

eyeRightInner

Coordinate

画像内の座標

eyeRightOuter

Coordinate

画像内の座標

eyeRightTop

Coordinate

画像内の座標

eyebrowLeftInner

Coordinate

画像内の座標

eyebrowLeftOuter

Coordinate

画像内の座標

eyebrowRightInner

Coordinate

画像内の座標

eyebrowRightOuter

Coordinate

画像内の座標

mouthLeft

Coordinate

画像内の座標

mouthRight

Coordinate

画像内の座標

noseLeftAlarOutTip

Coordinate

画像内の座標

noseLeftAlarTop

Coordinate

画像内の座標

noseRightAlarOutTip

Coordinate

画像内の座標

noseRightAlarTop

Coordinate

画像内の座標

noseRootLeft

Coordinate

画像内の座標

noseRootRight

Coordinate

画像内の座標

noseTip

Coordinate

画像内の座標

pupilLeft

Coordinate

画像内の座標

pupilRight

Coordinate

画像内の座標

underLipBottom

Coordinate

画像内の座標

underLipTop

Coordinate

画像内の座標

upperLipBottom

Coordinate

画像内の座標

upperLipTop

Coordinate

画像内の座標

FaceRectangle

顔が見つかる四角形

名前 説明
height

integer (int32)

四角形の高さ (ピクセル単位)。

left

integer (int32)

画像から四角形の左端までの距離 (ピクセル単位)。

top

integer (int32)

画像が四角形の上端までの場合の上端からの距離 (ピクセル単位)。

width

integer (int32)

四角形の幅 (ピクセル単位)。

FacialHair

顔の毛の属性を記述するプロパティ。

名前 説明
beard

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

moustache

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

sideburns

number

minimum: 0
maximum: 1

プロパティに関連付けられている信頼度のレベルを示す 0 から 1 までの範囲の数値。

Gender

顔の可能性のある性別。

説明
female
male

GlassesType

眼鏡の種類は、いずれかの顔の場合です。

説明
noGlasses
readingGlasses
sunglasses
swimmingGoggles

Hair

ヘア属性を記述するプロパティ。

名前 説明
bald

number

minimum: 0
maximum: 1

その人がはげかどうかを示す信頼度レベルを表す数値。

hairColor

HairColor[]

それぞれの存在する候補の色と信頼度レベルの配列。

invisible

boolean

イメージにヘアが表示されるかどうかを示すブール値。

HairColor

髪の色と関連する信頼度

名前 説明
color

HairColorType

髪の色の名前。

confidence

number

minimum: 0
maximum: 1

色の信頼度レベル

HairColorType

髪の色の名前。

説明
black
blond
brown
gray
other
red
unknown
white

HeadPose

顔の頭部姿勢を示すプロパティ。

名前 説明
pitch

number

roll

number

yaw

number

Makeup

特定の顔のメイクの存在を記述するプロパティ。

名前 説明
eyeMakeup

boolean

顔にアイ メイクが存在するかどうかを示すブール値。

lipMakeup

boolean

顔にリップ メイクが存在するかどうかを示すブール値。

Mask

特定の顔にマスクが存在することを示すプロパティ。

名前 説明
noseAndMouthCovered

boolean

鼻と口が覆われているかどうかを示すブール値。

type

MaskType

顔のいずれかが存在する場合はマスクの種類

MaskType

顔のいずれかが存在する場合はマスクの種類

説明
faceMask
noMask
otherMaskOrOcclusion
uncertain

Noise

画像のノイズ レベルを記述するプロパティ。

名前 説明
noiseLevel

NoiseLevel

ノイズのレベルを示す列挙値。

value

number

minimum: 0
maximum: 1

0 ~ 1 の範囲のノイズ レベルを示す数値。 [0, 0.25) が露出している。 [0.25, 0.75) は良好な露出です。 [0.75, 1]は露出超過です。 [0, 0.3) は低ノイズ レベルです。 [0.3, 0.7) は中程度のノイズ レベルです。 [0.7, 1]はノイズレベルが高い。

NoiseLevel

ノイズのレベルを示す列挙値。

説明
High
Low
Medium

Occlusion

特定の顔のオクルージョンを記述するプロパティ。

名前 説明
eyeOccluded

boolean

目が隠れているかどうかを示すブール値。

foreheadOccluded

boolean

額が隠れているかどうかを示すブール値。

mouthOccluded

boolean

口が隠れているかどうかを示すブール値。

QualityForRecognition

検出に使用されている画像が顔認識を試みるために十分な品質であるかどうかに関する全体的な画質を記述するプロパティ。

説明
High
Low
Medium

RecognitionModel

認識モデルの名前。 認識モデルは、顔の特徴が抽出され、検出された faceIds、(Large)FaceList、または (Large)PersonGroup に関連付けられている場合に使用されます。 認識モデル名は、Face - Detect または (Large)FaceList - Create または (Large)PersonGroup - Create の実行時に指定できます。 既定値は "recognition_01" です。最新のモデルが必要な場合は、必要なモデルを明示的に指定してください。

説明
recognition_01
recognition_02
recognition_03
recognition_04