このトピックでは、imageScan 操作を呼び出してカスタム顔を検索する方法について説明します。カスタム顔検索は、指定された個人ライブラリから特定の顔画像を取得し、ターゲットに最も類似している上位 5 人の個人を返すことができます。
シナリオ
カスタム顔検索は、顔認識のために渡された顔画像（face）に基づいて、最も類似している上位 5 人の個人（person）を検索して返します。返される上位 5 人の個人は、類似度によって大きい順にソートされます。
パラメーター | 説明 | 関連 API 操作 |
person | 個人。自然人を示します。 | |
face | 顔。個人に関連付けられた顔画像を示します。 1 人の個人に複数の顔画像を関連付けることができます。 | |
group | 個人グループ。個人の集合を表します。 1 人の個人は複数のグループに所属でき、1 つのグループには複数の個人が含まれる場合もあります。 |
説明
imageScan 操作を呼び出して、同期画像検出タスクを作成できます。HTTP リクエストを作成する方法の詳細については、「リクエスト構造」をご参照ください。既存の HTTP リクエストを選択することもできます。詳細については、「SDK の概要」をご参照ください。
課金方法:
この操作の呼び出しには料金が発生します。課金方法の詳細については、 をご参照ください。
応答タイムアウト:
同期モデレーションリクエストで許容される最大応答時間は 6 秒です。6 秒以内にモデレーションが完了しない場合は、タイムアウトエラーが返されます。モデレーション結果をリアルタイムで必要としない場合は、非同期モデレーションリクエストを送信できます。ほとんどの場合、同期モデレーション操作の方が呼び出しやすいため、同期モデレーションリクエストを送信することをお勧めします。同期モデレーション操作を呼び出す場合は、タイムアウト期間を 6 秒に設定することをお勧めします。
結果の返却:
通常、モデレーション結果は、同期モデレーションリクエストを送信してから 1 秒以内に返されます。システムで処理されるリクエストの数が多い場合、画像のサイズが大きい場合、または画像に多くの単語が含まれている場合は、時間が長くなることがあります。
画像の制限:
画像の URL は、HTTP または HTTPS URL である必要があります。
画像は PNG、JPG、JPEG、BMP、GIF、または WEBP 形式である必要があります。
画像のサイズは最大 20 MB です。画像サイズの制限は、同期および非同期モデレーション操作の両方に適用されます。
画像のダウンロード時間は 3 秒に制限されています。3 秒以内に画像をダウンロードできない場合は、タイムアウトエラーが返されます。
モデレーション効果を確保するために、少なくとも 256 × 256 ピクセルの画像を送信することをお勧めします。
画像をモデレーションする操作の応答時間は、これらの画像のダウンロード時間によって異なります。モデレーション対象の画像を保存するには、安定した信頼性の高いストレージサービスを使用してください。Object Storage Service (OSS) または Content Delivery Network (CDN) を使用することをお勧めします。
QPS 制限
この操作は、アカウントごとに 1 秒あたり最大 50 回呼び出すことができます。1 秒あたりの呼び出し数が制限を超えると、速度制限がトリガーされます。その結果、ビジネスに影響が及ぶ可能性があります。この操作を呼び出すときは、制限に注意することをお勧めします。
リクエスト構文
POST /green/image/scan HTTPS|HTTPリクエストヘッダー
この操作では、共通のリクエストヘッダーのみを使用します。詳細については、「共通リクエストヘッダー」をご参照ください。
リクエストパラメーター
パラメーター | タイプ | 必須 | 例 | 説明 |
clientInfo | JSONObject | いいえ | {"userId":"120234234","userNick":"Mike","userType":"others"} | ClientInfo 構造から JSON 形式でシリアル化されたクライアント情報。情報には、クライアントの一意のマシン識別子（UMID）と国際モバイル機器識別子（IMEI）が含まれます。詳細については、「ClientInfo」をご参照ください。 |
リクエストボディ
モデレーションシナリオとタスク情報を指定するには、リクエストボディで次のパラメーターも指定する必要があります。
パラメーター | タイプ | 必須 | 例 | 説明 |
bizType | String | いいえ | edu | ビジネスシナリオのタイプ。カスタム顔検索シナリオでは、このパラメーターを指定する必要はありません。 |
scenes | StringArray | はい | ["sface-n"] | 検出シナリオ。値: sface-n。カスタム顔検索を示します。 |
tasks | JSONArray | はい | 検出対象の顔画像に関する情報。構造の詳細については、「task」をご参照ください。 |
表 1. task
パラメーター | タイプ | 必須 | 例 | 説明 |
dataId | String | いいえ | test2NInmOtAON6qYUrtCRgLo-1mwxdi | モデレーションオブジェクトの ID。 ID には、文字、数字、アンダースコア（_）、ハイフン（-）、およびピリオド（.）を含めることができます。長さは最大 128 文字です。この ID は、ビジネスデータを一意に識別します。 |
url | String | はい | https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png | 検出対象の顔画像の URL。 |
extras | JSONObject | はい | {"groupId":"group"} | 追加のリクエストパラメーターについては、検出対象の画像と比較する個人グループの ID（groupId）を指定します。 /green/sface/groups を呼び出して、すべての個人グループ ID をクエリできます。 |
レスポンスパラメーター
JSON 形式のデータがすべてのリクエストに対して返されます。共通レスポンスパラメーターの詳細については、「共通レスポンスパラメーター」をご参照ください。レスポンスの data パラメーターは、ビジネス関連データを返すために使用されます。通常、このパラメーターの値は JSON 構造または配列です。
エラーが発生した場合、data パラメーターは空になる場合があります。
次の表は、data フィールドで返されるパラメーターについて説明しています。
パラメーター | タイプ | 例 | 説明 |
code | Integer | 200 | 返される HTTP ステータスコード。 詳細については、「共通エラーコード」をご参照ください。 |
results | JSONArray | 戻り値。呼び出しが成功した場合（code=200）、返される結果には 1 つ以上の結果要素が含まれます。各結果要素は構造体です。構造体の詳細については、「result」をご参照ください。 |
表 2. result
パラメーター | タイプ | 例 | 説明 |
scene | String | sface-n | 検出シナリオ。値: sface-n。カスタム顔検索を示します。 |
label | String | sface-n | 検出結果のカテゴリ。有効な値:
|
suggestion | String | review | モデレートされた音声の機械支援モデレーション結果。有効な値:
|
rate | Float | 0.999 | 結果が現在のカテゴリに属する確率。有効な値: 0.00 ～ 1.00。値が大きいほど、音声がこのカテゴリに分類される確率が高くなります。 |
topPersonData | JSONArray | ターゲットの顔画像に最も類似している上位 5 人の個人の情報。構造体の詳細については、「topPersonData」をご参照ください。 説明 類似する個人が取得されない場合は、null 値が返されます。 |
表 3. topPersonData
パラメーター | タイプ | 例 | 説明 |
persons | JSONArray | 上位 5 件が個人の情報と一致します。構造体の詳細については、「person」をご参照ください。 | |
faceItem | JSONObject | 画像内の顔属性を検出します。構造体の詳細については、「faceItem」をご参照ください。 |
表 4. person
パラメーター | タイプ | 例 | 説明 |
personId | String | person1 | 一致した個人の ID。 |
faceId | String | 14736649593638 | 個人と一致する顔画像の ID。 |
rate | Float | 0.999 | 個人の一致確率。一致確率が高いほど、対応する誤認識率は低くなります。次のように表示されます。
一致確率の値が 0.9 以上の結果を使用することをお勧めします。 |
表 5. faceItem
パラメーター | タイプ | 例 | 説明 |
x | Float | 467 | x 軸上の顔の座標。単位: ピクセル。 |
y | Float | 199 | y 軸上の顔の座標。単位: ピクセル。 |
width | Float | 422 | 顔の幅。単位: ピクセル。 |
height | Float | 422 | 顔の高さ。単位: ピクセル。 |
例
リクエストの例
POST /green/image/scan HTTP/1.1
共通リクエストヘッダー
{
"scenes": [
"sface-n"
],
"tasks": [
{
"dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png",
"extras": {
"groupId": "group"
}
}
]
}成功レスポンスの例
{
"code": 200,
"data": [
{
"code": 200,
"dataId": "test2NInmOtAON6qYUrtCRgLo-1mwxdi",
"msg": "呼び出しは成功しました。",
"results": [
{
"topPersonData": [
{
"faceItem": {
"height": 422,
"width": 422,
"x": 467,
"y": 199
},
"persons": [
{
"faceId": "14736649593638",
"personId": "person1",
"rate": "0.999"
},
{
"faceId": "14736649593637",
"personId": "person2",
"rate": "0.998"
}
]
}
],
"label": "sface-n",
"rate": 0.999,
"scene": "sface-n",
"suggestion": "review"
}
],
"taskId": "img2MVcKPU1QGD64LoAb4cK6w-1mwxdi",
"url": "https://example.com/tfs/TB1urBOQFXXXXbMXFXXXXXXXXXX-1442-257.png"
}
],
"msg": "OK",
"requestId": "36D384DA-8023-4E84-BCFD-0C5581352C16"
}